Claus Ibsen created CAMEL-25597:
-----------------------------------
Summary: 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
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)
