[
https://issues.apache.org/jira/browse/CAMEL-25597?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18126604#comment-18126604
]
Aurélien Pupier commented on CAMEL-25597:
-----------------------------------------
{noformat}
Every PR that needs an upgrade note appends a section at the end of the same
file {noformat}
This is the bigger root of the problem. If added alphabetically, and in a more
structured document, the conflicts will occur a bit at the beginning of a new
development phase version but a lot less after. It doesn't remove completely
the potential conflicts though.
In this case, the conflicts would arrive most of the time when providing
separate PRs on same component. in this case, it would be benefitial to have
the PRs based on each other to avoid brekaing the main branch because of 2 PRs
doing incompatible changes without conflicts. So we can even see it as a good
thing that we have conflicts to notice that another PR was merged with close
code modified.
{noformat}
how the guide picks up the files {noformat}
I think each files will need to provide some metadata, such as: component
impacted, removal, deprecation, breaking changes. So that the algorithm picking
the files is guided correctly. If not, it means that the generated upgrade
guide will quickly become a big mess.
When using different files, it remains the problem that it means that we will
need to generate this content at build time, on each build. Otherwise, we will
still have the conflict problem. It will consume resources and to check the end
result, it is adding an extra step.
{noformat}
Alternative without tooling: contributors put the note text in the PR
description under an "Upgrade guide" heading, and whoever merges adds the notes
to the guide in bulk afterwards. {noformat}
if we can try to keep the upgrade guide in same PR, that would be more
convenient to revert, browse history and backport.
So to summarize, I think that there is more advantages to keep everything in
the same file. it will even encourage to provide a better and more structured
upgrade guide.
> Upgrade guide - one note file per PR so PRs do not conflict on
> camel-4x-upgrade-guide-4_XX.adoc
> -----------------------------------------------------------------------------------------------
>
> Key: CAMEL-25597
> URL: https://issues.apache.org/jira/browse/CAMEL-25597
> Project: Camel
> Issue Type: Task
> Components: documentation
> Reporter: Claus Ibsen
> Priority: Major
> Fix For: 4.24.0
>
>
> Proposal for discussion - the team should agree on the approach before
> anything is changed.
> *Problem*
> Every PR that needs an upgrade note appends a section at the end of the same
> file,
> {{docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_XX.adoc}}.
> When one of them is merged, all the others conflict on that file, even when
> their code is unrelated. On 2026-10-12 nine approved, green PRs (#27678,
> #27689 - #27697) had to be re-synced one after the other; each sync is a push
> to the contributor's branch and a new CI round, and the next merge made the
> rest conflict again. In the end the notes were taken out of six PRs and added
> in one follow-up commit (#27744). This happens day after day, and asking
> contributors to rebase only for this file does not scale.
> A separate commit for the guide in each PR does not help: a squash merge
> takes all commits, so skipping one still means changing the contributor's
> branch.
> *Proposal*
> Each PR adds its upgrade note as its own small file instead of editing the
> guide, for example:
> {noformat}
> docs/user-manual/modules/ROOT/partials/upgrade-notes/4_24/CAMEL-25547.adoc
> {noformat}
> with the usual {{=== <component> - <title>}} heading and text. New files
> never conflict.
> The guide then shows them, in one of these ways (to decide):
> # the guide includes each note with
> {{include::partial$upgrade-notes/4_24/CAMEL-25547.adoc[]}} - the include
> lines still live in the guide, so whoever merges adds the line (or a
> merge-time / release-time step does it), or
> # a small build step (camel-package-maven-plugin or a docs script) generates
> the include list for {{camel-4x-upgrade-guide-4_XX.adoc}} from the files in
> the directory, sorted by component, so nobody edits the guide by hand, or
> # the release manager folds the note files into the guide when the release is
> cut, and deletes them.
> The same works for backports: a note for a maintenance release goes into the
> directory of that release (e.g. {{upgrade-notes/4_22_2/}}) on main.
> *To agree on*
> * the directory layout and file naming (Jira key per file)
> * how the guide picks up the files (include lines by hand, generated, or
> folded at release time)
> * the wording for AGENTS.md / CONTRIBUTING ("put the upgrade note in a new
> file under ..., do not edit camel-4x-upgrade-guide-4_XX.adoc") and the
> {{CLAUDE.md}} "Code Quality" section, which today says to edit the guide
> Alternative without tooling: contributors put the note text in the PR
> description under an "Upgrade guide" heading, and whoever merges adds the
> notes to the guide in bulk afterwards.
> _Claude Code on behalf of Claus Ibsen_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
