Add branch management for releases to gitworkflows

Add branch management for releases to gitworkflows

[rocketraman]

Version 3 of the gitworkflows patch follows.

This version of the patch attempts to incorporate all feedback received from Junio and Thomas. The main changes are:

1) Consistent use of pronouns in the imperative.

2) Reorganization to move the new text into the "MANAGING BRANCHES" section. This wasn't explicitly suggested by Junio or Thomas, but it makes sense as it clarifies that the content is not about releases in general, but how releases affect the branch structure previously described in the document.

3) Largely modified and reworded text, to conform to the new reorganization and to include feedback from Junio and Thomas.

Cheers,
Raman

[PATCHv3] Add branch management for releases to gitworkflows

[rocketraman]

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.
---
 Documentation/gitworkflows.txt |  108 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 108 insertions(+), 0 deletions(-)

diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 2b021e3..7000930 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -209,6 +209,114 @@ chance to see if their in-progress work will be compatible.  `git.git`
 has such an official throw-away integration branch called 'pu'.
 
 
+Branch management for a release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+'master' with a tag indicating the release version.
+
+.Release tagging
+[caption="Recipe: "]
+=====================================
+`git tag -s -m "GIT X.Y.Z" vX.Y.Z master`
+=====================================
+
+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
+"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.
+
+
+Maintenance branch management after a feature release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After a feature release, you need to manage your maintenance branches.
+
+First, if you wish to continue to release maintenance fixes for the
+feature release made before the recent one, then you must create
+another branch to track commits for that previous release.
+
+To do this, the current maintenance branch is copied to another branch
+named with the previous release version number (e.g. maint-X.Y.(Z-1)
+where X.Y.Z is the current release).
+
+.Copy maint
+[caption="Recipe: "]
+=====================================
+`git branch maint-X.Y.(Z-1) maint`
+=====================================
+
+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`
+=====================================
+
+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.
+
+
+Branch management for next and pu after a feature release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After a feature release, the 'next' testing branch 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 merge ai/topic_in_next1`
+* `git merge ai/topic_in_next2`
+* ...
+=====================================
+
+The advantage of doing this is that the history of 'next' will be
+clean. For example, some topics merged into 'next' may have initially
+looked promising, but were later found to be undesirable or premature.
+In such a case, the topic is reverted out of 'next' but the fact
+remains in the history that it was once merged and reverted. By
+recreating 'next', you give another incarnation of such topics a clean
+slate to retry, and a feature release is a good point in history to do
+so.
+
+If you do this, then you should make a public announcement indicating
+that 'next' was rewound and rebuilt.
+
+The same process may be followed for 'pu'.
+
+
 DISTRIBUTED WORKFLOWS
 ---------------------
 
-- 
1.6.2

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

[skillzero]

> +.Update maint to new release
> +[caption="Recipe: "]
> +=====================================
> +* `git branch -f next master`
> +* `git merge ai/topic_in_next1`
> +* `git merge ai/topic_in_next2`

Shouldn't that be something like "Update next to new release" instead
of "maint"?

Should it also have 'git checkout next' after the branch command so
it's on next before merging?

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

[Raman Gupta]

skillzero@gmail.com wrote:
>> +.Update maint to new release
>> +[caption="Recipe: "]
>> +=====================================
>> +* `git branch -f next master`
>> +* `git merge ai/topic_in_next1`
>> +* `git merge ai/topic_in_next2`
> 
> Shouldn't that be something like "Update next to new release" instead
> of "maint"?

Oops. I changed the caption to "Rewind and rebuild next".

> Should it also have 'git checkout next' after the branch command so
> it's on next before merging?

Right, fixed also.

Thanks,
Raman

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

[Nanako Shiraishi]

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

The maintenance branch is supposed to be a strict subset of the master
branch at all times. If you find out that this condition was violated
after you pushed a release from the master branch, it is too late.
Correcting that mistake will require redoing and retagging an already
published release.

In http://article.gmane.org/gmane.comp.version-control.git/132692, Junio
explained that the first step is:

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

