Subject: Re: [PATCH] Documentation/howto: tracking git.git

From: Junio C Hamano <[email-masked]>
Date: Fri, 14 May 2021 22:49:52 +0900

Bagas Sanjaya <[email-masked]> writes:

> +Available Branches
> +------------------
> +
> +There are several branches on git.git with different purposes:
> +
> +master::
> +This is the most stable branch. Changes (topics) that are merged
> +to master should have been stabilized in next and suitable for
> +production use. Feature releases (vX.Y.0) are cut from this
> +branch.

Isn't "maint" meant to be more stable?

> +next::
> +This is where topics that haven't been yet merged to master are
> +stabilized and tested for breakage and regressions. It gives
> +a summary forecast of what next batch of topics that will be
> +merged to master looks like.
> +
> +seen::
> +This is the most bleeding edge branch where all excited
> +developments happened. All proposed topics are queued in seen
> +by the maintainer. However, these may be buggy (have breakage or
> +regressions). When topics queued are deemed good and ready for
> +inclusion, they are graduated to next for stabilization.

This is inconsistent with what has been written elsewhere about this
integration branch.  In short, you should not read anything more
than "the maintainer happens to have seen these topics" out of the
fact that a topic is in 'seen'.  Not all proposed topics will be in
this branch, and a branch that was in 'seen' on one day may not be
there the next day, but that does not mean anything (certainly it
does not mean the topic has been "rejected").

> +Tracking
> +--------
> +
> +If you don't have git.git clone handy, you can obtain one by:
> +
> +----
> +$ git clone https://github.com/git/git.git git
> +----
> +
> +Now you can start hacking your topics. Don't forget to read
> +`Documentation/SubmittingPatches` for instructions on patch
> +submission.
> +
> +After some time, there will be updates to git.git. First, fetch them:
> +
> +----
> +$ git fetch origin
> +----
> +
> +Then pull the updates.
> +
> + - For `master`, `next`, `maint`, and `todo`, you can do fast-forward
> +   pull:
> +
> + $ git pull --ff-only

I do not see a point in doing this for all of these branches, and
I'd rather not to see this recommended to people who "track to
develop" at all.  It may make sense to do so if you do not do any
development of your own and will always stay on 'master' to check
out, build, test and install from the upstream, though.

For those who track to develop", if you want a reference point to
work from, you can do "git fetch origin" and then run

    $ git checkout -b mytopic origin/master

for a new feature, and

    $ git checkout -b myfix origin/maint

for a fix.  You can track your progress with

    $ git log origin/master..mytopic
    $ git log origin/master..myfix

If you are fixing a longstanding bug, you may even want to do

    $ git checkout -b myfix-for-2.29-and-above v2.29.3
    $ git log origin/master..myfix-for-2.29-and-above

To test your various topics, you would then do

    $ git checkout -B trial origin/master
    $ git merge mytopic
    $ git merge myfix
    ... build, test, install, employ it for daily use ...

And you can make sure you do not step on toes of others by doing
trial merges

    $ git checkout -B trial origin/seen ;# or origin/next
    $ git merge mytopic
    $ git merge myfix
    ... build and test

which is highly recommended.  This will give you a chance to notice
who, if any, are working in areas of the codebase that potentially
overlaps with what you are working on before you even send out your
series for review.

> + - For `seen`, DO NOT pull with `git pull`. This is because seen is
> +   in constant flux, and most often your local seen is divergent from
> +   the origin, caused by force-push from the maintainer. Attempting
> +   to pull either via merge or rebase will most likely end in
> +   conflict. Instead, pull by resetting the local seen to the origin:
> +
> + $ git reset --hard origin/seen

Even better, do not even create your own 'seen' branch at all.  If
you are interested in what is going on

    $ git log --first-parent --oneline origin/master..origin/seen

might be worth paying attention to, and checking out the tip of
topics of other people you seen in the output and playing with it on
a detached HEAD may also be useful, and if you find bugs in other's
work, you can futz with the code from that commit and you may end up
with a patch you can send as an improvement suggestion to the
original author of the topic.  But 'seen' as a whole is rarely of
interest, except for the purpose of learning what other topics may
be in flight.  Nobody sane is supposed to be running the version
from 'seen'; after all, the selection criteria of the topics in it
is "some of the topics that the maintainer happened to have seen",
and not even "these topics are interesting, promising and are wished
to be in 'next' someday".