Re: [PATCH 4/5] SubmittingPatches: remove confusing guidance about base branches

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 8, 2023, 05:48 UTC
Message-ID: <xmqqa5w76jig.fsf@gitster.g>
In-Reply-To: <55bed55cb8859ac7b5b4f464232258f410b4d202.1688778359.git.gitgitgadget@gmail.com>

"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?

Show 11 quoted lines

> -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.