Edit PR's description or add a new comment

[humitos]

The action currently edits the PR description to add a separator and below that the links.

It would be good if we can also support adding a new comment the first time and after that update the comment with the newer links, if any. Then, the user could choose the approach that like the most.

Both approaches have pros/cons that is worth considering.

[benjaoming]

I like comments because:

1. It's conventional (other similar types of integrations do the same), and we can make "bot" appear next to the commenting profile.
2. It generates notifications, description updates may go silently unnoticed.
3. Date and time stamps for creation and modified

[humitos]

I originally used a comment following the "convention" but immediately remembered the things that bother me from that behavior:

• after opening a PR, I receive a notification on GH saying there is a new comment. I prefer to not have that noise in my GH daily workflow
• I see all those comments as a lot of spam. The combination of them would be terrible: welcome bot, documentation, codecov, etc.
• I'm not sure why the timestamp for this would be important, but when the description is edited by the GH action, the timestamp is saved and you can see it by clicking the little arrow if needed.

Note these are all personal preferences, of course 😄

I'm sure we won't make all the users happy with this, implementing one or the other approach. That's why I opened the issue to discuss "Comment instead of edit the PR's description" and start collecting feedback and eventually implement it as configuration option.

[benjaoming]

This is a good point, and even though GitHub may know and indicate that a profile is a bot, they don't seem to have ways to filter out notifications from bot comments AFAIK.

Perhaps converting to comments is something that we can do when we have refined the message? I listed some scenarios in #4 and I think it's more clear that we need an "intelligent" way of detecting documentation changes before generating notification noise.

Summarizing: I think we should generate a comment and a notification for the first time that relevant documentation changes are seen -- so perhaps we shouldn't introduce a commenting feature at all before we can detect relevant page changes. Otherwise the comments would also have to say "something might have changed in your documentation - so we built a new version. And behold here it is, you can check it yourself" -- it does seem to be very noisy and not very useful if a repository has 90% PRs without docs changes :)