[Interdiff] [RFC PATCH v3] Documentation: add manpage about workflows
---
Documentation/gitworkflows.txt | 72 ++++++++++++++++++++-------------------
1 files changed, 37 insertions(+), 35 deletions(-)
diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 037ace5..7fe9f72 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -72,15 +72,15 @@ 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':
+`git.git` uses the following 'integration 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.
+* 'next' is intended as a testing branch for topics being tested for
+ stability for master.
There is a fourth official branch that is used slightly differently:
@@ -107,7 +107,7 @@ the unstable branch into the stable one. Hence the following:
[caption="Rule: "]
=====================================
Always commit your fixes to the oldest supported branch that require
-them. Then (periodically) merge the main branches upwards into each
+them. Then (periodically) merge the integration branches upwards into each
other.
=====================================
@@ -124,28 +124,32 @@ 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
+Committing everything directly on the integration 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:
+Use of "topic branches" solves these problems. The name is pretty
+self explanatory, with a caveat that comes from the "merge upwards"
+rule above:
.Topic branches
[caption="Rule: "]
=====================================
Make a side branch for every topic (feature, bugfix, ...). Fork it off
-at the oldest main branch that you will eventually want to merge it
+at the oldest integration branch that you will eventually want to merge it
into.
=====================================
Many things can then be done very naturally:
-* To get the feature/bugfix into a main branch, simply merge it. If
- the topic has evolved further in the meantime, merge again.
+* To get the feature/bugfix into an integration branch, simply merge
+ it. If the topic has evolved further in the meantime, merge again.
+ (Note that you do not necessarily have to merge it to the oldest
+ integration branch first. For example, you can first merge a bugfix
+ to 'next', give it some testing time, and merge to 'maint' when you
+ know it is stable.)
* If you find you need new features from the branch 'other' to continue
working on your topic, merge 'other' to 'topic'. (However, do not
@@ -154,35 +158,33 @@ Many things can then be done very naturally:
* If you find you forked off the wrong branch and want to move it
"back in time", use linkgit:git-rebase[1].
-Note that the last two points clash: a topic that has been merged
-elsewhere should not be rebased. See the section on RECOVERING FROM
-UPSTREAM REBASE in linkgit:git-rebase[1].
+Note that the last point clashes with the other two: a topic that has
+been merged elsewhere should not be rebased. See the section on
+RECOVERING FROM UPSTREAM REBASE in linkgit:git-rebase[1].
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:
+merging an integration 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.
+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.
=====================================
-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.
-An upstream might even inadvertently be merged into a "more stable"
-branch. And so on.
+Otherwise, the topic that was merged to suddenly contains more than a
+single (well-separated) change. 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. An upstream might even inadvertently be merged into a
+"more stable" branch. And so on.
-Integration branches
-~~~~~~~~~~~~~~~~~~~~
+Throw-away integration
+~~~~~~~~~~~~~~~~~~~~~~
If you followed the last paragraph, you will now have many small topic
branches, and occasionally wonder how they interact. Perhaps the
@@ -193,7 +195,7 @@ cannot easily be undone.
The solution, of course, is to make a merge that we can undo: merge
into a throw-away branch.
-.Integration branches
+.Throw-away integration branches
[caption="Rule: "]
=====================================
To test the interaction of several topics, merge them into a
@@ -204,7 +206,7 @@ If you make it (very) clear that this branch is going to be deleted
right after the testing, you can even publish this branch, for example
to give the testers a chance to work with it, or other developers a
chance to see if their in-progress work will be compatible. `git.git`
-has such an official integration branch called 'pu'.
+has such an official throw-away integration branch called 'pu'.
DISTRIBUTED WORKFLOWS
@@ -259,7 +261,7 @@ You will still have to tell people by other means, such as mail. (Git
provides the linkgit:request-pull[1] to send preformatted pull
requests to upstream maintainers to simplify this task.)
-If you just want to get the newest copies of the main branches,
+If you just want to get the newest copies of the integration branches,
staying up to date is easy too:
.Push/pull: Staying up to date
@@ -272,8 +274,8 @@ Then simply fork your topic branches from the stable remotes as
explained earlier.
If you are a maintainer and would like to merge other people's topic
-branches to the main branches, they will typically send a request to
-do so by mail. Such a request looks like
+branches to the integration branches, they will typically send a
+request to do so by mail. Such a request looks like
-------------------------------------
Please pull from
--
1.6.0.2.916.g8e7f4
Thomas Rast <trast@student.ethz.ch>