[
https://issues.apache.org/jira/browse/CAMEL-25597?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-25597:
--------------------------------
Fix Version/s: 4.25.0
(was: 4.24.0)
> 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.25.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
(v10.3.26#10030026)
