Support for comments

[marshall-mcmullen]

We love confluencebuilder so much! One of the things that we are trying to find a good solution for though is that when people outside our team make in-line comments on our published confluence pages, and then we publish new docs later that night, those comments get blown away.

The comments at the bottom of the page are fine, but in-line comments get lost. And that kind of makes sense.

I'm curious if you guys have a recommended solution or workaround for this? Or if this is something that could be thought about or investigated to find a good solution or workaround.

Thank you so much for your awesome tool. We use it every day.

[jdknight]

Took a look at this to see how this could be achieved. For sure there is not trivial way to address this at this time. It may be possible to support some level of inline comment retention, but it would require doing things this extension was never designed to do.

Notables are as follows:

1. Confluence at this time does not provide a way to query the contents of inline comments. So there would not be a way to (re)create comment entities if desired; however, that may not be needed for this feature. It appears when a user makes an inline comment, Confluence will inject ac:inline-comment-marker tags inside the source. Each of these tags includes a UUID value (inside a ac:ref attribute). If a user was to edit a page (or if we re-publish a page) using a comment marker with the same UUID, it will properly bind to the expected comment bubble/tree. This means we should have a way to re-inject these inline comments.

2. The one of the biggest problems with trying to re-insert comments it knowing if comments existed in the pages to be updated. To do this, page requests to Confluence (where we fetch page IDs, metadata, etc.), would now also require fetching the content of these pages (to be parsed/etc.). This could add some extra time for publishing -- which can be acceptable for users who want to maintain inline comments. This means that if we were to introduce such a capability, it would not be an automatic feature. We would most likely have a user option where one would need to explicitly configure to check and maintain comments (since we don't want to slow down other instances which do not use/care about these inline comments).

3. The hardest part is trying to find a way to diff/compare the original text with the next, and re-applying these comments. Some thought would need to be put into this -- ensuring we always use the most recent content to be published, and only inject inline comments if it is "added" and not replacing commented text. I assume there will be cases where conflicts may be detected, and the best way forward would be that any conflicting inline comments would be automatically removed.

At this time, there is no plans to implement this feature. We could possibly do something down the line to add support (next year at the earliest), but the maintenance time allocated (at least for myself) will first be focusing on providing some level of a v2 editor (experimental) support. Although if someone from the community wanted to take a stab at this, I would be happy to help review proposed merge requests to bring support for this capability.

[jdknight]

It appears Confluence now has comment-related API options for its REST v2 API. We should be able to provide some helper options related to inlined comments... although do not get too excited.

When playing with these options, it looks like there are two basic capabilities we can introduce into this extension:

1. The ability to skip (and warn) when publishing page updates to a page with inlined comments. Detecting comments on a page is easy. However, knowing if comments are resolved requires invoking some API calls. We can add a option confluence_publish_skip_commented_pages that when it detects a comment on a page update, it performs a query to see if any comment references are unresolved. If so, it will not publish a page update. I assume such an option may be helpful for some project/user workflows.
2. The second option is somewhat related to preserving unresolved comments. There is no graceful way to give a perfect preservation some users may be looking for (in a way, trying to do patching and re-inject comment markdown -- at least, it is a bit too complex for what this extension tries to resolve; we can expose a hook which users could try manipulation themselves if desired). But what we could do is inject data at the tail end of a page with a section called "Unresolved comments" and have a crude list of inlined comment entries. This can help prevent any unresolved dangling comments from being "lost", although it's presentation would be very rough (especially since there will be no comment data context).

For sure the first option can be done (and is somewhat planned to be added next release, if possible). The second option may be done (if user who use inlined comments think it would be helpful to add, please provide feedback). After these, there most likely will not be any other capabilities added to this extension with respect to inlined comments (which in turn we would close this request).

We will see how this plays out this next cycle. No timelines or guarantees at this time.

[artyompetrov]

Please check out similar tool that publishes Markdown to confluence. They somehow managed to implement support for comments feature

https://foliant-docs.github.io/docs/backends/confluence/

[adamtheturtle]

The ability to skip (and warn) when publishing page updates to a page with inlined comments. Detecting comments on a page is easy. However, knowing if comments are resolved requires invoking some API calls. We can add a option confluence_publish_skip_commented_pages that when it detects a comment on a page update, it performs a query to see if any comment references are unresolved. If so, it will not publish a page update. I assume such an option may be helpful for some project/user workflows.

@jdknight To confirm your assumption. For me, having an option to error on publishing a page update which will wipe comments would be very helpful. I assume that the "and warn" would mean that I can get an error with Sphinx's -W.