Update gitworkflows man page to include release workflow

Update gitworkflows man page to include release workflow

[rocketraman]

Resubmission of patch to include a basic discussion of the release process on the gitworkflows man page. The original submission and resulting discussion can be found here:

http://thread.gmane.org/gmane.comp.version-control.git/114704/focus=114703
http://thread.gmane.org/gmane.comp.version-control.git/115079/focus=115080

Sorry for the delay in resubmitting.

Cheers,
Raman

[PATCHv2] Update gitworkflows man page to include release workflow

[rocketraman]

From: Raman Gupta <raman@rocketraman.com>

The gitworkflows man page currently provides an overview of the workflows
used by git.git itself to serve as inspiration for people to use when
designing their own workflows. The current man page does a reasonable
job at describing the development process, but it does not contain any
guidance as to the workflow used for releases. Now add a basic
introduction to the branch management required for a release, so that a
reader may understand how the maint, master, next, and topic branches are
affected.
---
 Documentation/gitworkflows.txt |   97 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 97 insertions(+), 0 deletions(-)

diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 2b021e3..69b789a 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -348,6 +348,103 @@ in patches to figure out the merge base.  See linkgit:git-am[1] for
 other options.
 
 
+RELEASE WORKFLOW
+----------------
+
+The maintainer may use the following release workflow:
+
+He first tags the tip of 'master' with a release tag, then he updates
+the 'maint' branch to the current tip of 'master' for managing future
+maintenance fixes on the current release, and lastly he optionally
+rebuilds 'next' from the tip of 'master'.
+
+
+Release Tagging
+~~~~~~~~~~~~~~~
+
+The new feature release is tagged on 'master' with a tag matching
+vX.Y.Z, where X.Y.Z is the new feature release version.
+
+.Release tagging
+[caption="Recipe: "]
+=====================================
+`git tag -s -m "GIT X.Y.Z" vX.Y.Z master`
+=====================================
+
+
+Maintenance branch update
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Maintenance fixes for the current feature release are tracked on the
+'maint' branch.
+
+
+In order to track maintenance
+fixes to the current release, the maintainer uses a branch called
+'maint'.
+
+
+The current maintenance branch is optionally copied to another branch
+named with the older release version number (e.g. maint-X.Y.(Z-1)
+where X.Y.Z is the previous release). This allows for further
+maintenance releases on the older codebase.
+
+If the current tip of 'maint' corresponds to the previous release
+tag (i.e. that there are no fixes already pending on 'maint' that are
+intended for a maintenance release on the older codebase), then
+creating the 'maint' branch for the older codebase can also be done
+later, if it is needed.
+
+.Copy maint
+[caption="Recipe: "]
+=====================================
+`git branch maint-X.Y.(Z-1) maint`
+=====================================
+
+'maint' should now updated to the new release code so that maintenance
+fixes can be merged for the current version:
+
+.Update maint to new release
+[caption="Recipe: "]
+=====================================
+* `git checkout maint`
+* `git merge master`
+=====================================
+
+This updates 'maint' from 'master', while preserving the 'maint'
+reflog.
+
+An alternative approach to updating the 'maint' branch is to run
+
+  $ git branch -f maint master
+
+This will create a new 'maint' branch based on 'master'. If 'maint'
+already exists, it will be deleted before the new branch is created.
+Any commits on 'maint' that were not previously merged to master will
+therefore be lost and the 'maint' reflog will be reset. However, the
+branch history is "clean" and may be easier to understand.
+
+
+Update next branch
+~~~~~~~~~~~~~~~~~~
+
+The 'next' branch may be rewound and rebuilt from the tip of 'master'
+using the surviving topics on 'next'.
+
+This step is optional. If it is done by the maintainer, then a public
+announcement will be made indicating that 'next' was rewound and
+rebuilt.
+
+.Update maint to new release
+[caption="Recipe: "]
+=====================================
+* `git branch -f next master`
+* `git merge ai/topic_in_next1`
+* `git merge ai/topic_in_next2`
+* ...
+=====================================
+
+
 SEE ALSO
 --------
 linkgit:gittutorial[7],
-- 
1.6.2

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Štěpán Němec]

On Tue, Nov 10, 2009 at 11:08:59AM -0500, rocketraman@fastmail.fm wrote:

A small typo:

> +'maint' should now updated to the new release code so that maintenance
> +fixes can be merged for the current version:

There is a missing `be' somewhere, something like: "'maint' should now be
updated..."

Regards,

Štěpán

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Raman Gupta]

Štěpán Němec wrote:
> On Tue, Nov 10, 2009 at 11:08:59AM -0500, rocketraman@fastmail.fm wrote:
> 
> A small typo:
> 
>> +'maint' should now updated to the new release code so that maintenance
>> +fixes can be merged for the current version:
> 
> There is a missing `be' somewhere, something like: "'maint' should now be
> updated..."

Oops, thanks, good catch.

Cheers,
Raman

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Thiago Farina]

Hi,

On Tue, Nov 10, 2009 at 2:08 PM,  <rocketraman@fastmail.fm> wrote:
> From: Raman Gupta <raman@rocketraman.com>
>
> The gitworkflows man page currently provides an overview of the workflows
> used by git.git itself to serve as inspiration for people to use when
> designing their own workflows. The current man page does a reasonable
> job at describing the development process, but it does not contain any
> guidance as to the workflow used for releases. Now add a basic
> introduction to the branch management required for a release, so that a
> reader may understand how the maint, master, next, and topic branches are
> affected.
Here
http://git.kernel.org/?p=git/git.git;a=blob;f=Checklist.txt;h=37745f39487537117fb7f3a9a6f5b8e7d989a884;hb=refs/heads/todo
there is a release checklist, maybe you could extend your patch to
include more information from this?

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Raman Gupta]

Thiago Farina wrote:
> Hi,
> 
> On Tue, Nov 10, 2009 at 2:08 PM,  <rocketraman@fastmail.fm> wrote:
>> From: Raman Gupta <raman@rocketraman.com>
>>
>> The gitworkflows man page currently provides an overview of the workflows
>> used by git.git itself to serve as inspiration for people to use when
>> designing their own workflows. The current man page does a reasonable
>> job at describing the development process, but it does not contain any
>> guidance as to the workflow used for releases. Now add a basic
>> introduction to the branch management required for a release, so that a
>> reader may understand how the maint, master, next, and topic branches are
>> affected.
> Here
> http://git.kernel.org/?p=git/git.git;a=blob;f=Checklist.txt;h=37745f39487537117fb7f3a9a6f5b8e7d989a884;hb=refs/heads/todo
> there is a release checklist, maybe you could extend your patch to
> include more information from this?

Most of the checklist is specific to the git infrastructure rather
than git branch management. The latter is the focus of the
gitworkflows man page. The relevant items from checklist.txt (e.g.
merge 'maint' to 'master') are already included in the patch.

Cheers,
Raman

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Junio C Hamano]

rocketraman@fastmail.fm writes:

> From: Raman Gupta <raman@rocketraman.com>
>
> The gitworkflows man page currently provides an overview of the workflows
> used by git.git itself to serve as inspiration for people to use when
> designing their own workflows. The current man page does a reasonable
> job at describing the development process, but it does not contain any
> guidance as to the workflow used for releases. Now add a basic
> introduction to the branch management required for a release, so that a
> reader may understand how the maint, master, next, and topic branches are
> affected.
> ---

Is this meant to show how git.git does its release to serve as an
inspiration to others?  The document does not seem to describe how I make
releases.

> diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
> index 2b021e3..69b789a 100644
> --- a/Documentation/gitworkflows.txt
> +++ b/Documentation/gitworkflows.txt
> @@ -348,6 +348,103 @@ in patches to figure out the merge base.  See linkgit:git-am[1] for
>  other options.
>  
>  
> +RELEASE WORKFLOW
> +----------------
> +
> +The maintainer may use the following release workflow:

Please set the tone straight.  If this is to suggest various possible
workflows in general vague terms, "may use" would be good.  If this is to
precisely describe what I do, then there won't be "you could do this, or
you could do that."  Your "may use" suggests the former, but the commit
log message claims the latter.  Which document are you writing?

Assuming that you are writing what I do...

> +He first tags the tip of 'master' with a release tag, then he updates
> +the 'maint' branch to the current tip of 'master' for managing future
> +maintenance fixes on the current release, and lastly he optionally
> +rebuilds 'next' from the tip of 'master'.