to avoid that mistake.  Explain the exact procedure in a recipe format,
and make sure it is done before the tip of the master branch is tagged.
Also use --ff-only when merging master into maint.

Rebuilding of 'next' must be done on 'next' branch; correct the
command sequence in the recipe.

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/

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

[Raman Gupta]

Nanako Shiraishi wrote:
>  .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.

I noticed you removed the discussion I added about the situation in
which maint will *not* be a subset of master i.e. when the user has
cherry-picked commits from other branches. This type of cherry-pick is
described as a valid operation, though one to generally be avoided
earlier in the man page. If we tell users that the occasional
cherry-pick to maint is ok, then shouldn't we explain how that affects
the release process?

Cheers,
Raman

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

[Nanako Shiraishi]

Quoting Raman Gupta <rocketraman@fastmail.fm>

> Nanako Shiraishi wrote:
>>  .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.
>
> I noticed you removed the discussion I added about the situation in
> which maint will *not* be a subset of master i.e. when the user has
> cherry-picked commits from other branches. This type of cherry-pick is
> described as a valid operation, though one to generally be avoided
> earlier in the man page. If we tell users that the occasional
> cherry-pick to maint is ok, then shouldn't we explain how that affects
> the release process?

It is irrelevant that you can cherry-pick to 'maint'.

You can, and Junio does, cherry-pick some commits from master to 
maint from time to time. But even if you have such cherry-picked 
commits on the maintenance branch, the result, with zero or more 
other maintenance commits on top, is always merged back to the 
master branch (you can look at "gitk origin/maint origin/master" 
to see yourself).

So when Junio tags the release from the tip of the master branch, 
it is a superset of the maintenace branch; it is irrelevant if 
maint has some commits that are cherry-picked from master.

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

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

[Raman Gupta]

Nanako Shiraishi wrote:
> Quoting Raman Gupta <rocketraman@fastmail.fm>
>> I noticed you removed the discussion I added about the situation in
>> which maint will *not* be a subset of master i.e. when the user has
>> cherry-picked commits from other branches. This type of cherry-pick is
>> described as a valid operation, though one to generally be avoided
>> earlier in the man page. If we tell users that the occasional
>> cherry-pick to maint is ok, then shouldn't we explain how that affects
>> the release process?
> 
> It is irrelevant that you can cherry-pick to 'maint'.
> 
> You can, and Junio does, cherry-pick some commits from master to 
> maint from time to time. But even if you have such cherry-picked 
> commits on the maintenance branch, the result, with zero or more 
> other maintenance commits on top, is always merged back to the 
> master branch (you can look at "gitk origin/maint origin/master" 
> to see yourself).
> 
> So when Junio tags the release from the tip of the master branch, 
> it is a superset of the maintenace branch; it is irrelevant if 
> maint has some commits that are cherry-picked from master.

Thanks for the explanation. Makes sense.

Ok, another dumb question: since you have now submitted a patch on top
of my patch, what is the proper etiquette for proceeding? Who
maintains this patch series until it is committed? Since your patch
applies on top of mine I can't really make any more changes without
affecting your patch right? I can't find any guidance in the
SubmittingPatches document.

Cheers,
Raman

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

[Björn Gustavsson]

On Sat, Nov 14, 2009 at 6:35 AM, Raman Gupta <rocketraman@fastmail.fm> wrote:
>
> Ok, another dumb question: since you have now submitted a patch on top
> of my patch, what is the proper etiquette for proceeding? Who
> maintains this patch series until it is committed? Since your patch
> applies on top of mine I can't really make any more changes without
> affecting your patch right? I can't find any guidance in the
> SubmittingPatches document.

I can't answer the questions about proper etiquette, but you *can* do
more changes
if you first apply Nanako's patch on top of your previous changes.

/Björn
-- 
Björn Gustavsson, Erlang/OTP, Ericsson AB

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

[Nanako Shiraishi]

Quoting Raman Gupta <rocketraman@fastmail.fm>

