From 37f6040764489ee63b14807c1196c3b2e6469eb4 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 25 Jul 2023 22:16:49 -0700 Subject: [PATCH 1/3] SubmittingPatches: choice of base for fixing an older maintenance track When working on an high-value bugfix that must be given to ancient maintenance tracks, a starting point that is older than `maint` may have to be chosen. Helped-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index f1774c91e9..c500fb4398 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -46,7 +46,12 @@ latest HEAD commit of `maint` or `master` based on the following cases: * If you are fixing bugs in the released version, use `maint` as the starting point (which may mean you have to fix things without using new API features on the cutting edge that recently appeared in - `master` but were not available in the released version). + `master` but were not available in the released version). If the bug + exists in an older version (e.g., commit `X` introduced the bug, and + `git describe --contains X` says `v2.30.0-rc2-gXXXXXX` has it), then + use the tip of the maintenance branch for the 2.30.x versions in the + `maint-2.30` branch in https://github.com/gitster/git[the maintainer's + repo]. * Otherwise (such as if you are adding new features) use `master`. From f835de52d7c36c278004383919c58457861dac6c Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 25 Jul 2023 22:17:31 -0700 Subject: [PATCH 2/3] SubmittingPatches: explain why 'next' and above are inappropriate base The 'next' branch is primarily meant to be a testing ground to make sure that topics that are reasonably well done work well together. Building a new work on it would mean everything that was already in 'next' must have graduated to 'master' before the new work can also be merged to 'master', and that is why we do not encourage basing new work on 'next'. Helped-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c500fb4398..42ce0a5939 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -57,10 +57,14 @@ latest HEAD commit of `maint` or `master` based on the following cases: This also means that `next` or `seen` are inappropriate starting points for your work, if you want your work to have a realistic chance of -graduating to `master`. They are simply not designed to provide a -stable base for new work, because they are (by design) frequently -re-integrated with incoming patches on the mailing list and force-pushed -to replace previous versions of these branches. +graduating to `master`. They are simply not designed to be used as a +base for new work; they are only there to make sure that topics in +flight work well together. This is why both `next` and `seen` are +frequently re-integrated with incoming patches on the mailing list and +force-pushed to replace previous versions of themselves. A topic that is +literally built on top of `next` cannot be merged to `master` without +dragging in all the other topics in `next`, some of which may not be +ready. For example, if you are making tree-wide changes, while somebody else is also making their own tree-wide changes, your work may have severe From 369998df83d779e0b3fc45072be20d43a6559b27 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 25 Jul 2023 22:21:12 -0700 Subject: [PATCH 3/3] SubmittingPatches: use of older maintenance tracks is an exception While we could technically fix each and every bug on top of the commit that introduced it, it is not necessarily practical. For trivial and low-value bugfixes, it often is simpler and sufficient to just fix it in the current maintenance track, leaving the bug unfixed in the older maintenance tracks. Demote the "use older maintenance track to fix old bugs" as a side note, and explain that the choice is used only in exceptional cases. Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 42ce0a5939..973d7a81d4 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -46,15 +46,22 @@ latest HEAD commit of `maint` or `master` based on the following cases: * If you are fixing bugs in the released version, use `maint` as the starting point (which may mean you have to fix things without using new API features on the cutting edge that recently appeared in - `master` but were not available in the released version). If the bug - exists in an older version (e.g., commit `X` introduced the bug, and - `git describe --contains X` says `v2.30.0-rc2-gXXXXXX` has it), then - use the tip of the maintenance branch for the 2.30.x versions in the - `maint-2.30` branch in https://github.com/gitster/git[the maintainer's - repo]. + `master` but were not available in the released version). * Otherwise (such as if you are adding new features) use `master`. + +NOTE: In exceptional cases, a bug that was introduced in an old +version may have to be fixed for users of releases that are much older +than the recent releases. `git describe --contains X` may describe +`X` as `v2.30.0-rc2-gXXXXXX` for the commit `X` that introduced the +bug, and the bug may be so high-impact that we may need to issue a new +maintenance release for Git 2.30.x series, when "Git 2.41.0" is the +current release. In such a case, you may want to use the tip of the +maintenance branch for the 2.30.x series, which may be available in the +`maint-2.30` branch in https://github.com/gitster/git[the maintainer's +"broken out" repo]. + This also means that `next` or `seen` are inappropriate starting points for your work, if you want your work to have a realistic chance of graduating to `master`. They are simply not designed to be used as a