Not in that order.

	- doubly make sure that there is nothing left in 'maint' that
	  is not in 'master';
	- review 'master' more thoroughly than usual;
	- review RelNotes symlink, Documentation/RelNotes-X.Y.Z.txt,
          the stalenotes section in Documentation/git.git, and
          GIT-VERSION-GEN for the last time;
        - tag it;
        - review it again for the last time;
	- test on buildfarm;
	- cut tarball;
        - cut RPM on FC11 i386 and FC11 x86_64;
        - push the tag and master branch alone to the public server---this
          triggers an autobuilder for documentation pages, updates man and
          html branches and documentation tarballs;

When making a maintenance release, everything is the same except that
'maint' is used instead of 'master'.

Then, after all the release task on 'master' (or 'maint') is done,
propagate that upwards (i.e. merge 'master' to 'next' and 'pu').

Merging 'master' to 'maint' is done totally as a separate step, often a
few days later, "Now the big release is done, let's start maintenance
track for that relase".

And then after that, 'next' may be rebuilt.

> +Release Tagging
> +~~~~~~~~~~~~~~~
> +
> +The new feature release is tagged on 'master' with a tag matching
> +vX.Y.Z, where X.Y.Z is the new feature release version.
> +
> +.Release tagging
> +[caption="Recipe: "]
> +=====================================
> +`git tag -s -m "GIT X.Y.Z" vX.Y.Z master`
> +=====================================

There is no incorrect information here, but I do not think there is
anything particularly worth saying here, either.  It is in "git tag"
manpage and anybody can run "git cat-file tag v1.6.3" to learn what is in
there.

> +Maintenance branch update
> +~~~~~~~~~~~~~~~~~~~~~~~~~

This section largely overlaps with Documentation/howto/maintain-git.txt; I
am starting to doubt if we even need a new section in the workflows
document.  Perhaps we could have a release management section in the
Documentation/howto/maintain-git.txt, though.

> +[caption="Recipe: "]
> +=====================================
> +* `git checkout maint`
> +* `git merge master`
> +=====================================
> +
> +This updates 'maint' from 'master', while preserving the 'maint'
> +reflog.
> +
> +An alternative approach to updating the 'maint' branch is to run
> +
> +  $ git branch -f maint master

As I already said, I never do this "alternative", and I do not want
anybody who will take over git.git maintenance to do so.  There is no
reason to encourage nor even mention "branch -f" here.  As 'maint' is
supposed to be a strict subset, pulling 'master' to 'maint' should fast
forward and otherwise you (the maintainer) would notice that there was a
mistake made.  If you use "branch -f", you will never notice.

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Raman Gupta]

Thanks for your review. Comments inline.

Junio C Hamano wrote:
> rocketraman@fastmail.fm writes:
> 
>> From: Raman Gupta <raman@rocketraman.com>
>>
>> The gitworkflows man page currently provides an overview of the workflows
>> used by git.git itself to serve as inspiration for people to use when
>> designing their own workflows. The current man page does a reasonable
>> job at describing the development process, but it does not contain any
>> guidance as to the workflow used for releases. Now add a basic
>> introduction to the branch management required for a release, so that a
>> reader may understand how the maint, master, next, and topic branches are
>> affected.
>> ---
> 
> Is this meant to show how git.git does its release to serve as an
> inspiration to others?  The document does not seem to describe how I make
> releases.

Here is the existing intro to gitworkflows:

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

We formulate a set of rules for quick reference, while the prose tries
to motivate each of them. Do not always take them literally; you
should value good reasons for your actions higher than manpages such
as this one.
===================

It is in this spirit that I am attempting to add to this document in
relation to the release process. If after you read through this email
you don't agree this patch has any value in gitworkflows, let me know
so that I can stop wasting my time and yours.

>> diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
>> index 2b021e3..69b789a 100644
>> --- a/Documentation/gitworkflows.txt
>> +++ b/Documentation/gitworkflows.txt
>> @@ -348,6 +348,103 @@ in patches to figure out the merge base.  See linkgit:git-am[1] for
>>  other options.
>>  
>>  
>> +RELEASE WORKFLOW
>> +----------------
>> +
>> +The maintainer may use the following release workflow:
> 
> Please set the tone straight.  If this is to suggest various possible
> workflows in general vague terms, "may use" would be good.  If this is to
> precisely describe what I do, then there won't be "you could do this, or
> you could do that."  Your "may use" suggests the former, but the commit
> log message claims the latter.  Which document are you writing?