> Ok, another dumb question: since you have now submitted a patch on top
> of my patch, what is the proper etiquette for proceeding? Who
> maintains this patch series until it is committed? Since your patch
> applies on top of mine I can't really make any more changes without
> affecting your patch right? I can't find any guidance in the
> SubmittingPatches document.

What usually happens is that we wait now.

In this case we are in agreement that it is a good idea to apply 
both of our patches (mine was only repeating what Junio said in 
his comments), so if I were you, I would anticipate that Junio 
would apply both of them and start preparing incremental updates 
on top of them now, and send them when the patches appear in his 
'pu' branch.

Junio has gone quiet for the past few days; maybe he is too busy
to read or respond to either of our patch. Instead of preparing 
the final text you write in the document in a patch format, it 
may be a better to bring up your ideas here and discuss them 
first. What changes do you have in mind? I think the new section 
now already is in a reasonable shape.

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

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

[Raman Gupta]

Nanako Shiraishi wrote:
> Quoting Raman Gupta <rocketraman@fastmail.fm>
> 
>> Ok, another dumb question: since you have now submitted a patch on top
>> of my patch, what is the proper etiquette for proceeding? Who
>> maintains this patch series until it is committed? Since your patch
>> applies on top of mine I can't really make any more changes without
>> affecting your patch right? I can't find any guidance in the
>> SubmittingPatches document.
> 
> What usually happens is that we wait now.
> 
> In this case we are in agreement that it is a good idea to apply 
> both of our patches (mine was only repeating what Junio said in 
> his comments), so if I were you, I would anticipate that Junio 
> would apply both of them and start preparing incremental updates 
> on top of them now, and send them when the patches appear in his 
> 'pu' branch.
> 
> Junio has gone quiet for the past few days; maybe he is too busy
> to read or respond to either of our patch. Instead of preparing 
> the final text you write in the document in a patch format, it 
> may be a better to bring up your ideas here and discuss them 
> first. What changes do you have in mind? I think the new section 
> now already is in a reasonable shape.

No specific changes -- it was a hypothetical question...

Cheers,
Raman

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

[Junio C Hamano]

Nanako Shiraishi <nanako3@lavabit.com> writes:

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

Your changes look mostly fine.

I obviously agree with the removal of "use 'branch -f' to update maint"
which I said I do not want to see in the document number of times.

There is another thing; I didn't notice it in the earlier round but the
way I actually rotate 'master', 'maint' and the 'maint-one-rev-old' is
similar to how Thomas mentioned.  That is:

================================
git checkout master
git log ..maint        ;# should see nothing
git tag ...            ;# release task
git checkout maint
git branch maint-X.Y.Z ;# without -f so that I can catch a typo to
                          clobber what already exists
git merge --ff-only master
================================

My fingers are trained to type "git merge" before --ff-only was invented,
so I actually do use "merge master" without --ff-only option in the last
step, but if I see a real merge created with that command, I notice it and
treat it as a grave error, so in the Recipe we should say --ff-only.

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

[Thomas Rast]

Nanako Shiraishi wrote:
> Quoting rocketraman@fastmail.fm
> > Add a basic introduction to the branch management undertaken during a
> > git.git release
[...]
> Here are some corrections that can be applied on top of your change.

At the bottom there are some more corrections on top of your combined
patches.  At this point I would prefer to squash everything into a
single patch, but if you want to keep them separate I can come up with
a commit message.

All but the last change are just intended to "sound nicer".  Since I'm
not a native speaker either (I'm not sure any have commented in the
threads so far), it would probably be nice to get some additional
comments.

As for the last hunk, I felt it was misleading to state 'pu' uses the
same process as 'next' immediately after mentioning the "next will be
rewound shortly" messages that Junio sends out.  Such a message is
never required for 'pu' because (as is already explained in the
manpage) the "contract" is that the maintainer may rewind it anytime
he likes.

Apart from that, I'm not entirely happy with the way the "release" and
"maint, after a feature release" sections are tangled yet.  There are
several forward and backward references between them.  I see that you
are trying to drive home the point that maint needs to be contained in
master.  Can't we just deal with that in the "feature release"
section?

