Hi Almost every bug fix and behaviour change adds a section to the upgrade guide, camel-4x-upgrade-guide-4_XX.adoc, and they all append at the end of the same file. So as soon as one PR is merged, all the other open PRs with a note conflict on that file, even when their code has nothing in common.
Today I merged 9 approved, green PRs and had to sync the guide on them one after the other. Each sync means a push to the contributor's branch and another CI round, and the next merge breaks the rest again. In the end I took the notes out of the PRs and added them in one follow-up commit. This happens almost every day, and asking contributors to rebase only because of this file doesn't scale. My proposal is that each PR adds its note as its own small file, for example docs/user-manual/modules/ROOT/partials/upgrade-notes/4_24/CAMEL-12345.adoc and doesn't touch the guide. New files never conflict. The guide then picks up the notes, either through include lines, a small build step that generates them, or by folding them in when we cut the release. That last part is open for discussion. A simpler alternative without tooling: put the note text in the PR description, and whoever merges adds it to the guide afterwards. Details are in CAMEL-25597: https://issues.apache.org/jira/browse/CAMEL-25597 What do you think? Other ideas are welcome too. -- Claus Ibsen