Ok. The current document is inconsistent. In places it uses "the
maintainer" and in other places it uses "you". In any case, it seems
that the "maintainer" here is not "Junio Hamano" -- rather, it is the
reader.

Let me create a separate (and first) cleanup patch to fix the existing
inconsistencies in this man page. I would prefer to use the pronoun
"you" consistently as also suggested by Thomas Rast.

In addition, I will update the commit log message to be consistent.

>
> Assuming that you are writing what I do...
>
>> +He first tags the tip of 'master' with a release tag, then he updates
>> +the 'maint' branch to the current tip of 'master' for managing future
>> +maintenance fixes on the current release, and lastly he optionally
>> +rebuilds 'next' from the tip of 'master'.
> 
> Not in that order.

Ok, I'll work on the order.

> 	- doubly make sure that there is nothing left in 'maint' that
> 	  is not in 'master';
> 	- review 'master' more thoroughly than usual;

As per the intro to the man page, I think you will agree these items
are not required. They follow under the category of the user thinking
about what they are doing -- the man page is not meant to provide the
user with a "monkey-see, monkey-do" series of steps.

> 	- review RelNotes symlink, Documentation/RelNotes-X.Y.Z.txt,
>           the stalenotes section in Documentation/git.git, and
>           GIT-VERSION-GEN for the last time;
>         - tag it;
>         - review it again for the last time;
> 	- test on buildfarm;
> 	- cut tarball;
>         - cut RPM on FC11 i386 and FC11 x86_64;

I will update the commit log message to show that my intent was to
talk about how the git.git integration and topic branches are affected
by the release rather than providing a complete project release
process. General items like release notes, version files, reviews,
tests, and cutting distribution tarballs are not specific to git.git
nor git. For git.git, these items better belong in MaintNotes and the
release checklist.txt (as they do) rather than this user distributed
man page.

>         - push the tag and master branch alone to the public server---this
>           triggers an autobuilder for documentation pages, updates man and
>           html branches and documentation tarballs;

I think it makes sense to include some verbiage around the push
aspect, as it is part of the distributed nature of git. I'll add this.
The autobuilder is not git specific so should be excluded via the
logic above -- except perhaps the hook part, which I could mention in
general terms when discussing the push e.g.

"You may decide to use a hook script on the public repository to
initiate release-related items such as building documentation."

> When making a maintenance release, everything is the same except that
> 'maint' is used instead of 'master'.

Good point -- I will add a section about maintenance releases.

> Then, after all the release task on 'master' (or 'maint') is done,
> propagate that upwards (i.e. merge 'master' to 'next' and 'pu').

Will add this.

> Merging 'master' to 'maint' is done totally as a separate step, often a
> few days later, "Now the big release is done, let's start maintenance
> track for that relase".
> 
> And then after that, 'next' may be rebuilt.

Ok, I'll change the order/wording accordingly.

>> +Release Tagging
>> +~~~~~~~~~~~~~~~
>> +
>> +The new feature release is tagged on 'master' with a tag matching
>> +vX.Y.Z, where X.Y.Z is the new feature release version.
>> +
>> +.Release tagging
>> +[caption="Recipe: "]
>> +=====================================
>> +`git tag -s -m "GIT X.Y.Z" vX.Y.Z master`
>> +=====================================
> 
> There is no incorrect information here, but I do not think there is
> anything particularly worth saying here, either.  It is in "git tag"
> manpage and anybody can run "git cat-file tag v1.6.3" to learn what is in
> there.

The intention of this is not to illustrate the "git tag" syntax but
rather so that the user understands the tag description and naming
conventions used by git.git -- this prompts them mentally to consider
defining conventions for their project. Therefore, I'd like to keep this.

>> +Maintenance branch update
>> +~~~~~~~~~~~~~~~~~~~~~~~~~
> 
> This section largely overlaps with Documentation/howto/maintain-git.txt; I
> am starting to doubt if we even need a new section in the workflows
> document.  Perhaps we could have a release management section in the
> Documentation/howto/maintain-git.txt, though.

Based on my comments and changes above, do you still have this doubt?
 Remember that the audience of a man page is not the git team -- it is
users. A new user to git who is considering developing branch
processes and conventions around their git project will have access to
a man page such as gitworkflows but will not have (easy) access to
maintain-git.txt.

