Re: [RFC PATCH v2] Documentation: add manpage about workflows

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 9, 2008, 12:50 UTC
Message-ID: <7v8wsyortf.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <1223552537-6918-1-git-send-email-trast@student.ethz.ch>

Thomas Rast <trast@student.ethz.ch> writes:

Show 16 quoted lines

> diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
> new file mode 100644
> index 0000000..037ace5
> --- /dev/null
> +++ b/Documentation/gitworkflows.txt
> @@ -0,0 +1,362 @@
> +gitworkflows(7)
> +===============
> ...
> +DESCRIPTION
> +-----------
> +
> +This document attempts to write down and motivate some of the workflow
> +elements used for `git.git` itself.  Many ideas apply in general,
> +though the full workflow is rarely required for smaller projects with
> +fewer people involved.

Hmm. Even though I have to wonder if the workflow used in git.git should be treated as a representative BCP. For one thing, git.git is on the smaller end of the spectrum (from the point of view of the size of the codebase, but not from the size of the contributor base), it is something we know well enough and probably is a good place to take examples from.

Show 14 quoted lines

> +Graduation
> +~~~~~~~~~~
> +
> +As a given feature goes from experimental to stable, it also
> +"graduates" between the corresponding branches of the software.
> +`git.git` uses the following 'main branches':
> +
> +* 'maint' tracks the commits that should go into the next "maintenance
> +  release", i.e., update of the last released stable version;
> +
> +* 'master' tracks the commits that should go into the next release;
> +
> +* 'next' is intended as a testing branch for topics not stable enough
> +  for master yet.

s/not stable enough/being tested for stability/;s/ yet//;

The point being that commits on next are deemed stable enough from code inspection but are kept out of master for a while because your maintainer wants to be extra careful.

Show 15 quoted lines

> +Topic branches
> +~~~~~~~~~~~~~~
> +
> +Any nontrivial feature will require several patches to implement, and
> +may get extra bugfixes or improvements during its lifetime.
> +
> +Committing everything directly on the main branches leads to many
> +problems: Bad commits cannot be undone, so they must be reverted one
> +by one, which creates confusing histories and further error potential
> +when you forget to revert part of a group of changes.  Working in
> +parallel mixes up the changes, creating further confusion.
> +
> +The key concept here is "topic branches".  The name is pretty self
> +explanatory, with a caveat that comes from the "merge upwards" rule
> +above:

I'd reword the first sentence --- Use of "Topic branches" solves these problems.

Show 19 quoted lines

> +We should point out that "habitually" (regularly for no real reason)
> +merging a main branch into your topics -- and by extension, merging
> +anything upstream into anything downstream on a regular basis -- is
> +frowned upon:
> +
> +.Merge to downstream only at well-defined points
> +[caption="Rule: "]
> +=====================================
> +Do not merge to downstream except:
> +
> +* with a good reason: upstream API changes affect your branch; your
> +  branch no longer merges to upstream cleanly; etc.
> +
> +* at well-defined points such as when an upstream release has been tagged.
> +=====================================
> +
> +Otherwise, the many resulting small merges will greatly clutter up
> +history.  Anyone who later investigates the history of a file will
> +have to find out whether that merge affected the topic in development.

This description misses the most important reason why merging into topic branches is not a good idea. Once you merge a general purpose integration branch such as master into a topic branch, the branch ceases to be about the single topic. It becomes "the topic and other unrelated changes mixed together".

> +Integration branches
> +~~~~~~~~~~~~~~~~~~~~

Nomenclature. I think we use the word "integration branches" to mean the stable branches such as maint/master/next, not the ones you use for throw-away test merges.

Always merging upward is a good rule, and this is when used with topic branches, there is one twist you did not mention but is worth knowing about. A topic that is meant to eventually merge into older integration branch (e.g. maint) does not necessarily have to be merged to its final destination branch first. I often do this:

	git checkout tr/maint-fix-bla maint
        git am -s fix-mail-from-thomas.txt
        git checkout next
        git merge tr/maint-fix-bla
        ... cook further, perhaps adding more commits to
        ... tr/maint-fix-bla topic and merging the result to next;
	... and then when the topic appears to be stable do:
	git checkout master
        git merge tr/maint-fix-bla
	... and later
        git checkout maint
        git merge tr/maint-fix-bla
	git branch -d tr/maint-fix-bla

This keeps older integration branches stale, until the topic really gets proven to be regression-free in the field. This workflow is safer and more suitable for a final integration branch to which a known breakage is better than an unintended regression. An alternative would be what the reader would assume from your description of merging upwards, which would look like this:

	git checkout tr/maint-fix-bla maint
        git am -s fix-mail-from-thomas.txt
        git checkout maint
        git merge tr/maint-fix-bla
	git checkout master
        git merge maint
        git checkout next
	git merge master

This can regress maint unintentionally and then the regression is propagated upwards to contaminate all integration branches.