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@xxxxxxxxx>
Helped-by: Junio C Hamano <gitster@xxxxxxxxx>
@@ 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