This is in fact why I decided to make this patch submission -- I found
gitworkflows to be very helpful in creating a layout for my git
projects, but found that gitworkflows was missing any guidance as to
what to do with my integration and topic branches when I needed to cut
a release. It was a while before I found maintain-git.txt, and most
users will never find it.

>> +[caption="Recipe: "]
>> +=====================================
>> +* `git checkout maint`
>> +* `git merge master`
>> +=====================================
>> +
>> +This updates 'maint' from 'master', while preserving the 'maint'
>> +reflog.
>> +
>> +An alternative approach to updating the 'maint' branch is to run
>> +
>> +  $ git branch -f maint master
> 
> As I already said, I never do this "alternative", and I do not want
> anybody who will take over git.git maintenance to do so.  There is no
> reason to encourage nor even mention "branch -f" here.  As 'maint' is
> supposed to be a strict subset, pulling 'master' to 'maint' should fast
> forward and otherwise you (the maintainer) would notice that there was a
> mistake made.  If you use "branch -f", you will never notice.

I know you do not do this alternative, however I added it as per our
previous discussion. I quote from
http://article.gmane.org/gmane.comp.version-control.git/115183:

>> I'll add some discussion about the branch -f bit -- I hope you agree
>> that in this document that is distributed with git, some
>> beginner-level explanation of the difference between the branch -f and
>> the merge approach is warranted?
> 
> Surely and thanks.

I will try to make the reason why "branch -f" is not a good option
more clear. I'd like to keep this because many newbies coming from VCs
like subversion will default to taking the "branch -f" approach
because that is conceptually closer to the way subversion works (I
know I did).

Thanks for your comments.

Cheers,
Raman

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Junio C Hamano]

Raman Gupta <rocketraman@fastmail.fm> writes:

> Junio C Hamano wrote:
>> 
>> Is this meant to show how git.git does its release to serve as an
>> inspiration to others?  The document does not seem to describe how I make
>> releases.
>
> Here is the existing intro to gitworkflows:
>
> ===================
> 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.
>
> We formulate a set of rules for quick reference, while the prose tries
> to motivate each of them. Do not always take them literally; you
> should value good reasons for your actions higher than manpages such
> as this one.
> ===================
>
> It is in this spirit that I am attempting to add to this document in
> relation to the release process.

Thanks for reminding me of this.

Let me address the second paragraph from the quoted part first.  The
existing document is structured as a quick reference.  Rules and recipes,
with supporting prose to explain them (I do not think "motivate" is a good
way to phrase it, though).

I am not very fond of documents with that style, but that does not mean
nobody should work on nor we should ship such a document.  It just means I
would not be a very good judge for one, and major parts of my response 
unfortunately came from my bias against such a document.

What the first paragraph says is also important.  We will talk about the
workflow elements we actually use here.  Every description of a workflow
element should be read as if we said "this is what we use and it has
worked well for us; we recommend you to imitate it." after it.  Limiting
the recommendation to what we practice ourselves and what worked well for
us keeps the document honest.

In that light, after I re-read your patch and my comments, I think I
should rescind large part of my comments on your "Release Tagging" section
and "Maintenance branch update" section.  They are mostly good as-is, and
they are in line with the goal of the document stated at the beginning.
They describe the workflow elements actually used in git.git in a
quick-reference format.

>>> +RELEASE WORKFLOW
>>> +----------------
>>> +
>>> +The maintainer may use the following release workflow:
>> 
>> Please set the tone straight.  If this is to suggest various possible
>> workflows in general vague terms, "may use" would be good. ...
>
> Ok. The current document is inconsistent. In places it uses "the
> maintainer" and in other places it uses "you". In any case, it seems
> that the "maintainer" here is not "Junio Hamano" -- rather, it is the
> reader.

I wasn't talking about the difference between these two (Junio vs you).
That is not the issue.  I was contrasting between

 - You _may_ choose to do A for release management as the maintainer, or
   do B or do C as alternatives.

and

 - In managing git.git, its maintainer _does_ A when making a release.

As we are writing down what we practice, aka "workflow elements used for
git.git itself", in my comment I was hoping the latter was what you were
writing.  Of course we could say

 - In managing git.git, its maintainer _does_ A when making a release.
   It is conceivable we _could_ also do B or C instead, but we do not
   recommend them.

