SubmittingPatches: simplify guidance for choosing a starting point
commit0a02ca2383455e40cfc0b1c0818479c2d36fe6cd
authorLinus Arver <linusa@google.com>
Fri, 14 Jul 2023 06:01:33 +0000 (14 06:01 +0000)
committerJunio C Hamano <gitster@pobox.com>
Fri, 14 Jul 2023 17:31:43 +0000 (14 10:31 -0700)
treeb863dd2a4692169ea378c14ba1150a2170c3f12b
parent5c98149ce4d5f57f5376fc38e512dade77a96f8b
SubmittingPatches: simplify guidance for choosing a starting point

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/SubmittingPatches