Docs: update migration guide.

docs/updating/update-to-40.md

@@ -28,6 +28,18 @@ The `srcset` model attribute which provides parameters for responsive images, ha
 
 Last but not least, content styles have been updated with this release, which means you need to update them in your editor implementation to avoid any discrepancies. Please refer to the {@link installation/advanced/content-styles Content styles} guide to learn how to generate the stylesheet.
 
+### Changes to the comments feature
+
+The comment thread's **resolved** state has been separated from the **unlinked** state (a state, when the related editor content was removed from the document). A thread can now have any combination of these states, so if a comment thread is either **resolved** or **unlinked**, it is moved to the comments archive. This new approach is reflected in the comments archive UI. Notably, an **unlinked** comment thread can become resolved and reopened while still being in the comments archive. Additionally, the **unlinked** comment threads have a gray header color to differentiate them from the **resolved** comment threads.
+
+The `Comment#archivedAt` property is now the property to check when deciding whether the comment thread is inside the comments archive or not (that property was `#resolvedAt` before).
+
+The `CommentsArchive#resolvedThreads` property has been renamed to `#archivedThreads`. If your custom code used that property, make sure to apply this change.
+
+The `deletedAt` property is no longer passed in `AddCommentThreadEvent` as it is not needed anymore. Deleted comment threads should never be added to the repository, so they should not be handled in `addCommentThread`. If your custom code used that property, make sure to apply this change.
+
+In a real-time collaboration environment, removed comment threads will no longer be added to `CommentsRepository` after re-initializing the editor. Before, the comment thread was removed from `CommentsRepository` but was added back when the editor re-connected to Cloud Services. If your custom code expected the old (incorrect) behavior, it might need a change. This change was reflected in the {@link features/comments-outside-editor comments outside the editor} guide.
+
 ### New Balloon Block editor icon
 
 We have changed the default {@link features/blocktoolbar Balloon Block editor toolbar} indicator icon from the pilcrow icon (`¶`) to the braille pattern dots icon (`⠿`). The new icon better corresponds to the dual function of the indicator, which may be used to both invoke the balloon toolbar and to drag to content block around.