but I think we are better off without such an addition.

An anti-recommendation against B and C like that does not carry the same
weight as our positive recommendation for A, which is backed by our actual
experience.

"In the past, we tried B but it did not work well for us for such and such
reasons, so we don't recommend you to use B" would be justifiable, and
that is what I mean by "keeping the document honest by limiting the
description to what we use".

But if this document is meant to be a quick reference, such
anti-recommendation should be kept to minimum for the sake of
"quick"-ness.

Also I agree with you that ...

>> 	- review RelNotes symlink, Documentation/RelNotes-X.Y.Z.txt,
>>           the stalenotes section in Documentation/git.git, and
>>           GIT-VERSION-GEN for the last time;
>>         - tag it;
>>         - review it again for the last time;
>> 	- test on buildfarm;
>> 	- cut tarball;
>>         - cut RPM on FC11 i386 and FC11 x86_64;

these (except "tag it") can safely omitted to keep the document focused on
"revision control" aspect of the system.

> The autobuilder is not git specific so should be excluded via the logic
> above -- except perhaps the hook part, which I could mention in general
> terms when discussing the push e.g.
>
> "You may decide to use a hook script on the public repository to
> initiate release-related items such as building documentation."

Again, if we are going to recommend it, we should say "We use post-update
hook in _this_ way", not "You may do ...".

A major difference is that we describe what has worked for us and exactly
how, as opposed to giving suggestions that we ourselves haven't even used
but suspect it might work in a hand-wavy way.

>>> +Maintenance branch update
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~
>> ...
>>> +An alternative approach to updating the 'maint' branch is to run
>>> +
>>> +  $ git branch -f maint master
>> 
>> As I already said, I never do this "alternative", and I do not want
>> ...
>> mistake made.  If you use "branch -f", you will never notice.
>
> I know you do not do this alternative, however ...

Given the stated goal of the document of showing what we actually do and
what we know have worked well for us, I do not think we would want it
mentioned as a valid alternative.

> previous discussion. I quote from
> http://article.gmane.org/gmane.comp.version-control.git/115183:
>
>>> I'll add some discussion about the branch -f bit -- I hope you agree
>>> that in this document that is distributed with git, some
>>> beginner-level explanation of the difference between the branch -f and
>>> the merge approach is warranted?

Explanation of the difference would have sounded like:

    We do not use "branch -f maint master" here; it is different from
    merging master into maint in such and such way and using "branch -f"
    for this purpose only has downsides.

But is it really worth mentioning random approaches that novices might
think of as alternatives and then refuting every one of them?  Should we
also say "don't do 'checkout maint && reset --hard master'"?  Should we
say "'push . master:maint' would work equally well but don't add --force
to that command line"?

The document is an overview of recommended workflows.  If we have one best
current practice for a task, just describing it without covering other
inferiour (or equivalent but not superiour) alternatives to clutter the
text would be better for such a "quick reference" document, I think.

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Thomas Rast]

Raman Gupta wrote:
> Junio C Hamano wrote:
> > Please set the tone straight.  If this is to suggest various possible
> > workflows in general vague terms, "may use" would be good.  If this is to
> > precisely describe what I do, then there won't be "you could do this, or
> > you could do that."  Your "may use" suggests the former, but the commit
> > log message claims the latter.  Which document are you writing?
> 
> Ok. The current document is inconsistent. In places it uses "the
> maintainer" and in other places it uses "you". In any case, it seems
> that the "maintainer" here is not "Junio Hamano" -- rather, it is the
> reader.
> 
> Let me create a separate (and first) cleanup patch to fix the existing
> inconsistencies in this man page. I would prefer to use the pronoun
> "you" consistently as also suggested by Thomas Rast.

Well, I'm not sure if this is also in reply to my comment

} The current gitworkflows is mostly formulated in the imperative, [...]
} or by directly describing the tools in the third person, [...]

but note that I do not consider the current form to be inconsistent
(though you may of course convince me otherwise).  It addresses the
presumed user with "you", which is not always the maintainer.  For
example, when talking about patch submission we have

  If the maintainer tells you that your patch no longer applies to the
  current upstream, you will have to rebase your topic (you cannot use a
  merge because you cannot format-patch merges):