-- 8< --
diff --git i/Documentation/gitworkflows.txt w/Documentation/gitworkflows.txt
index 2a9329f..490346c 100644
--- i/Documentation/gitworkflows.txt
+++ w/Documentation/gitworkflows.txt
@@ -225,8 +225,8 @@ should first make sure that condition holds.
 git log master..maint
 =====================================
 
-There should be no commit listed from this command (otherwise, check
-out 'master' and merge 'maint' into it).
+This command should not list any commits.  Otherwise, check out
+'master' and merge 'maint' into it.
 
 Then you can tag the tip of
 'master' with a tag indicating the release version.
@@ -241,15 +241,15 @@ Similarly, for a maintenance release, 'maint' is tracking the commits
 to be released. Therefore, simply replace 'master' above with
 'maint'.
 
-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
+You need to push the new tag to a public git server
+when you push the updated 'master' (or 'maint',
+if you are making a maintenance release).  See
+"DISTRIBUTED WORKFLOWS" below. This 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
 release tarballs and preformatted documentation pages.  You may want
-to wait this push-out before you update your 'maint' branch (see the
-next section).
+to defer the push until after you have updated your 'maint' branch
+(see the next section).
 
 
 Maintenance branch management after a feature release
@@ -319,8 +319,6 @@ so.
 If you do this, then you should make a public announcement indicating
 that 'next' was rewound and rebuilt.
 
-The same process may be followed for 'pu'.
-
 
 DISTRIBUTED WORKFLOWS
 ---------------------

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

[Raman Gupta]

Thomas Rast wrote:
> Nanako Shiraishi wrote:
>> Quoting rocketraman@fastmail.fm
>>> Add a basic introduction to the branch management undertaken during a
>>> git.git release
> [...]
>> Here are some corrections that can be applied on top of your change.

Ok. I am submitting another patch on top of yours and Nanako's with some additional explanation and guidance, as well as some rewording and reorganization. I also corrected an error that skillzero caught earlier.

I think the basics of Junio's message re rotating 'master', 'maint', and 'maint-one-rev-old' are already in the document, so I haven't added anything explicit regarding that.

> At the bottom there are some more corrections on top of your combined
> patches.  At this point I would prefer to squash everything into a
> single patch, but if you want to keep them separate I can come up with
> a commit message.

Squashing is fine with me.

> All but the last change are just intended to "sound nicer".  Since I'm
> not a native speaker either (I'm not sure any have commented in the
> threads so far), it would probably be nice to get some additional
> comments.

I *am* a native English speaker. Sadly, its the *only* language I speak, read, and write. However, additional comments would definitely be nice.

> As for the last hunk, I felt it was misleading to state 'pu' uses the
> same process as 'next' immediately after mentioning the "next will be
> rewound shortly" messages that Junio sends out.  Such a message is
> never required for 'pu' because (as is already explained in the
> manpage) the "contract" is that the maintainer may rewind it anytime
> he likes.

I added it back in with the additional explanation that the public announcement is not necessary. I think its important for a reader to understand how the 'pu' branch might be maintained. Besides, the title of the section includes pu, so some discussion around pu is warranted, or the title should change also.

> Apart from that, I'm not entirely happy with the way the "release" and
> "maint, after a feature release" sections are tangled yet.  There are
> several forward and backward references between them.  I see that you
> are trying to drive home the point that maint needs to be contained in
> master.  Can't we just deal with that in the "feature release"
> section?

Agree. I reworded the sections to untangle the information somewhat. Let me know what you think.

-- 8< --
diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 490346c..91c0eea 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -216,10 +216,17 @@ 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.
 
-Since 'master' is supposed to be always a superset of 'maint', you
-should first make sure that condition holds.
+A feature release is created from the 'master' branch, since 'master'
+tracks the commits that should go into the next feature release.
 
