* [PATCH 0/5] SubmittingPatches: clarify which branch to use
@ 2023-07-08 1:05 Linus Arver via GitGitGadget
2023-07-08 1:05 ` [PATCH 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget
` (5 more replies)
0 siblings, 6 replies; 38+ messages in thread
From: Linus Arver via GitGitGadget @ 2023-07-08 1:05 UTC (permalink / raw)
To: git; +Cc: Linus Arver
This series rewords the "base-branch" section to be more informative in
general to new contributors. The main motivation was to remove the phrase
"In general, always base your work on the oldest branch that your change is
relevant to" because it was somewhat misleading from the rest of the text.
Other smaller cleanups and improvements were made along the way.
Linus Arver (5):
SubmittingPatches: reword awkward phrasing
SubmittingPatches: be more explicit
SubmittingPatches: discuss subsystems separately from git.git
SubmittingPatches: remove confusing guidance about base branches
SubmittingPatches: define topic branches
Documentation/SubmittingPatches | 34 ++++++++++++++++++++++-----------
1 file changed, 23 insertions(+), 11 deletions(-)
base-commit: 061c58647eb4b3f0e2c898333577d4b2af115b1d
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1556%2Flistx%2Fdoc-submitting-patches-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1556/listx/doc-submitting-patches-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1556
--
gitgitgadget
^ permalink raw reply [flat|nested] 38+ messages in thread* [PATCH 1/5] SubmittingPatches: reword awkward phrasing 2023-07-08 1:05 [PATCH 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget @ 2023-07-08 1:05 ` Linus Arver via GitGitGadget 2023-07-08 5:37 ` Junio C Hamano 2023-07-08 1:05 ` [PATCH 2/5] SubmittingPatches: be more explicit Linus Arver via GitGitGadget ` (4 subsequent siblings) 5 siblings, 1 reply; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-08 1:05 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b218e273570..b89678cedc3 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -3,8 +3,8 @@ Submitting Patches == Guidelines -Here are some guidelines for people who want to contribute their code to this -software. There is also a link:MyFirstContribution.html[step-by-step tutorial] +Here are some guidelines for contributing back to this +project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. [[base-branch]] -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH 1/5] SubmittingPatches: reword awkward phrasing 2023-07-08 1:05 ` [PATCH 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget @ 2023-07-08 5:37 ` Junio C Hamano 0 siblings, 0 replies; 38+ messages in thread From: Junio C Hamano @ 2023-07-08 5:37 UTC (permalink / raw) To: Linus Arver via GitGitGadget; +Cc: git, Linus Arver "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Linus Arver <linusa@google.com> > > Signed-off-by: Linus Arver <linusa@google.com> > --- > Documentation/SubmittingPatches | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index b218e273570..b89678cedc3 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -3,8 +3,8 @@ Submitting Patches > > == Guidelines > > -Here are some guidelines for people who want to contribute their code to this > -software. There is also a link:MyFirstContribution.html[step-by-step tutorial] > +Here are some guidelines for contributing back to this > +project. There is also a link:MyFirstContribution.html[step-by-step tutorial] > available which covers many of these same guidelines. Obviously better. Thanks. ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH 2/5] SubmittingPatches: be more explicit 2023-07-08 1:05 [PATCH 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 2023-07-08 1:05 ` [PATCH 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget @ 2023-07-08 1:05 ` Linus Arver via GitGitGadget 2023-07-08 5:36 ` Junio C Hamano 2023-07-08 1:05 ` [PATCH 3/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget ` (3 subsequent siblings) 5 siblings, 1 reply; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-08 1:05 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b89678cedc3..5611580fb4c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -8,7 +8,7 @@ project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. [[base-branch]] -=== Decide what to base your work on. +=== Decide which branch to base your work on. In general, always base your work on the oldest branch that your change is relevant to. @@ -317,8 +317,8 @@ Please make sure your patch does not add commented out debugging code, or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before -sending out, please make sure it cleanly applies to the base you -have chosen in the "Decide what to base your work on" section, +sending out, please make sure it cleanly applies to the branch you +have chosen in the "Decide which branch to base your work on" section, and unless it targets the `master` branch (which is the default), mark your patches as such. -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH 2/5] SubmittingPatches: be more explicit 2023-07-08 1:05 ` [PATCH 2/5] SubmittingPatches: be more explicit Linus Arver via GitGitGadget @ 2023-07-08 5:36 ` Junio C Hamano 2023-07-13 21:03 ` Linus Arver 0 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2023-07-08 5:36 UTC (permalink / raw) To: Linus Arver via GitGitGadget; +Cc: git, Linus Arver "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Linus Arver <linusa@google.com> > > Signed-off-by: Linus Arver <linusa@google.com> > --- If you leave the body of the commit log message empty, can we at least have a bit more helpful title so that it is clear what we are being more explicit about? > [[base-branch]] > -=== Decide what to base your work on. > +=== Decide which branch to base your work on. Technically speaking, what the user needs to decide here is on top of what commit to base their work on. There may not be a suitable branch anywhere. But this series will be updating the section even more in the later steps, so let's read on. > @@ -317,8 +317,8 @@ Please make sure your patch does not add commented out debugging code, > or include any extra files which do not relate to what your patch > is trying to achieve. Make sure to review > your patch after generating it, to ensure accuracy. Before > -sending out, please make sure it cleanly applies to the base you > -have chosen in the "Decide what to base your work on" section, > +sending out, please make sure it cleanly applies to the branch you > +have chosen in the "Decide which branch to base your work on" section, > and unless it targets the `master` branch (which is the default), > mark your patches as such. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 2/5] SubmittingPatches: be more explicit 2023-07-08 5:36 ` Junio C Hamano @ 2023-07-13 21:03 ` Linus Arver 2023-07-13 21:10 ` Junio C Hamano 0 siblings, 1 reply; 38+ messages in thread From: Linus Arver @ 2023-07-13 21:03 UTC (permalink / raw) To: Junio C Hamano, Linus Arver via GitGitGadget; +Cc: git Junio C Hamano <gitster@pobox.com> writes: > "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> From: Linus Arver <linusa@google.com> >> >> Signed-off-by: Linus Arver <linusa@google.com> >> --- > > If you leave the body of the commit log message empty, can we > at least have a bit more helpful title so that it is clear what we > are being more explicit about? Certainly. Will update in v2. >> [[base-branch]] >> -=== Decide what to base your work on. >> +=== Decide which branch to base your work on. > > Technically speaking, what the user needs to decide here is on top > of what commit to base their work on. There may not be a suitable > branch anywhere. Good point. Will add this in v2. I think what threw me off originally was the internal section link name "[[base-branch]]". I think that could be reworded to "base-starting-point" or similar. > But this series will be updating the section even more in the later > steps, so let's read on. > > > >> @@ -317,8 +317,8 @@ Please make sure your patch does not add commented out debugging code, >> or include any extra files which do not relate to what your patch >> is trying to achieve. Make sure to review >> your patch after generating it, to ensure accuracy. Before >> -sending out, please make sure it cleanly applies to the base you >> -have chosen in the "Decide what to base your work on" section, >> +sending out, please make sure it cleanly applies to the branch you >> +have chosen in the "Decide which branch to base your work on" section, >> and unless it targets the `master` branch (which is the default), >> mark your patches as such. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 2/5] SubmittingPatches: be more explicit 2023-07-13 21:03 ` Linus Arver @ 2023-07-13 21:10 ` Junio C Hamano 0 siblings, 0 replies; 38+ messages in thread From: Junio C Hamano @ 2023-07-13 21:10 UTC (permalink / raw) To: Linus Arver; +Cc: Linus Arver via GitGitGadget, git Linus Arver <linusa@google.com> writes: > I think what threw me off originally was the internal section link name > "[[base-branch]]". I think that could be reworded to > "base-starting-point" or similar. Yeah, I agree that it is misleading to say "branch" as if it has to already exist. starting-point would be a good phrase to include, so I would imagine base-starting-point would be an appropriate name for the inline anchor. ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH 3/5] SubmittingPatches: discuss subsystems separately from git.git 2023-07-08 1:05 [PATCH 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 2023-07-08 1:05 ` [PATCH 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget 2023-07-08 1:05 ` [PATCH 2/5] SubmittingPatches: be more explicit Linus Arver via GitGitGadget @ 2023-07-08 1:05 ` Linus Arver via GitGitGadget 2023-07-08 1:05 ` [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches Linus Arver via GitGitGadget ` (2 subsequent siblings) 5 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-08 1:05 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> The discussion around subsystems disrupts the flow of discussion in the surrounding area, which only deals with branches used for the git.git project. So move this bullet point out to the end. Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 5611580fb4c..48918181f49 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -35,14 +35,14 @@ change is relevant to. to stabilize, you would have to rebase it (see the "depends on other topics" above). -* Some parts of the system have dedicated maintainers with their own - repositories (see the section "Subsystems" below). Changes to - these parts should be based on their trees. - To find the tip of a topic branch, run `git log --first-parent master..seen` and look for the merge commit. The second parent of this commit is the tip of the topic branch. +Note that some parts of the system have dedicated maintainers with their +own separate source code repositories (see the section "Subsystems" +below). + [[separate-commits]] === Make separate commits for logically separate changes. -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches 2023-07-08 1:05 [PATCH 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (2 preceding siblings ...) 2023-07-08 1:05 ` [PATCH 3/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget @ 2023-07-08 1:05 ` Linus Arver via GitGitGadget 2023-07-08 5:48 ` Junio C Hamano 2023-07-08 1:05 ` [PATCH 5/5] SubmittingPatches: define topic branches Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 5 siblings, 1 reply; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-08 1:05 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> The guidance to "base your work on the oldest branch that your change is relevant to" was added in d0c26f0f56 (SubmittingPatches: Add new section about what to base work on, 2010-04-19). That commit also added the bullet points which describe the scenarios where one would use one of "maint", "master", "next", and "seen" ("pu" in the original as that was the name of this branch before it was renamed, per 828197de8f (docs: adjust for the recent rename of `pu` to `seen`, 2020-06-25)). The underlying principle of this guidance was probably something like "base your work on the earlier-in-history branch so your change can be merged forward". However, this principle is already concretely explained in the accompanying bullet points. This principle should only come into play if none of the scenarios described in the bullet points apply --- and such a situation would be exceedingly rare. Also, the guidance's wording of using the "oldest" branch is confusing when read together with the rest of this section, because three of the four named branches discussed ("master", "next", and "seen") move frequently enough to not be considered "old" at all. For these reasons, remove the guidance _without_ preserving the meaning of the underlying principle, and instead add an overview of the four named branches. Helped-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 48918181f49..ef39808f568 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,8 +10,15 @@ available which covers many of these same guidelines. [[base-branch]] === Decide which branch to base your work on. -In general, always base your work on the oldest branch that your -change is relevant to. +The following branches are the typical starting points for new work: + +* maint +* master +* next +* seen + +These branches are explained in detail in linkgit:gitworkflows[7]. +Choose the appropriate branch depending on the following scenarios: * A bugfix should be based on `maint` in general. If the bug is not present in `maint`, base it on `master`. For a bug that's not yet -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches 2023-07-08 1:05 ` [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches Linus Arver via GitGitGadget @ 2023-07-08 5:48 ` Junio C Hamano 2023-07-13 21:54 ` Linus Arver 0 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2023-07-08 5:48 UTC (permalink / raw) To: Linus Arver via GitGitGadget; +Cc: git, Linus Arver "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: > For these reasons, remove the guidance _without_ preserving the meaning > of the underlying principle, and instead add an overview of the four > named branches. Meaning that this rewrites the guidance and changes the meaning of the underlying principle? > -In general, always base your work on the oldest branch that your > -change is relevant to. > +The following branches are the typical starting points for new work: > + > +* maint > +* master > +* next > +* seen > + > +These branches are explained in detail in linkgit:gitworkflows[7]. > +Choose the appropriate branch depending on the following scenarios: Please never suggest to build anything on 'next' or 'seen'. They are inappropriate to base your work on, if your topic wants to have a realistic chance to graduate to 'master'. If you are making tree-wide changes, while somebody else is also making another tree-wide changes, your topic may have severe overlap with the other person's topic. In which case, you may be tempted to build on 'next' that has the other person's topic, but doing so would mean you'll not just depend on the other topic, but with all the other topics that are already in 'next'. That would make the basic choices simpler. * If you are fixing bugs in the released version, build on 'maint' (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 you are adding new features, build on 'master'. Under exceptional circumstances that you need to depend on a selected few topics that are already in 'next' but not in 'master', you may want to fork your base-branch from 'master', merge these selected few topics to it, and call that your base-branch (which nobody else has). And then you build on top of it. When sending patches out, because your synthetic base-branch is something only you have, you'd need to communicate how you created it in your cover letter to allow others to recreate it. Thanks. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches 2023-07-08 5:48 ` Junio C Hamano @ 2023-07-13 21:54 ` Linus Arver 0 siblings, 0 replies; 38+ messages in thread From: Linus Arver @ 2023-07-13 21:54 UTC (permalink / raw) To: Junio C Hamano, Linus Arver via GitGitGadget; +Cc: git Junio C Hamano <gitster@pobox.com> writes: > "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> For these reasons, remove the guidance _without_ preserving the meaning >> of the underlying principle, and instead add an overview of the four >> named branches. > > Meaning that this rewrites the guidance Yes. > and changes the meaning of the underlying principle? Hmm, no. I think I should have written in my commit message instead: --8<---------------cut here---------------start------------->8--- For these reasons, remove the guidance while still preserving the meaning of the underlying principle by adding an overview of the four named branches. --8<---------------cut here---------------end--------------->8--- However, I now think deleting the "base your work on the oldest branch that your change is relevant to" text was unnecessarily harsh. I think I can reword it to make it sound less contrary to the accompanying bullet points. Will update in v2. >> -In general, always base your work on the oldest branch that your >> -change is relevant to. >> +The following branches are the typical starting points for new work: >> + >> +* maint >> +* master >> +* next >> +* seen >> + >> +These branches are explained in detail in linkgit:gitworkflows[7]. >> +Choose the appropriate branch depending on the following scenarios: > > Please never suggest to build anything on 'next' or 'seen'. They > are inappropriate to base your work on, if your topic wants to have > a realistic chance to graduate to 'master'. I only included "next" and "seen" here just below "maint" and "master" because they were included as OK-places to start new work (albeit in exceptional cases) in one of the bullet points: --8<---------------cut here---------------start------------->8--- * In the exceptional case that a new feature depends on several topics not in `master`, start working on `next` or `seen` privately and send out patches only for discussion. Once your new feature starts to stabilize, you would have to rebase it (see the "depends on other topics" above). --8<---------------cut here---------------end--------------->8--- > If you are making tree-wide changes, while somebody else is also > making another tree-wide changes, your topic may have severe overlap > with the other person's topic. In which case, you may be tempted to > build on 'next' that has the other person's topic, but doing so would > mean you'll not just depend on the other topic, but with all the > other topics that are already in 'next'. Good point. I will include this tip in v2 (seems like something that would be especially helpful for newer contributors). > That would make the basic choices simpler. > > * If you are fixing bugs in the released version, build on 'maint' > (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 you are adding new features, build on 'master'. > > Under exceptional circumstances that you need to depend on a > selected few topics that are already in 'next' but not in 'master', > you may want to fork your base-branch from 'master', merge these > selected few topics to it, and call that your base-branch (which > nobody else has). And then you build on top of it. When sending > patches out, because your synthetic base-branch is something only > you have, you'd need to communicate how you created it in your cover > letter to allow others to recreate it. I strongly agree that this is simpler. One thing I would change is to use a phrase like "start your work" instead of the word "build" because the latter on quick glance could be misinterpreted as literally building (compiling/packaging) the project. Will incorporate in v2 (thank you for the suggestion; will credit you in a "Helped-by: ..." trailer). ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH 5/5] SubmittingPatches: define topic branches 2023-07-08 1:05 [PATCH 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (3 preceding siblings ...) 2023-07-08 1:05 ` [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches Linus Arver via GitGitGadget @ 2023-07-08 1:05 ` Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 5 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-08 1:05 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index ef39808f568..6fb96e6537f 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -17,7 +17,12 @@ The following branches are the typical starting points for new work: * next * seen -These branches are explained in detail in linkgit:gitworkflows[7]. +These branches are explained in detail in linkgit:gitworkflows[7]. There are +also "topic" branches, which contain work from other contributors. Topic +branches are created by the Git maintainer (in their fork) to organize the +current set of incoming contributions from the mailing list, and are enumerated +in the regular "What's cooking in git.git" announcements. + Choose the appropriate branch depending on the following scenarios: * A bugfix should be based on `maint` in general. If the bug is not -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [PATCH v2 0/5] SubmittingPatches: clarify which branch to use 2023-07-08 1:05 [PATCH 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (4 preceding siblings ...) 2023-07-08 1:05 ` [PATCH 5/5] SubmittingPatches: define topic branches Linus Arver via GitGitGadget @ 2023-07-14 6:01 ` Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget ` (5 more replies) 5 siblings, 6 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-14 6:01 UTC (permalink / raw) To: git; +Cc: Linus Arver This series rewords the "base-branch" section (now renamed to "choose-starting-point") to be more informative in general to new contributors, who may not be as familiar with the various integration branches. Other smaller cleanups and improvements were made along the way. Updates in v2 ============= * The language about choosing the "oldest" branch was retained, and expanded. It turns out that this language is also present in gitworkflows, however the meaning of the word "oldest" was not explained properly in the "base-branch" section. This has been addressed. * Rename "base-branch" to "choose-starting-point" * Patch 04 (emphasize need to communicate non-default starting points) is new. Linus Arver (5): SubmittingPatches: reword awkward phrasing SubmittingPatches: discuss subsystems separately from git.git SubmittingPatches: de-emphasize branches as starting points SubmittingPatches: emphasize need to communicate non-default starting points SubmittingPatches: simplify guidance for choosing a starting point Documentation/SubmittingPatches | 125 +++++++++++++++++++++----------- 1 file changed, 84 insertions(+), 41 deletions(-) base-commit: aa9166bcc0ba654fc21f198a30647ec087f733ed Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1556%2Flistx%2Fdoc-submitting-patches-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1556/listx/doc-submitting-patches-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1556 Range-diff vs v1: 1: cb4a61eba8d = 1: 08deed14d96 SubmittingPatches: reword awkward phrasing 3: d430a4ed8ee ! 2: 8d4b57a8704 SubmittingPatches: discuss subsystems separately from git.git @@ Commit message SubmittingPatches: discuss subsystems separately from git.git The discussion around subsystems disrupts the flow of discussion in the - surrounding area, which only deals with branches used for the git.git - project. So move this bullet point out to the end. + surrounding area, which only deals with starting points used for the + git.git project. So move this bullet point out to the end. Signed-off-by: Linus Arver <linusa@google.com> @@ Documentation/SubmittingPatches: change is relevant to. master..seen` and look for the merge commit. The second parent of this commit is the tip of the topic branch. -+Note that some parts of the system have dedicated maintainers with their -+own separate source code repositories (see the section "Subsystems" -+below). ++Finally, note that some parts of the system have dedicated maintainers ++with their own separate source code repositories (see the section ++"Subsystems" below). + [[separate-commits]] === Make separate commits for logically separate changes. 2: 203ed19dd1b ! 3: 69fef8afe64 SubmittingPatches: be more explicit @@ Metadata Author: Linus Arver <linusa@google.com> ## Commit message ## - SubmittingPatches: be more explicit + SubmittingPatches: de-emphasize branches as starting points + It could be that a suitable branch does not exist, so instead just use + the phrase "starting point". Technically speaking the starting point + would be a commit (not a branch) anyway. + + Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Linus Arver <linusa@google.com> ## Documentation/SubmittingPatches ## -@@ Documentation/SubmittingPatches: project. There is also a link:MyFirstContribution.html[step-by-step tutorial] +@@ Documentation/SubmittingPatches: Here are some guidelines for contributing back to this + project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. - [[base-branch]] +-[[base-branch]] -=== Decide what to base your work on. -+=== Decide which branch to base your work on. ++[[choose-starting-point]] ++=== Choose a starting point. In general, always base your work on the oldest branch that your change is relevant to. @@ Documentation/SubmittingPatches: Please make sure your patch does not add commen your patch after generating it, to ensure accuracy. Before -sending out, please make sure it cleanly applies to the base you -have chosen in the "Decide what to base your work on" section, -+sending out, please make sure it cleanly applies to the branch you -+have chosen in the "Decide which branch to base your work on" section, ++sending out, please make sure it cleanly applies to the starting point you ++have chosen in the "Choose a starting point" section, and unless it targets the `master` branch (which is the default), mark your patches as such. -: ----------- > 4: f8f96a79b92 SubmittingPatches: emphasize need to communicate non-default starting points 4: 55bed55cb88 ! 5: 5ec91d02b7a SubmittingPatches: remove confusing guidance about base branches @@ Metadata Author: Linus Arver <linusa@google.com> ## Commit message ## - SubmittingPatches: remove confusing guidance about base branches + SubmittingPatches: simplify guidance for choosing a starting point - The guidance to "base your work on the oldest branch that your change is - relevant to" was added in d0c26f0f56 (SubmittingPatches: Add new section - about what to base work on, 2010-04-19). That commit also added the - bullet points which describe the scenarios where one would use one of - "maint", "master", "next", and "seen" ("pu" in the original as that was - the name of this branch before it was renamed, per 828197de8f (docs: - adjust for the recent rename of `pu` to `seen`, 2020-06-25)). + Background: The guidance to "base your work on the oldest branch that + your change is relevant to" was added in d0c26f0f56 (SubmittingPatches: + Add new section about what to base work on, 2010-04-19). That commit + also added the bullet points which describe the scenarios where one + would use one of the following named branches: "maint", "master", + "next", and "seen" ("pu" in the original as that was the name of this + branch before it was renamed, per 828197de8f (docs: adjust for the + recent rename of `pu` to `seen`, 2020-06-25)). The guidance was probably + taken from existing similar language introduced in the "Merge upwards" + section of gitworkflows in f948dd8992 (Documentation: add manpage about + workflows, 2008-10-19). - The underlying principle of this guidance was probably something like - "base your work on the earlier-in-history branch so your change can be - merged forward". However, this principle is already concretely explained - in the accompanying bullet points. This principle should only come into - play if none of the scenarios described in the bullet points apply --- - and such a situation would be exceedingly rare. - - Also, the guidance's wording of using the "oldest" branch is confusing - when read together with the rest of this section, because three of the - four named branches discussed ("master", "next", and "seen") move - frequently enough to not be considered "old" at all. - - For these reasons, remove the guidance _without_ preserving the meaning - of the underlying principle, and instead add an overview of the four - named branches. + Summary: This change simplifies the guidance by pointing users to just + "maint" or "master". But it also gives an explanation of why that is + preferred and what is meant by preferring "older" branches (which might + be confusing to some because "old" here is meant in relative terms + between these named branches, not in terms of the age of the branches + themselves). We also add an example to illustrate why it would be a bad + idea to use "next" as a starting point, which may not be so obvious to + new contributors. Helped-by: Jonathan Nieder <jrnieder@gmail.com> + Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Linus Arver <linusa@google.com> ## Documentation/SubmittingPatches ## @@ Documentation/SubmittingPatches: available which covers many of these same guidelines. - [[base-branch]] - === Decide which branch to base your work on. + [[choose-starting-point]] + === Choose a starting point. -In general, always base your work on the oldest branch that your -change is relevant to. -+The following branches are the typical starting points for new work: +- +-* A bugfix should be based on `maint` in general. If the bug is not +- present in `maint`, base it on `master`. For a bug that's not yet +- in `master`, find the topic that introduces the regression, and +- base your work on the tip of the topic. +- +-* A new feature should be based on `master` in general. If the new +- feature depends on other topics that are in `next`, but not in +- `master`, fork a branch from the tip of `master`, merge these topics +- to the branch, and work on that branch. You can remind yourself of +- how you prepared the base with `git log --first-parent master..`. +- +-* Corrections and enhancements to a topic not yet in `master` should +- be based on the tip of that topic. If the topic has not been merged +- to `next`, it's alright to add a note to squash minor corrections +- into the series. +- +-* In the exceptional case that a new feature depends on several topics +- not in `master`, start working on `next` or `seen` privately and +- send out patches only for discussion. Once your new feature starts +- to stabilize, you would have to rebase it (see the "depends on other +- topics" above). +- +-To find the tip of a topic branch, run `git log --first-parent +-master..seen` and look for the merge commit. The second parent of this +-commit is the tip of the topic branch. ++As a preliminary step, you must first choose a starting point for your ++work. Typically this means choosing a branch, although technically ++speaking it is actually a particular commit (typically the HEAD, or tip, ++of the branch). ++ ++There are several important branches to be aware of. Namely, there are ++four integration branches as discussed in linkgit:gitworkflows[7]: + +* maint +* master +* next +* seen + -+These branches are explained in detail in linkgit:gitworkflows[7]. -+Choose the appropriate branch depending on the following scenarios: ++The branches lower on the list are typically descendants of the ones ++that come before it. For example, `maint` is an "older" branch than ++`master` because `master` usually has patches (commits) on top of ++`maint`. ++ ++There are also "topic" branches, which contain work from other ++contributors. Topic branches are created by the Git maintainer (in ++their fork) to organize the current set of incoming contributions on ++the mailing list, and are itemized in the regular "What's cooking in ++git.git" announcements. To find the tip of a topic branch, run `git log ++--first-parent master..seen` and look for the merge commit. The second ++parent of this commit is the tip of the topic branch. ++ ++There is one guiding principle for choosing the right starting point: in ++general, always base your work on the oldest integration branch that ++your change is relevant to (see "Merge upwards" in ++linkgit:gitworkflows[7]). What this principle means is that for the ++vast majority of cases, the starting point for new work should be the ++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). ++ ++* Otherwise (such as if you are adding new features) use `master`. ++ ++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. ++ ++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 ++overlap with the other person's work. This situation may tempt you to ++use `next` as your starting point (because it would have the other ++person's work included in it), but doing so would mean you'll not only ++depend on the other person's work, but all the other random things from ++other contributors that are already integrated into `next`. And as soon ++as `next` is updated with a new version, all of your work will need to ++be rebased anyway in order for them to be cleanly applied by the ++maintainer. ++ ++Under truly exceptional circumstances where you absolutely must depend ++on a select few topic branches that are already in `next` but not in ++`master`, you may want to create your own custom base-branch by forking ++`master` and merging the required topic branches to it. You could then ++work on top of this base-branch. But keep in mind that this base-branch ++would only be known privately to you. So when you are ready to send ++your patches to the list, be sure to communicate how you created it in ++your cover letter. This critical piece of information would allow ++others to recreate your base-branch on their end in order for them to ++try out your work. - * A bugfix should be based on `maint` in general. If the bug is not - present in `maint`, base it on `master`. For a bug that's not yet + Finally, note that some parts of the system have dedicated maintainers + with their own separate source code repositories (see the section 5: 1db7a1be27f < -: ----------- SubmittingPatches: define topic branches -- gitgitgadget ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH v2 1/5] SubmittingPatches: reword awkward phrasing 2023-07-14 6:01 ` [PATCH v2 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget @ 2023-07-14 6:01 ` Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 2/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget ` (4 subsequent siblings) 5 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-14 6:01 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b218e273570..b89678cedc3 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -3,8 +3,8 @@ Submitting Patches == Guidelines -Here are some guidelines for people who want to contribute their code to this -software. There is also a link:MyFirstContribution.html[step-by-step tutorial] +Here are some guidelines for contributing back to this +project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. [[base-branch]] -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [PATCH v2 2/5] SubmittingPatches: discuss subsystems separately from git.git 2023-07-14 6:01 ` [PATCH v2 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget @ 2023-07-14 6:01 ` Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 3/5] SubmittingPatches: de-emphasize branches as starting points Linus Arver via GitGitGadget ` (3 subsequent siblings) 5 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-14 6:01 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> The discussion around subsystems disrupts the flow of discussion in the surrounding area, which only deals with starting points used for the git.git project. So move this bullet point out to the end. Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b89678cedc3..7919a362e31 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -35,14 +35,14 @@ change is relevant to. to stabilize, you would have to rebase it (see the "depends on other topics" above). -* Some parts of the system have dedicated maintainers with their own - repositories (see the section "Subsystems" below). Changes to - these parts should be based on their trees. - To find the tip of a topic branch, run `git log --first-parent master..seen` and look for the merge commit. The second parent of this commit is the tip of the topic branch. +Finally, note that some parts of the system have dedicated maintainers +with their own separate source code repositories (see the section +"Subsystems" below). + [[separate-commits]] === Make separate commits for logically separate changes. -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [PATCH v2 3/5] SubmittingPatches: de-emphasize branches as starting points 2023-07-14 6:01 ` [PATCH v2 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 2/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget @ 2023-07-14 6:01 ` Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 4/5] SubmittingPatches: emphasize need to communicate non-default " Linus Arver via GitGitGadget ` (2 subsequent siblings) 5 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-14 6:01 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> It could be that a suitable branch does not exist, so instead just use the phrase "starting point". Technically speaking the starting point would be a commit (not a branch) anyway. Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 7919a362e31..f1d1446764b 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -7,8 +7,8 @@ Here are some guidelines for contributing back to this project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. -[[base-branch]] -=== Decide what to base your work on. +[[choose-starting-point]] +=== Choose a starting point. In general, always base your work on the oldest branch that your change is relevant to. @@ -317,8 +317,8 @@ Please make sure your patch does not add commented out debugging code, or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before -sending out, please make sure it cleanly applies to the base you -have chosen in the "Decide what to base your work on" section, +sending out, please make sure it cleanly applies to the starting point you +have chosen in the "Choose a starting point" section, and unless it targets the `master` branch (which is the default), mark your patches as such. -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [PATCH v2 4/5] SubmittingPatches: emphasize need to communicate non-default starting points 2023-07-14 6:01 ` [PATCH v2 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (2 preceding siblings ...) 2023-07-14 6:01 ` [PATCH v2 3/5] SubmittingPatches: de-emphasize branches as starting points Linus Arver via GitGitGadget @ 2023-07-14 6:01 ` Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point Linus Arver via GitGitGadget 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 5 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-14 6:01 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> The phrase and unless it targets the `master` branch (which is the default), mark your patches as such. is tightly packed with several things happening in just two lines of text. It also feels like it is not that important because of the terse treatment. This is a problem because (1) it has the potential to confuse new contributors, and (2) it may be glossed over for those skimming the docs. Emphasize and elaborate on this guidance by promoting it to its own separate paragraph. Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index f1d1446764b..40467372c0d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -318,9 +318,12 @@ or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before sending out, please make sure it cleanly applies to the starting point you -have chosen in the "Choose a starting point" section, -and unless it targets the `master` branch (which is the default), -mark your patches as such. +have chosen in the "Choose a starting point" section. + +NOTE: From the perspective of those reviewing your patch, the `master` +branch is the default expected starting point. So if you have chosen a +different starting point, please communicate this choice in your cover +letter. [[send-patches]] -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point 2023-07-14 6:01 ` [PATCH v2 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (3 preceding siblings ...) 2023-07-14 6:01 ` [PATCH v2 4/5] SubmittingPatches: emphasize need to communicate non-default " Linus Arver via GitGitGadget @ 2023-07-14 6:01 ` Linus Arver via GitGitGadget 2023-07-14 17:31 ` Junio C Hamano 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 5 siblings, 1 reply; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-14 6:01 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> Background: The guidance to "base your work on the oldest branch that your change is relevant to" was added in d0c26f0f56 (SubmittingPatches: Add new section about what to base work on, 2010-04-19). That commit also added the bullet points which describe the scenarios where one would use one of the following named branches: "maint", "master", "next", and "seen" ("pu" in the original as that was the name of this branch before it was renamed, per 828197de8f (docs: adjust for the recent rename of `pu` to `seen`, 2020-06-25)). The guidance was probably taken from existing similar language introduced in the "Merge upwards" section of gitworkflows in f948dd8992 (Documentation: add manpage about workflows, 2008-10-19). Summary: This change simplifies the guidance by pointing users to just "maint" or "master". But it also gives an explanation of why that is preferred and what is meant by preferring "older" branches (which might be confusing to some because "old" here is meant in relative terms between these named branches, not in terms of the age of the branches themselves). We also add an example to illustrate why it would be a bad idea to use "next" as a starting point, which may not be so obvious to new contributors. Helped-by: Jonathan Nieder <jrnieder@gmail.com> Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 96 +++++++++++++++++++++++---------- 1 file changed, 68 insertions(+), 28 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 40467372c0d..f1774c91e9c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,34 +10,74 @@ available which covers many of these same guidelines. [[choose-starting-point]] === Choose a starting point. -In general, always base your work on the oldest branch that your -change is relevant to. - -* A bugfix should be based on `maint` in general. If the bug is not - present in `maint`, base it on `master`. For a bug that's not yet - in `master`, find the topic that introduces the regression, and - base your work on the tip of the topic. - -* A new feature should be based on `master` in general. If the new - feature depends on other topics that are in `next`, but not in - `master`, fork a branch from the tip of `master`, merge these topics - to the branch, and work on that branch. You can remind yourself of - how you prepared the base with `git log --first-parent master..`. - -* Corrections and enhancements to a topic not yet in `master` should - be based on the tip of that topic. If the topic has not been merged - to `next`, it's alright to add a note to squash minor corrections - into the series. - -* In the exceptional case that a new feature depends on several topics - not in `master`, start working on `next` or `seen` privately and - send out patches only for discussion. Once your new feature starts - to stabilize, you would have to rebase it (see the "depends on other - topics" above). - -To find the tip of a topic branch, run `git log --first-parent -master..seen` and look for the merge commit. The second parent of this -commit is the tip of the topic branch. +As a preliminary step, you must first choose a starting point for your +work. Typically this means choosing a branch, although technically +speaking it is actually a particular commit (typically the HEAD, or tip, +of the branch). + +There are several important branches to be aware of. Namely, there are +four integration branches as discussed in linkgit:gitworkflows[7]: + +* maint +* master +* next +* seen + +The branches lower on the list are typically descendants of the ones +that come before it. For example, `maint` is an "older" branch than +`master` because `master` usually has patches (commits) on top of +`maint`. + +There are also "topic" branches, which contain work from other +contributors. Topic branches are created by the Git maintainer (in +their fork) to organize the current set of incoming contributions on +the mailing list, and are itemized in the regular "What's cooking in +git.git" announcements. To find the tip of a topic branch, run `git log +--first-parent master..seen` and look for the merge commit. The second +parent of this commit is the tip of the topic branch. + +There is one guiding principle for choosing the right starting point: in +general, always base your work on the oldest integration branch that +your change is relevant to (see "Merge upwards" in +linkgit:gitworkflows[7]). What this principle means is that for the +vast majority of cases, the starting point for new work should be the +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). + +* Otherwise (such as if you are adding new features) use `master`. + +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. + +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 +overlap with the other person's work. This situation may tempt you to +use `next` as your starting point (because it would have the other +person's work included in it), but doing so would mean you'll not only +depend on the other person's work, but all the other random things from +other contributors that are already integrated into `next`. And as soon +as `next` is updated with a new version, all of your work will need to +be rebased anyway in order for them to be cleanly applied by the +maintainer. + +Under truly exceptional circumstances where you absolutely must depend +on a select few topic branches that are already in `next` but not in +`master`, you may want to create your own custom base-branch by forking +`master` and merging the required topic branches to it. You could then +work on top of this base-branch. But keep in mind that this base-branch +would only be known privately to you. So when you are ready to send +your patches to the list, be sure to communicate how you created it in +your cover letter. This critical piece of information would allow +others to recreate your base-branch on their end in order for them to +try out your work. Finally, note that some parts of the system have dedicated maintainers with their own separate source code repositories (see the section -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point 2023-07-14 6:01 ` [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point Linus Arver via GitGitGadget @ 2023-07-14 17:31 ` Junio C Hamano 2023-07-26 1:36 ` Linus Arver 0 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2023-07-14 17:31 UTC (permalink / raw) To: Linus Arver via GitGitGadget; +Cc: git, Linus Arver "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: > +There is one guiding principle for choosing the right starting point: in > +general, always base your work on the oldest integration branch that > +your change is relevant to (see "Merge upwards" in > +linkgit:gitworkflows[7]). What this principle means is that for the > +vast majority of cases, the starting point for new work should be the > +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). I think this is technically not optimal, but is good enough for the sake of simplicity and brevity[*]. > +* Otherwise (such as if you are adding new features) use `master`. > + > +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. "unstable" is not the primary reason why you shouldn't build on 'next'. It is "your work, if queued on 'next', cannot be merged to 'master' without pulling all the other undercooked stuff still in 'next'", as you describe in the next paragraph. But that is different from being unstable. I'd suggest to use something like this instead: ... not designed to be used as a base for new work---they are there only to make sure that topics in flight work well together. A topic that is literally built on top of 'next' cannot be merged to 'master' without dragging all the other topics in 'next', some of which may not be ready. In addition, `seen` is frequently re-integrated with incoming patches ... > +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 > +overlap with the other person's work. This situation may tempt you to > +use `next` as your starting point (because it would have the other > +person's work included in it), but doing so would mean you'll not only > +depend on the other person's work, but all the other random things from > +other contributors that are already integrated into `next`. And as soon > +as `next` is updated with a new version, all of your work will need to > +be rebased anyway in order for them to be cleanly applied by the > +maintainer. > + > +Under truly exceptional circumstances where you absolutely must depend > +on a select few topic branches that are already in `next` but not in > +`master`, you may want to create your own custom base-branch by forking > +`master` and merging the required topic branches to it. You could then > +work on top of this base-branch. But keep in mind that this base-branch > +would only be known privately to you. So when you are ready to send > +your patches to the list, be sure to communicate how you created it in > +your cover letter. This critical piece of information would allow > +others to recreate your base-branch on their end in order for them to > +try out your work. Very well written. Thanks, will queue. [Footnote] * An very old but still severe bug in tagged versions would want to be fixed ideally not on top of 'maint' but on top of the latest tagged version in the same maintenance track. E.g. if the commit X introduced the bug, you may ask "git describe --contains X" the oldest version the commit appears in, say "v2.30.0-rc2-gXXXXXX". Then you would run "git checkout -b fix v2.30.9" to start the branch to fix it. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point 2023-07-14 17:31 ` Junio C Hamano @ 2023-07-26 1:36 ` Linus Arver 2023-07-26 2:31 ` Linus Arver 2023-07-26 4:41 ` Junio C Hamano 0 siblings, 2 replies; 38+ messages in thread From: Linus Arver @ 2023-07-26 1:36 UTC (permalink / raw) To: Junio C Hamano, Linus Arver via GitGitGadget; +Cc: git Junio C Hamano <gitster@pobox.com> writes: > "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> +There is one guiding principle for choosing the right starting point: in >> +general, always base your work on the oldest integration branch that >> +your change is relevant to (see "Merge upwards" in >> +linkgit:gitworkflows[7]). What this principle means is that for the >> +vast majority of cases, the starting point for new work should be the >> +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). > > I think this is technically not optimal, but is good enough for the > sake of simplicity and brevity[*]. > > [Footnote] > > * An very old but still severe bug in tagged versions would want to > be fixed ideally not on top of 'maint' but on top of the latest > tagged version in the same maintenance track. E.g. if the commit > X introduced the bug, you may ask "git describe --contains X" the > oldest version the commit appears in, say "v2.30.0-rc2-gXXXXXX". > Then you would run "git checkout -b fix v2.30.9" to start the > branch to fix it. In this example, are we using v2.30.9 as a starting point, not v2.30.0 because v2.30.9 is the latest tagged version that is in 'maint'? I think this nugget of knowledge should be included in a v3 of this series. Will update. >> +* Otherwise (such as if you are adding new features) use `master`. >> + >> +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. > > "unstable" is not the primary reason why you shouldn't build on > 'next'. It is "your work, if queued on 'next', cannot be merged to > 'master' without pulling all the other undercooked stuff still in > 'next'", as you describe in the next paragraph. But that is > different from being unstable. I'd suggest to use something like > this instead: > > ... not designed to be used as a base for new work---they > are there only to make sure that topics in flight work well > together. A topic that is literally built on top of 'next' > cannot be merged to 'master' without dragging all the other > topics in 'next', some of which may not be ready. In > addition, `seen` is frequently re-integrated with incoming > patches ... Will update. Thanks. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point 2023-07-26 1:36 ` Linus Arver @ 2023-07-26 2:31 ` Linus Arver 2023-07-26 4:41 ` Junio C Hamano 1 sibling, 0 replies; 38+ messages in thread From: Linus Arver @ 2023-07-26 2:31 UTC (permalink / raw) To: Junio C Hamano, Linus Arver via GitGitGadget; +Cc: git Linus Arver <linusa@google.com> writes: >> * An very old but still severe bug in tagged versions would want to >> be fixed ideally not on top of 'maint' but on top of the latest >> tagged version in the same maintenance track. E.g. if the commit >> X introduced the bug, you may ask "git describe --contains X" the >> oldest version the commit appears in, say "v2.30.0-rc2-gXXXXXX". >> Then you would run "git checkout -b fix v2.30.9" to start the >> branch to fix it. > > In this example, are we using v2.30.9 as a starting point, not v2.30.0 > because v2.30.9 is the latest tagged version that is in 'maint'? Answering my own question, I now see that there are branches named `maint-2.30`, `maint-2.31`, etc. And `2.30.9` is the latest version in the `maint-2.30` branch. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point 2023-07-26 1:36 ` Linus Arver 2023-07-26 2:31 ` Linus Arver @ 2023-07-26 4:41 ` Junio C Hamano 1 sibling, 0 replies; 38+ messages in thread From: Junio C Hamano @ 2023-07-26 4:41 UTC (permalink / raw) To: Linus Arver; +Cc: Linus Arver via GitGitGadget, git Linus Arver <linusa@google.com> writes: >> * An very old but still severe bug in tagged versions would want to >> be fixed ideally not on top of 'maint' but on top of the latest >> tagged version in the same maintenance track. E.g. if the commit >> X introduced the bug, you may ask "git describe --contains X" the >> oldest version the commit appears in, say "v2.30.0-rc2-gXXXXXX". >> Then you would run "git checkout -b fix v2.30.9" to start the >> branch to fix it. > > In this example, are we using v2.30.9 as a starting point, not v2.30.0 > because v2.30.9 is the latest tagged version that is in 'maint'? Yes, the example assumes that the last maintenance release for v2.30.x series is v2.30.9. But this kind of fix happening is sufficiently rare and I do not think regular contributors should have to worry too much about it. If the affected area had tons of changes between v2.30.9 and 'master', a fix on such an old base would require a lot of work merging upwards, adjusting to newer codebase, and it only makes sense to go that length for high value fixes (aka "security patch"). The rules that apply for such a fix would be vastly different (e.g. the review may be done behind closed doors with small number of reviewers, not on the public list). > I think this nugget of knowledge should be included in a v3 of this > series. Will update. So, while it may help improve understanding of the philosophy behind the regular procedure to know, I am not sure it is worth spending a lot of lines to describe it when we are giving a piece of advice for general "bugfix and/or new development". Some bugs are simply not worth the trouble of going back for more than two maintenance tracks to fix. Thanks. ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH v3 0/5] SubmittingPatches: clarify which branch to use 2023-07-14 6:01 ` [PATCH v2 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (4 preceding siblings ...) 2023-07-14 6:01 ` [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point Linus Arver via GitGitGadget @ 2023-07-26 3:04 ` Linus Arver via GitGitGadget 2023-07-26 3:04 ` [PATCH v3 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget ` (8 more replies) 5 siblings, 9 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-26 3:04 UTC (permalink / raw) To: git; +Cc: Linus Arver This series rewords the "base-branch" section (now renamed to "choose-starting-point") to be more informative in general to new contributors, who may not be as familiar with the various integration branches. Other smaller cleanups and improvements were made along the way. Updates in v3 ============= * We add a little more detail about when you'd want to use the tip of a maintenance track (e.g., maint-2.30) instead of maint. * The language about the instability of "next" and "seen" has been de-emphasized, in favor of saying that these branches just have lots of other topics (some not ready) in it. Updates in v2 ============= * The language about choosing the "oldest" branch was retained, and expanded. It turns out that this language is also present in gitworkflows, however the meaning of the word "oldest" was not explained properly in the "base-branch" section. This has been addressed. * Rename "base-branch" to "choose-starting-point" * Patch 04 (emphasize need to communicate non-default starting points) is new. Linus Arver (5): SubmittingPatches: reword awkward phrasing SubmittingPatches: discuss subsystems separately from git.git SubmittingPatches: de-emphasize branches as starting points SubmittingPatches: emphasize need to communicate non-default starting points SubmittingPatches: simplify guidance for choosing a starting point Documentation/SubmittingPatches | 134 ++++++++++++++++++++++---------- 1 file changed, 93 insertions(+), 41 deletions(-) base-commit: aa9166bcc0ba654fc21f198a30647ec087f733ed Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1556%2Flistx%2Fdoc-submitting-patches-v3 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1556/listx/doc-submitting-patches-v3 Pull-Request: https://github.com/gitgitgadget/git/pull/1556 Range-diff vs v2: 1: 08deed14d96 = 1: 08deed14d96 SubmittingPatches: reword awkward phrasing 2: 8d4b57a8704 = 2: 8d4b57a8704 SubmittingPatches: discuss subsystems separately from git.git 3: 69fef8afe64 = 3: 69fef8afe64 SubmittingPatches: de-emphasize branches as starting points 4: f8f96a79b92 = 4: f8f96a79b92 SubmittingPatches: emphasize need to communicate non-default starting points 5: 5ec91d02b7a ! 5: 1273f50c8a8 SubmittingPatches: simplify guidance for choosing a starting point @@ Commit message workflows, 2008-10-19). Summary: This change simplifies the guidance by pointing users to just - "maint" or "master". But it also gives an explanation of why that is - preferred and what is meant by preferring "older" branches (which might - be confusing to some because "old" here is meant in relative terms - between these named branches, not in terms of the age of the branches - themselves). We also add an example to illustrate why it would be a bad - idea to use "next" as a starting point, which may not be so obvious to - new contributors. + "maint" or "master" for most cases. But it also gives an explanation of + why that is preferred and what is meant by preferring "older" + branches (which might be confusing to some because "old" here is meant + in relative terms between these named branches, not in terms of the age + of the branches themselves). We also explain in detail why it would be a + bad idea to use "next" or "seen" as starting points, which may not be so + obvious to new contributors. Helped-by: Jonathan Nieder <jrnieder@gmail.com> Helped-by: Junio C Hamano <gitster@pobox.com> @@ Documentation/SubmittingPatches: available which covers many of these same guide +* 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 --containx 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`. + +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 -- gitgitgadget ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH v3 1/5] SubmittingPatches: reword awkward phrasing 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget @ 2023-07-26 3:04 ` Linus Arver via GitGitGadget 2023-07-26 3:04 ` [PATCH v3 2/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget ` (7 subsequent siblings) 8 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-26 3:04 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b218e273570..b89678cedc3 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -3,8 +3,8 @@ Submitting Patches == Guidelines -Here are some guidelines for people who want to contribute their code to this -software. There is also a link:MyFirstContribution.html[step-by-step tutorial] +Here are some guidelines for contributing back to this +project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. [[base-branch]] -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [PATCH v3 2/5] SubmittingPatches: discuss subsystems separately from git.git 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 2023-07-26 3:04 ` [PATCH v3 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget @ 2023-07-26 3:04 ` Linus Arver via GitGitGadget 2023-07-26 3:04 ` [PATCH v3 3/5] SubmittingPatches: de-emphasize branches as starting points Linus Arver via GitGitGadget ` (6 subsequent siblings) 8 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-26 3:04 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> The discussion around subsystems disrupts the flow of discussion in the surrounding area, which only deals with starting points used for the git.git project. So move this bullet point out to the end. Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b89678cedc3..7919a362e31 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -35,14 +35,14 @@ change is relevant to. to stabilize, you would have to rebase it (see the "depends on other topics" above). -* Some parts of the system have dedicated maintainers with their own - repositories (see the section "Subsystems" below). Changes to - these parts should be based on their trees. - To find the tip of a topic branch, run `git log --first-parent master..seen` and look for the merge commit. The second parent of this commit is the tip of the topic branch. +Finally, note that some parts of the system have dedicated maintainers +with their own separate source code repositories (see the section +"Subsystems" below). + [[separate-commits]] === Make separate commits for logically separate changes. -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [PATCH v3 3/5] SubmittingPatches: de-emphasize branches as starting points 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 2023-07-26 3:04 ` [PATCH v3 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget 2023-07-26 3:04 ` [PATCH v3 2/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget @ 2023-07-26 3:04 ` Linus Arver via GitGitGadget 2023-07-26 3:05 ` [PATCH v3 4/5] SubmittingPatches: emphasize need to communicate non-default " Linus Arver via GitGitGadget ` (5 subsequent siblings) 8 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-26 3:04 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> It could be that a suitable branch does not exist, so instead just use the phrase "starting point". Technically speaking the starting point would be a commit (not a branch) anyway. Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 7919a362e31..f1d1446764b 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -7,8 +7,8 @@ Here are some guidelines for contributing back to this project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. -[[base-branch]] -=== Decide what to base your work on. +[[choose-starting-point]] +=== Choose a starting point. In general, always base your work on the oldest branch that your change is relevant to. @@ -317,8 +317,8 @@ Please make sure your patch does not add commented out debugging code, or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before -sending out, please make sure it cleanly applies to the base you -have chosen in the "Decide what to base your work on" section, +sending out, please make sure it cleanly applies to the starting point you +have chosen in the "Choose a starting point" section, and unless it targets the `master` branch (which is the default), mark your patches as such. -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [PATCH v3 4/5] SubmittingPatches: emphasize need to communicate non-default starting points 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (2 preceding siblings ...) 2023-07-26 3:04 ` [PATCH v3 3/5] SubmittingPatches: de-emphasize branches as starting points Linus Arver via GitGitGadget @ 2023-07-26 3:05 ` Linus Arver via GitGitGadget 2023-07-26 3:05 ` [PATCH v3 5/5] SubmittingPatches: simplify guidance for choosing a starting point Linus Arver via GitGitGadget ` (4 subsequent siblings) 8 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-26 3:05 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> The phrase and unless it targets the `master` branch (which is the default), mark your patches as such. is tightly packed with several things happening in just two lines of text. It also feels like it is not that important because of the terse treatment. This is a problem because (1) it has the potential to confuse new contributors, and (2) it may be glossed over for those skimming the docs. Emphasize and elaborate on this guidance by promoting it to its own separate paragraph. Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index f1d1446764b..40467372c0d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -318,9 +318,12 @@ or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before sending out, please make sure it cleanly applies to the starting point you -have chosen in the "Choose a starting point" section, -and unless it targets the `master` branch (which is the default), -mark your patches as such. +have chosen in the "Choose a starting point" section. + +NOTE: From the perspective of those reviewing your patch, the `master` +branch is the default expected starting point. So if you have chosen a +different starting point, please communicate this choice in your cover +letter. [[send-patches]] -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* [PATCH v3 5/5] SubmittingPatches: simplify guidance for choosing a starting point 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (3 preceding siblings ...) 2023-07-26 3:05 ` [PATCH v3 4/5] SubmittingPatches: emphasize need to communicate non-default " Linus Arver via GitGitGadget @ 2023-07-26 3:05 ` Linus Arver via GitGitGadget 2023-07-26 5:15 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Junio C Hamano ` (3 subsequent siblings) 8 siblings, 0 replies; 38+ messages in thread From: Linus Arver via GitGitGadget @ 2023-07-26 3:05 UTC (permalink / raw) To: git; +Cc: Linus Arver, Linus Arver From: Linus Arver <linusa@google.com> Background: The guidance to "base your work on the oldest branch that your change is relevant to" was added in d0c26f0f56 (SubmittingPatches: Add new section about what to base work on, 2010-04-19). That commit also added the bullet points which describe the scenarios where one would use one of the following named branches: "maint", "master", "next", and "seen" ("pu" in the original as that was the name of this branch before it was renamed, per 828197de8f (docs: adjust for the recent rename of `pu` to `seen`, 2020-06-25)). The guidance was probably taken from existing similar language introduced in the "Merge upwards" section of gitworkflows in f948dd8992 (Documentation: add manpage about workflows, 2008-10-19). Summary: This change simplifies the guidance by pointing users to just "maint" or "master" for most cases. But it also gives an explanation of why that is preferred and what is meant by preferring "older" branches (which might be confusing to some because "old" here is meant in relative terms between these named branches, not in terms of the age of the branches themselves). We also explain in detail why it would be a bad idea to use "next" or "seen" as starting points, which may not be so obvious to new contributors. Helped-by: Jonathan Nieder <jrnieder@gmail.com> Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Linus Arver <linusa@google.com> --- Documentation/SubmittingPatches | 105 +++++++++++++++++++++++--------- 1 file changed, 77 insertions(+), 28 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 40467372c0d..559c02c90c5 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,34 +10,83 @@ available which covers many of these same guidelines. [[choose-starting-point]] === Choose a starting point. -In general, always base your work on the oldest branch that your -change is relevant to. - -* A bugfix should be based on `maint` in general. If the bug is not - present in `maint`, base it on `master`. For a bug that's not yet - in `master`, find the topic that introduces the regression, and - base your work on the tip of the topic. - -* A new feature should be based on `master` in general. If the new - feature depends on other topics that are in `next`, but not in - `master`, fork a branch from the tip of `master`, merge these topics - to the branch, and work on that branch. You can remind yourself of - how you prepared the base with `git log --first-parent master..`. - -* Corrections and enhancements to a topic not yet in `master` should - be based on the tip of that topic. If the topic has not been merged - to `next`, it's alright to add a note to squash minor corrections - into the series. - -* In the exceptional case that a new feature depends on several topics - not in `master`, start working on `next` or `seen` privately and - send out patches only for discussion. Once your new feature starts - to stabilize, you would have to rebase it (see the "depends on other - topics" above). - -To find the tip of a topic branch, run `git log --first-parent -master..seen` and look for the merge commit. The second parent of this -commit is the tip of the topic branch. +As a preliminary step, you must first choose a starting point for your +work. Typically this means choosing a branch, although technically +speaking it is actually a particular commit (typically the HEAD, or tip, +of the branch). + +There are several important branches to be aware of. Namely, there are +four integration branches as discussed in linkgit:gitworkflows[7]: + +* maint +* master +* next +* seen + +The branches lower on the list are typically descendants of the ones +that come before it. For example, `maint` is an "older" branch than +`master` because `master` usually has patches (commits) on top of +`maint`. + +There are also "topic" branches, which contain work from other +contributors. Topic branches are created by the Git maintainer (in +their fork) to organize the current set of incoming contributions on +the mailing list, and are itemized in the regular "What's cooking in +git.git" announcements. To find the tip of a topic branch, run `git log +--first-parent master..seen` and look for the merge commit. The second +parent of this commit is the tip of the topic branch. + +There is one guiding principle for choosing the right starting point: in +general, always base your work on the oldest integration branch that +your change is relevant to (see "Merge upwards" in +linkgit:gitworkflows[7]). What this principle means is that for the +vast majority of cases, the starting point for new work should be the +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 --containx 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`. + +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 +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 +overlap with the other person's work. This situation may tempt you to +use `next` as your starting point (because it would have the other +person's work included in it), but doing so would mean you'll not only +depend on the other person's work, but all the other random things from +other contributors that are already integrated into `next`. And as soon +as `next` is updated with a new version, all of your work will need to +be rebased anyway in order for them to be cleanly applied by the +maintainer. + +Under truly exceptional circumstances where you absolutely must depend +on a select few topic branches that are already in `next` but not in +`master`, you may want to create your own custom base-branch by forking +`master` and merging the required topic branches to it. You could then +work on top of this base-branch. But keep in mind that this base-branch +would only be known privately to you. So when you are ready to send +your patches to the list, be sure to communicate how you created it in +your cover letter. This critical piece of information would allow +others to recreate your base-branch on their end in order for them to +try out your work. Finally, note that some parts of the system have dedicated maintainers with their own separate source code repositories (see the section -- gitgitgadget ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH v3 0/5] SubmittingPatches: clarify which branch to use 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (4 preceding siblings ...) 2023-07-26 3:05 ` [PATCH v3 5/5] SubmittingPatches: simplify guidance for choosing a starting point Linus Arver via GitGitGadget @ 2023-07-26 5:15 ` Junio C Hamano 2023-07-26 17:19 ` Linus Arver 2023-07-26 5:16 ` [PATCH v3 6/5] SubmittingPatches: choice of base for fixing an older maintenance track Junio C Hamano ` (2 subsequent siblings) 8 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2023-07-26 5:15 UTC (permalink / raw) To: Linus Arver via GitGitGadget; +Cc: git, Linus Arver "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: > This series rewords the "base-branch" section (now renamed to > "choose-starting-point") to be more informative in general to new > contributors, who may not be as familiar with the various integration > branches. Other smaller cleanups and improvements were made along the way. Well, both of us forgot that the previous round has already been in 'next' for quite a while. So, I've split the difference between the previous round and the result of applying this round into two patches, and then added a bit of fix-ups on top. I'll send them out shortly. Thanks. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH v3 0/5] SubmittingPatches: clarify which branch to use 2023-07-26 5:15 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Junio C Hamano @ 2023-07-26 17:19 ` Linus Arver 0 siblings, 0 replies; 38+ messages in thread From: Linus Arver @ 2023-07-26 17:19 UTC (permalink / raw) To: Junio C Hamano, Linus Arver via GitGitGadget; +Cc: git Junio C Hamano <gitster@pobox.com> writes: > Well, both of us forgot that the previous round has already been in > 'next' for quite a while. > > So, I've split the difference between the previous round and the > result of applying this round into two patches, and then added a bit > of fix-ups on top. ... Sorry about that (but also, I didn't know any better). So I guess the guidance is: Sometimes, you may want to work on a topic (typically your own) which has already been in `next` for quite a while. Perhaps you had an unplanned break of a couple weeks, or some other circumstance. In such cases, consider sending out patches that build on top of the latest patch series round instead of directly modifying (locally rebasing) the patches for a new series. This way, your new changes will be easier to apply to `next` as is, without rebuilding `next` all over again. Would you prefer to include this guidance in the docs as well, or is it sufficiently rare enough that we shouldn't include it? ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH v3 6/5] SubmittingPatches: choice of base for fixing an older maintenance track 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (5 preceding siblings ...) 2023-07-26 5:15 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Junio C Hamano @ 2023-07-26 5:16 ` Junio C Hamano 2023-07-26 5:40 ` Eric Sunshine 2023-07-26 5:17 ` [PATCH 7/5] SubmittingPatches: explain why 'next' and above are inappropriate base Junio C Hamano 2023-07-26 5:21 ` [PATCH 8/5] SubmittingPatches: use of older maintenance tracks is an exception Junio C Hamano 8 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2023-07-26 5:16 UTC (permalink / raw) To: Linus Arver via GitGitGadget; +Cc: git, Linus Arver 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 <linusa@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/SubmittingPatches | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index f1774c91e9..d1e3783978 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 --containx 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`. -- 2.41.0-450-ga80be15292 ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH v3 6/5] SubmittingPatches: choice of base for fixing an older maintenance track 2023-07-26 5:16 ` [PATCH v3 6/5] SubmittingPatches: choice of base for fixing an older maintenance track Junio C Hamano @ 2023-07-26 5:40 ` Eric Sunshine 2023-07-26 16:36 ` Junio C Hamano 0 siblings, 1 reply; 38+ messages in thread From: Eric Sunshine @ 2023-07-26 5:40 UTC (permalink / raw) To: Junio C Hamano; +Cc: Linus Arver via GitGitGadget, git, Linus Arver On Wed, Jul 26, 2023 at 1:38 AM Junio C Hamano <gitster@pobox.com> wrote: > 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 <linusa@google.com> > Signed-off-by: Junio C Hamano <gitster@pobox.com> > --- > diff --git 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 --containx X` says `v2.30.0-rc2-gXXXXXX` has it), then s/containx/contains/ > + 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]. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH v3 6/5] SubmittingPatches: choice of base for fixing an older maintenance track 2023-07-26 5:40 ` Eric Sunshine @ 2023-07-26 16:36 ` Junio C Hamano 0 siblings, 0 replies; 38+ messages in thread From: Junio C Hamano @ 2023-07-26 16:36 UTC (permalink / raw) To: Eric Sunshine; +Cc: Linus Arver via GitGitGadget, git, Linus Arver Eric Sunshine <sunshine@sunshineco.com> writes: >> + `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 --containx X` says `v2.30.0-rc2-gXXXXXX` has it), then > > s/containx/contains/ Thanks. ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH 7/5] SubmittingPatches: explain why 'next' and above are inappropriate base 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (6 preceding siblings ...) 2023-07-26 5:16 ` [PATCH v3 6/5] SubmittingPatches: choice of base for fixing an older maintenance track Junio C Hamano @ 2023-07-26 5:17 ` Junio C Hamano 2023-07-27 19:26 ` Linus Arver 2023-07-26 5:21 ` [PATCH 8/5] SubmittingPatches: use of older maintenance tracks is an exception Junio C Hamano 8 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2023-07-26 5:17 UTC (permalink / raw) To: Linus Arver via GitGitGadget; +Cc: git, Linus Arver 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 <linusa@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/SubmittingPatches | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d1e3783978..559c02c90c 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 -- 2.41.0-450-ga80be15292 ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH 7/5] SubmittingPatches: explain why 'next' and above are inappropriate base 2023-07-26 5:17 ` [PATCH 7/5] SubmittingPatches: explain why 'next' and above are inappropriate base Junio C Hamano @ 2023-07-27 19:26 ` Linus Arver 0 siblings, 0 replies; 38+ messages in thread From: Linus Arver @ 2023-07-27 19:26 UTC (permalink / raw) To: Junio C Hamano, Linus Arver via GitGitGadget; +Cc: git Junio C Hamano <gitster@pobox.com> writes: > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index d1e3783978..559c02c90c 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 s/'master'/`master` (Sorry I missed this in my patch.) ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH 8/5] SubmittingPatches: use of older maintenance tracks is an exception 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget ` (7 preceding siblings ...) 2023-07-26 5:17 ` [PATCH 7/5] SubmittingPatches: explain why 'next' and above are inappropriate base Junio C Hamano @ 2023-07-26 5:21 ` Junio C Hamano 2023-07-27 19:35 ` Linus Arver 8 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2023-07-26 5:21 UTC (permalink / raw) To: Linus Arver via GitGitGadget; +Cc: git, Linus Arver 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 to just fix it in the current maintenance track, leaving the bug unfixed in the older maintenance tracks. Demote the "use older maintenance track" as a side note, and explain that the choice is used only in exceptional cases. Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/SubmittingPatches | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 559c02c90c..0d1b53d4e5 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 --containx 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 an exceptional case, 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 as +`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 -- 2.41.0-450-ga80be15292 ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH 8/5] SubmittingPatches: use of older maintenance tracks is an exception 2023-07-26 5:21 ` [PATCH 8/5] SubmittingPatches: use of older maintenance tracks is an exception Junio C Hamano @ 2023-07-27 19:35 ` Linus Arver 2023-07-27 20:08 ` Junio C Hamano 0 siblings, 1 reply; 38+ messages in thread From: Linus Arver @ 2023-07-27 19:35 UTC (permalink / raw) To: Junio C Hamano, Linus Arver via GitGitGadget; +Cc: git Thank you for breaking out these patches (in the future I will try to do it on my end to save you the trouble). I just have small wording nits (see below), but otherwise LGTM. Thanks again. Junio C Hamano <gitster@pobox.com> writes: > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index 559c02c90c..0d1b53d4e5 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 --containx 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 an exceptional case, a bug that was introduced in an old I think "In exceptional cases" reads more naturally. > +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 as s/as/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 > -- > 2.41.0-450-ga80be15292 ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 8/5] SubmittingPatches: use of older maintenance tracks is an exception 2023-07-27 19:35 ` Linus Arver @ 2023-07-27 20:08 ` Junio C Hamano 0 siblings, 0 replies; 38+ messages in thread From: Junio C Hamano @ 2023-07-27 20:08 UTC (permalink / raw) To: Linus Arver; +Cc: Linus Arver via GitGitGadget, git Linus Arver <linusa@google.com> writes: > I just have small wording nits (see below), but otherwise LGTM. Thanks. Rolled typo/format fixes in. 1: e3386ce69d ! 1: f835de52d7 SubmittingPatches: explain why 'next' and above are inappropriate base @@ Documentation/SubmittingPatches: latest HEAD commit of `maint` or `master` based +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 ++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. 2: 6b2650d32f ! 2: 369998df83 SubmittingPatches: use of older maintenance tracks is an exception @@ Documentation/SubmittingPatches: latest HEAD commit of `maint` or `master` based * Otherwise (such as if you are adding new features) use `master`. + -+NOTE: In an exceptional case, a bug that was introduced in an old ++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 as ++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]. + ^ permalink raw reply [flat|nested] 38+ messages in thread
end of thread, other threads:[~2023-07-27 20:08 UTC | newest] Thread overview: 38+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2023-07-08 1:05 [PATCH 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 2023-07-08 1:05 ` [PATCH 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget 2023-07-08 5:37 ` Junio C Hamano 2023-07-08 1:05 ` [PATCH 2/5] SubmittingPatches: be more explicit Linus Arver via GitGitGadget 2023-07-08 5:36 ` Junio C Hamano 2023-07-13 21:03 ` Linus Arver 2023-07-13 21:10 ` Junio C Hamano 2023-07-08 1:05 ` [PATCH 3/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget 2023-07-08 1:05 ` [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches Linus Arver via GitGitGadget 2023-07-08 5:48 ` Junio C Hamano 2023-07-13 21:54 ` Linus Arver 2023-07-08 1:05 ` [PATCH 5/5] SubmittingPatches: define topic branches Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 2/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 3/5] SubmittingPatches: de-emphasize branches as starting points Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 4/5] SubmittingPatches: emphasize need to communicate non-default " Linus Arver via GitGitGadget 2023-07-14 6:01 ` [PATCH v2 5/5] SubmittingPatches: simplify guidance for choosing a starting point Linus Arver via GitGitGadget 2023-07-14 17:31 ` Junio C Hamano 2023-07-26 1:36 ` Linus Arver 2023-07-26 2:31 ` Linus Arver 2023-07-26 4:41 ` Junio C Hamano 2023-07-26 3:04 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Linus Arver via GitGitGadget 2023-07-26 3:04 ` [PATCH v3 1/5] SubmittingPatches: reword awkward phrasing Linus Arver via GitGitGadget 2023-07-26 3:04 ` [PATCH v3 2/5] SubmittingPatches: discuss subsystems separately from git.git Linus Arver via GitGitGadget 2023-07-26 3:04 ` [PATCH v3 3/5] SubmittingPatches: de-emphasize branches as starting points Linus Arver via GitGitGadget 2023-07-26 3:05 ` [PATCH v3 4/5] SubmittingPatches: emphasize need to communicate non-default " Linus Arver via GitGitGadget 2023-07-26 3:05 ` [PATCH v3 5/5] SubmittingPatches: simplify guidance for choosing a starting point Linus Arver via GitGitGadget 2023-07-26 5:15 ` [PATCH v3 0/5] SubmittingPatches: clarify which branch to use Junio C Hamano 2023-07-26 17:19 ` Linus Arver 2023-07-26 5:16 ` [PATCH v3 6/5] SubmittingPatches: choice of base for fixing an older maintenance track Junio C Hamano 2023-07-26 5:40 ` Eric Sunshine 2023-07-26 16:36 ` Junio C Hamano 2023-07-26 5:17 ` [PATCH 7/5] SubmittingPatches: explain why 'next' and above are inappropriate base Junio C Hamano 2023-07-27 19:26 ` Linus Arver 2023-07-26 5:21 ` [PATCH 8/5] SubmittingPatches: use of older maintenance tracks is an exception Junio C Hamano 2023-07-27 19:35 ` Linus Arver 2023-07-27 20:08 ` Junio C Hamano
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).