since the presumed user of a patch-submission workflow is a
contributor, not the maintainer.  Indeed much of the text talks
*about* the workflow used by our esteemed maintainer, but is addressed
to a contributor who wants to understand how it works so he can
participate.

IOW, I'm neither a native speaker nor a professional writer, so you
may of course convince me that there is something to fix.  I am,
however, fairly sure that s/maintainer/you/ and then fixing the
grammar is *not* a good thing.

[BTW, it would have been nice to get a Cc to begin with, since the
entire manpage blames to me.  I noticed the thread anyway, but other
times I do not have the time to scan the entire list.]

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

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Raman Gupta]

Thomas Rast wrote:
> Raman Gupta wrote:
>> Junio C Hamano wrote:
>>> Please set the tone straight.  If this is to suggest various possible
>>> workflows in general vague terms, "may use" would be good.  If this is to
>>> precisely describe what I do, then there won't be "you could do this, or
>>> you could do that."  Your "may use" suggests the former, but the commit
>>> log message claims the latter.  Which document are you writing?
>> Ok. The current document is inconsistent. In places it uses "the
>> maintainer" and in other places it uses "you". In any case, it seems
>> that the "maintainer" here is not "Junio Hamano" -- rather, it is the
>> reader.
>>
>> Let me create a separate (and first) cleanup patch to fix the existing
>> inconsistencies in this man page. I would prefer to use the pronoun
>> "you" consistently as also suggested by Thomas Rast.
> 
> Well, I'm not sure if this is also in reply to my comment

It was mostly, yes.

> } The current gitworkflows is mostly formulated in the imperative, [...]
> } or by directly describing the tools in the third person, [...]
> 
> but note that I do not consider the current form to be inconsistent
> (though you may of course convince me otherwise).  It addresses the
> presumed user with "you", which is not always the maintainer.  For
> example, when talking about patch submission we have

You're right, upon re-reading the original man page I realized it is
consistent.

Thanks,
Raman

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Thomas Rast]

It's nice to see someone work on this manpage :-) I sadly do not have
the time to read the whole patch right now, though I'll try and catch
up tomorrow or so.  In the meantime I do have one remark:

rocketraman@fastmail.fm wrote:
> +The maintainer may use the following release workflow:
> +
> +He first tags the tip of 'master' with a release tag, then he updates
> +the 'maint' branch to the current tip of 'master' for managing future
> +maintenance fixes on the current release, and lastly he optionally
> +rebuilds 'next' from the tip of 'master'.

The current gitworkflows is mostly formulated in the imperative, as in

  To test the interaction of several topics, merge them into a
  throw-away branch.  You must never base any work on such a branch!

or by directly describing the tools in the third person, as in

  * linkgit:git-push[1] copies your branches to a remote repository,
    usually to one that can be read by all involved parties;

It would certainly be nice to be somewhat consistent.  Since at first
glance your description is aimed at the maintainer himself, I assume
that would mostly mean addressing the maintainer as "you", and
formulating the rules in the imperative.

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

Re: [PATCHv2] Update gitworkflows man page to include release workflow

[Thomas Rast]

Here's my promised review of the whole patch.  Much of the text fits
my understanding of what's actually going on, but Junio will have the
final word on what he actually does (or what a sensible simplification
might be).

rocketraman@fastmail.fm wrote:
> +The current maintenance branch is optionally copied to another branch
> +named with the older release version number (e.g. maint-X.Y.(Z-1)
> +where X.Y.Z is the previous release). This allows for further
> +maintenance releases on the older codebase.

The use of Z-1 confused me; I guess by "previous release" you mean
"the release we just tagged in the last step".  Otherwise the maint
version number would come out wrong.

> +.Update maint to new release
> +[caption="Recipe: "]
> +=====================================
> +* `git checkout maint`
> +* `git merge master`
> +=====================================
> +
> +This updates 'maint' from 'master', while preserving the 'maint'
> +reflog.

I agree with what Junio said in the other mail: it's important at this
point that this was a fast-forward.  (If it's not, master could be
missing some fixes made on maint.)

> +An alternative approach to updating the 'maint' branch is to run
> +
> +  $ git branch -f maint master

In my book the alternative approach is

  git branch -m maint maint-X.Y.(Z-1)
  git branch maint master

I'd rather not teach users to play with loaded guns, much less in a
"good examples of workflows" manpage.

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