-.Make sure 'maint' fast-forwards to 'master'
+The 'master' branch is supposed to be a superset of 'maint'. If this
+condition does not hold, then 'maint' contains some commits that
+are not included on 'master'. The fixes represented by those commits
+will therefore not be included in your feature release.
+
+To verify that 'master' is indeed a superset of 'maint', use git log:
+
+.Verify 'master' is a superset of 'maint'
 [caption="Recipe: "]
 =====================================
 git log master..maint
@@ -228,8 +235,8 @@ git log master..maint
 This command should not list any commits.  Otherwise, check out
 'master' and merge 'maint' into it.
 
-Then you can tag the tip of
-'master' with a tag indicating the release version.
+Now you can proceed with the creation of the feature release. Apply a
+tag to the tip of 'master' indicating the release version:
 
 .Release tagging
 [caption="Recipe: "]
@@ -237,19 +244,15 @@ Then you can tag the tip of
 `git tag -s -m "GIT X.Y.Z" vX.Y.Z master`
 =====================================
 
-Similarly, for a maintenance release, 'maint' is tracking the commits
-to be released. Therefore, simply replace 'master' above with
-'maint'.
-
-You need to push the new tag to a public git server
-when you push the updated 'master' (or 'maint',
-if you are making a maintenance release).  See
-"DISTRIBUTED WORKFLOWS" below. This makes the tag available to
+You need to push the new tag to a public git server (see
+"DISTRIBUTED WORKFLOWS" below). This 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
-release tarballs and preformatted documentation pages.  You may want
-to defer the push until after you have updated your 'maint' branch
-(see the next section).
+release tarballs and preformatted documentation pages.
+
+Similarly, for a maintenance release, 'maint' is tracking the commits
+to be released. Therefore, in the steps above simply tag and push
+'maint' rather than 'master'.
 
 
 Maintenance branch management after a feature release
@@ -281,13 +284,10 @@ code so that maintenance fixes can be tracked for the current release:
 * `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
-'master', which means that the recent feature release could be missing
-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.
+If the merge fails because it is not a fast-forward, then it is
+possible some fixes on 'maint' were missed in the feature release.
+This will not happen if the content of the branches was verified as
+described in the previous section.
 
 
 Branch management for next and pu after a feature release
@@ -297,7 +297,7 @@ 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
+.Rewind and rebuild next
 [caption="Recipe: "]
 =====================================
 * `git checkout next`
@@ -319,6 +319,10 @@ so.
 If you do this, then you should make a public announcement indicating
 that 'next' was rewound and rebuilt.
 
+The same rewind and rebuild process may be followed for 'pu'. A public
+announcement is not necessary since 'pu' is a throw-away branch, as
+described above.
+
 
 DISTRIBUTED WORKFLOWS
 ---------------------
-- 
1.6.2

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

[Thomas Rast]

Raman Gupta wrote:
> 
> I *am* a native English speaker. Sadly, its the *only* language I
> speak, read, and write. However, additional comments would
> definitely be nice.

Oh, my apologies.  I just looked at the names and jumped to
conclusions from there.

> Agree. I reworded the sections to untangle the information
> somewhat. Let me know what you think.
[...]
>  * `git merge --ff-only master`
>  =====================================
>  
[...]
> +If the merge fails because it is not a fast-forward, then it is
> +possible some fixes on 'maint' were missed in the feature release.
> +This will not happen if the content of the branches was verified as
> +described in the previous section.

Yes, I think that is nicer.  It's no longer a repetition of what was
said above, but merely points out what could have gone wrong and where
to look for advice.  The last sentence sounds a bit like "ha ha we
told you so!" though ;-)

FWIW, you can add my

  Acked-by: Thomas Rast <trast@student.ethz.ch>

to the final (squashed) patch.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

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

[Nanako Shiraishi]

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

> FWIW, you can add my
>
>   Acked-by: Thomas Rast <trast@student.ethz.ch>
>
> to the final (squashed) patch.

Junio, please also add my

   Acked-by: Nanako Shiraishi <nanako3@lavabit.com>

My changes were intended to be squashed into the final single patch, too.

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