| Message ID | pull.1556.v3.git.1690340701.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | SubmittingPatches: clarify which branch to use | expand |
"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.
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?
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