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

[Thomas Rast <trast@student.ethz.ch>]

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