Re: [PATCHv3] Add branch management for releases to gitworkflows

From

Nanako Shiraishi <nanako3@lavabit.com>

Date

Nov 13, 2009, 22:19 UTC

Message-ID

<20091114071946.6117@nanako3.lavabit.com>

In-Reply-To

<1258055164-11876-2-git-send-email-rocketraman@fastmail.fm>

Quoting rocketraman@fastmail.fm

> From: Raman Gupta <raman@rocketraman.com>
>
> The current man page does a reasonable job at describing branch management
> during the development process, but it does not contain any guidance as to
> how the branches are affected by releases.
>
> Add a basic introduction to the branch management undertaken during a
> git.git release, so that a reader may gain some insight into how the
> integration, maintenance, and topic branches are affected during the
> release transition, and is thus able to better design the process for their
> own project.
>
> Other release activities such as reviews, testing, and creating
> distributions are currently out of scope.
> ---

You are missing Signed-off-by: line. 

Here are some corrections that can be applied on top of your change.

-- >8 --
Subject: [PATCH] Corrections to release management section in gitworkflows.txt

        - doubly make sure that there is nothing left in 'maint' that
          is not in 'master';

Other minor clarifications in the text are also included in this change:

 * Clarify "building documentation" a bit; the post-update hook
   creates preformatted documentation pages.

 * The latest documentation set uses "fast-forward", not "fast
   forward".

 * Call 'next' branch an integration branch, not a "testing" branch, to be
   consistent with the Graduation section.

Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com>
---
 Documentation/gitworkflows.txt |   57 +++++++++++++++++++++------------------
 1 files changed, 31 insertions(+), 26 deletions(-)

diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 7000930..b1c7ef3 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -216,8 +216,19 @@ Assuming you are using the merge approach discussed above, when you
 are releasing your project you will need to do some additional branch
 management work.
 
-Creating a release is easy. Since 'master' is tracking the commits
-that should go into the next feature release, simply tag the tip of
+Since 'master' is supposed to be always a superset of 'maint', you
+should first make sure that condition holds.
+
+.Make sure 'maint' fast-forwards to 'master'
+[caption="Recipe: "]
+=====================================
+git log master..maint
+=====================================
+
+There should be no commit listed from this command (otherwise, check
+out 'master' and merge 'maint' into it).
+
+Then you can tag the tip of
 'master' with a tag indicating the release version.
 
 .Release tagging
@@ -230,11 +241,15 @@ Similarly, for a maintenance release, 'maint' is tracking the commits
 to be released. Therefore, simply replace 'master' above with
 'maint'.
 
-Generally, you should push the new tag to a public git server (see
+You need to push the new tag to a public git server,
+at the same time you push the updated 'master' or 'maint',
+if you are making a maintenance release. (see
 "DISTRIBUTED WORKFLOWS" below). This push makes the tag available to
 others tracking your project. The push could also trigger a
 post-update hook to perform release-related items such as building
-documentation.
+release tarballs and preformatted documentation pages.  You may want
+to wait this push-out before you update your 'maint' branch (see the
+next section).
 
 
 Maintenance branch management after a feature release
@@ -256,47 +271,37 @@ where X.Y.Z is the current release).
 `git branch maint-X.Y.(Z-1) maint`
 =====================================
 
-The 'maint' branch should now be fast forwarded to the newly released
+The 'maint' branch should now be fast-forwarded to the newly released
 code so that maintenance fixes can be tracked for the current release:
 
 .Update maint to new release
 [caption="Recipe: "]
 =====================================
-* `git checkout maint`
-* `git merge master`
+* `git checkout maint`
+* `git merge --ff-only master`
 =====================================
 
-This 'should' fast forward 'maint' from 'master'. If it is not a fast
-forward, then 'maint' contained some commits that were not included on
+This should fast-forward 'maint' from 'master'. If it is not a
+fast-forward, then 'maint' contained some commits that were not included on
 'master', which means that the recent feature release could be missing
-some fixes made on 'maint'. The exception is if there were any commits
-that were cherry-picked to 'maint' as described above in "Merging
-upwards". In this case, the merge will not be a fast forward.
-
-An alternative approach to updating the 'maint' branch, though one
-not used in git.git, is to rename the current 'maint' branch to track
-maintenance fixes for the older release and then to recreate 'maint'
-from 'master':
-
-  $ git branch -m maint maint-X.Y.(Z-1)
-  $ git branch maint master
-
-The latter step will create a new 'maint' branch based on 'master'. If
-commits were cherry-picked to 'maint', then this will create a new
-'maint' branch without a merge commit.
+some fixes made on 'maint'.  If that happens, you need to go back to the
+previous "Branch management for a release" step.  Correcting this mistake
+becomes messy if you have already pushed the release tag, and that is why
+you should wait until finishing this step before pushing the release out.
 
 
 Branch management for next and pu after a feature release
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-After a feature release, the 'next' testing branch may optionally be
+After a feature release, the integration branch 'next' may optionally be
 rewound and rebuilt from the tip of 'master' using the surviving
 topics on 'next':
 
 .Update maint to new release
 [caption="Recipe: "]
 =====================================
-* `git branch -f next master`
+* `git checkout next`
+* `git reset --hard master`
 * `git merge ai/topic_in_next1`
 * `git merge ai/topic_in_next2`
 * ...

-- 
1.6.5.2.159.g67ee8

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/