[PATCH 1/2] Add feature release instructions to MaintNotes addendum

[PATCH 1/2] Add feature release instructions to MaintNotes addendum

[rocketraman]

From: Raman Gupta <raman@rocketraman.com>

Based on a mailing list discussion, add the operations for creating a
feature release.

Signed-off-by: Raman Gupta <raman@rocketraman.com>
---
 Documentation/howto/maintain-git.txt |   29 +++++++++++++++++++++++++++++
 1 files changed, 29 insertions(+), 0 deletions(-)

diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index 4357e26..f6ee0c5 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt
@@ -244,6 +244,35 @@ by doing the following:
    repo.or.cz
 
 
+A feature release of git is made by tagging 'master' with a tag
+matching vX.Y.Z, where X.Y.Z is the feature release version.
+
+ - Optionally, track the current 'maint' branch to support
+   new releases for the older codebase if necessary.
+
+     $ git branch maint-X.Y.(Z-1) maint
+
+ - The 'maint' branch is updated to the new release.
+
+     $ git checkout maint
+     $ git merge master
+
+   This is equivalent to deleting maint and recreating it from
+   master, but it preserves the maint reflog.
+
+ - The 'next' branch may be rebuilt from the tip of 'master'
+   using the surviving topics on 'next'.
+
+     $ git branch -f next master
+
+   (Again, this approach preserves the reflog and per-branch
+   configuration of 'next')
+
+     $ git merge ai/topic_in_next1
+     $ git merge ai/topic_in_next2
+     ...
+
+
 Some observations to be made.
 
  * Each topic is tested individually, and also together with
-- 
1.6.2

[PATCH 2/2] Add feature release instructions to gitworkflows man page

[rocketraman]

From: Raman Gupta <raman@rocketraman.com>

Based on a mailing list discussion, add a description of the workflow,
and associated commands, for creating a feature release.

Signed-off-by: Raman Gupta <raman@rocketraman.com>
---
 Documentation/gitworkflows.txt |   69 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 69 insertions(+), 0 deletions(-)

diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 2b021e3..1796878 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -348,6 +348,75 @@ 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 "vX.Y.Z" vX.Y.Z`
+==========================================
+
+
+Maintenance branch update
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The current maintenance branch is optionally tracked with the older
+release version number to allow for further maintenance releases on
+the older codebase.
+
+.Track maint
+[caption="Recipe: "]
+=====================================
+`git branch maint-X.Y.(Z-1) maint`
+=====================================
+
+'maint' is 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 is equivalent to deleting maint and recreating it from master,
+but it preserves the maint reflog.
+
+Update next branch
+~~~~~~~~~~~~~~~~~~
+
+The 'next' branch may be 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 rebased.
+
+.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: [PATCH 2/2] Add feature release instructions to gitworkflows man page

[Junio C Hamano]

rocketraman@fastmail.fm writes:

> +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 "vX.Y.Z" vX.Y.Z`
> +==========================================

I actually always do:

	git tag -s -m "GIT X.Y.Z" vX.Y.Z master

The argument to -m in your descriptoin is incorrectly quoted, and has an
extra v.  I also spell out 'master' to avoid mistakes, and I would be
happy to encourage others to follow it.

> +Maintenance branch update
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The current maintenance branch is optionally tracked with the older
> +release version number to allow for further maintenance releases on
> +the older codebase.
> +
> +.Track maint
> +[caption="Recipe: "]
> +=====================================
> +`git branch maint-X.Y.(Z-1) maint`
> +=====================================

This creates maint-X.Y.(Z-1) from maint, but calling this step "track
maint" entirely misses the point.

When people use the word "track", the intention is that they intend to
merge subsequent changes to the original branch (in this case, 'maint') to
the new branch ('maint-X.Y.(Z-1)') from time to time.

That is exactly opposite to what I create maint-X.Y.(Z-1) branch for.
This new "branch to maintain an older codebase" will *never* merge from
'maint' after it forks.

> +Update next branch
> +~~~~~~~~~~~~~~~~~~
> +
> +The 'next' branch may be 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 rebased.

The wording I use is more like 'rewound and rebuilt'.

Re: [PATCH 1/2] Add feature release instructions to MaintNotes addendum

[Raman Gupta]

Nanako Shiraishi wrote:
> Quoting rocketraman@fastmail.fm:
> 
>> + - The 'maint' branch is updated to the new release.
>> +
>> +     $ git checkout maint
>> +     $ git merge master
>> +
>> +   This is equivalent to deleting maint and recreating it from
>> +   master, but it preserves the maint reflog.
> 
> After giving a recipe that is better than an alternative, what's
> the point of describing an inferior alternative as "equivalent",
> when it is obviously not "equivalent"?

Is this better:

The resulting maint tree is equivalent to deleting maint and
recreating it from the tip of master, but merging from master
preserves the maint reflog.

Cheers,
Raman

Re: [PATCH 2/2] Add feature release instructions to gitworkflows man page

[Raman Gupta]

Junio C Hamano wrote:
> rocketraman@fastmail.fm writes:
> 
>> +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 "vX.Y.Z" vX.Y.Z`
>> +==========================================
> 
> I actually always do:
> 
> 	git tag -s -m "GIT X.Y.Z" vX.Y.Z master
> 
> The argument to -m in your descriptoin is incorrectly quoted, and has an
> extra v.  I also spell out 'master' to avoid mistakes, and I would be
> happy to encourage others to follow it.

Fixed.

>> +Maintenance branch update
>> +~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +The current maintenance branch is optionally tracked with the older
>> +release version number to allow for further maintenance releases on
>> +the older codebase.
>> +
>> +.Track maint
>> +[caption="Recipe: "]
>> +=====================================
>> +`git branch maint-X.Y.(Z-1) maint`
>> +=====================================
> 
> This creates maint-X.Y.(Z-1) from maint, but calling this step "track
> maint" entirely misses the point.
> 
> When people use the word "track", the intention is that they intend to
> merge subsequent changes to the original branch (in this case, 'maint') to
> the new branch ('maint-X.Y.(Z-1)') from time to time.
> 
> That is exactly opposite to what I create maint-X.Y.(Z-1) branch for.
> This new "branch to maintain an older codebase" will *never* merge from
> 'maint' after it forks.

Yeah, I originally had written "Copy maint" but copy seemed to be more
subversion-speak rather than git-speak so I changed it. However it
does seem to accurately describe the operation. Would "Copy maint" be
acceptable terminology?

>> +Update next branch
>> +~~~~~~~~~~~~~~~~~~
>> +
>> +The 'next' branch may be 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 rebased.
> 
> The wording I use is more like 'rewound and rebuilt'.

Fixed.

Cheers,
Raman

Re: [PATCH 1/2] Add feature release instructions to MaintNotes addendum

[Junio C Hamano]

Raman Gupta <rocketraman@fastmail.fm> writes:

> Nanako Shiraishi wrote:
>> Quoting rocketraman@fastmail.fm:
>> 
>>> + - The 'maint' branch is updated to the new release.
>>> +
>>> +     $ git checkout maint
>>> +     $ git merge master
>>> +
>>> +   This is equivalent to deleting maint and recreating it from
>>> +   master, but it preserves the maint reflog.
>> 
>> After giving a recipe that is better than an alternative, what's
>> the point of describing an inferior alternative as "equivalent",
>> when it is obviously not "equivalent"?
>
> Is this better:
>
> The resulting maint tree is equivalent to deleting maint and
> recreating it from the tip of master, but merging from master
> preserves the maint reflog.

It is unclear what you are trying to explain with these two (in your
original) or three (your rewrite) lines.  As an explanation for the two
command sequence, I would expect to see:

    "This merges the tip of the master into maint".

But that is literally what the command sequence does, so it goes without
saying.

If there is anything that needs to be said further, I think it is not how
delete-then-recreate is inappropriate (I do not think it is even worth
teaching).  But you may want to explain the reason _why_ maint gets this
update from master.  I thought the explanation "... is updated to the new
release" already covers that motivation, but if you want to make the
description really novice-friendly, you _could_ say something like:

    Now a new release X.Y.Z is out, the 'maint' branch will be used to
    manage the fixes to it.  The branch used to be used for managing the
    fixes to X.Y.(Z-1), and does not have any feature development that
    happened between X.Y.(Z-1) and X.Y.Z.  Because these changes are
    contained in the 'master' branch, we can merge 'master' to 'maint' to
    have the latter have them, which prepares it to be used for managing
    the fixes to X.Y.Z.

I personally would not want to see somebody who needs the above to be
explained to take over git maintenance after I get hit by a wayward bus,
by the way ;-)

Re: [PATCH 1/2] Add feature release instructions to MaintNotes addendum

[Raman Gupta]

Junio C Hamano wrote:
> Raman Gupta <rocketraman@fastmail.fm> writes:
> 
>> Nanako Shiraishi wrote:
>>> Quoting rocketraman@fastmail.fm:
>>>
>>>> + - The 'maint' branch is updated to the new release.
>>>> +
>>>> +     $ git checkout maint
>>>> +     $ git merge master
>>>> +
>>>> +   This is equivalent to deleting maint and recreating it from
>>>> +   master, but it preserves the maint reflog.
>>> After giving a recipe that is better than an alternative, what's
>>> the point of describing an inferior alternative as "equivalent",
>>> when it is obviously not "equivalent"?
>> Is this better:
>>
>> The resulting maint tree is equivalent to deleting maint and
>> recreating it from the tip of master, but merging from master
>> preserves the maint reflog.
> 
> It is unclear what you are trying to explain with these two (in your
> original) or three (your rewrite) lines.  As an explanation for the two
> command sequence, I would expect to see:
> 
>     "This merges the tip of the master into maint".
> 
> But that is literally what the command sequence does, so it goes without
> saying.

Let me see if I can explain why I think the extra verbiage, at least
in some form, is useful...

It is my understanding that the _goal_ in this case is for the maint
tree to match the master tree (so that the maint tree matches the new
feature release). The "obvious" way to do that, at least for less
experienced folks, is to delete maint, and recreate it from the tip of
master (or from the feature release tag which should be the same commit).

In this particular case, because and only because of the semantics of
the maint and master branch i.e. we know that master already contains
everything that maint does, merging from master to maint makes the
trees equivalent, while *also* maintaining the reflog. However,
someone less familiar with the semantics of the maint and master
branches may not draw this conclusion automatically.

BTW, would:

git branch -f maint master

be another way of doing this?

> If there is anything that needs to be said further, I think it is not how
> delete-then-recreate is inappropriate (I do not think it is even worth
> teaching).  But you may want to explain the reason _why_ maint gets this
> update from master.  I thought the explanation "... is updated to the new
> release" already covers that motivation, but if you want to make the
> description really novice-friendly, you _could_ say something like:
> 
>     Now a new release X.Y.Z is out, the 'maint' branch will be used to
>     manage the fixes to it.  The branch used to be used for managing the
>     fixes to X.Y.(Z-1), and does not have any feature development that
>     happened between X.Y.(Z-1) and X.Y.Z.  Because these changes are
>     contained in the 'master' branch, we can merge 'master' to 'maint' to
>     have the latter have them, which prepares it to be used for managing
>     the fixes to X.Y.Z.
> 
> I personally would not want to see somebody who needs the above to be
> explained to take over git maintenance after I get hit by a wayward bus,
> by the way ;-)

:) Very true, but there are lots of people out there who are trying to
understand and use git, and when they come across documentation like
this they rightfully think "hey if this works for the git.git guys, it
would probably be a pretty good starting point for me as well!". I
know I did. So a bit of explanation may be appropriate, even though
its not relevant for your intended audience. On the other hand, maybe
the newbie-level explanation can be skipped here, and instead be put
into gitworkflows(7). For my next patch iteration, I'll assume that's
what you want unless you tell me otherwise.

Cheers,
Raman

Re: [PATCH 2/2] Add feature release instructions to gitworkflows man page

[Junio C Hamano]

Raman Gupta <rocketraman@fastmail.fm> writes:

> It might be useful to add some explanation of why one would want to
> rewind and rebuild vs simply continue as is.
>
> I guess the advantage is that the history for next starts out nice and
> clean for the next release, without any cruft from repeated merging of
> topic branches.

Repeated merges are usually not a major issue.  Summarization tools such
as log and shortlog can be told not to list merges.

What matters more is a revert of a topic, that looked promising when it
started, but later found undesirable or premature.  In such a case, the
topic is reverted out of 'next' and but the fact remains in the history
that it was once merged, and it was reverted.  We would want to get rid of
these records at some point to give a chance for another incarnation of
the topic done right a clean slate to retry, and a feature release is a
good point in history to do so.


> The disadvantage is that one must publish the operation and all forks
> must deal with the rebase.

Yes.

Re: [PATCH 2/2] Add feature release instructions to gitworkflows man page

[Raman Gupta]

Junio C Hamano wrote:
> Raman Gupta <rocketraman@fastmail.fm> writes:
> 
>> Junio C Hamano wrote:
>> ...
>> If you wish to remove discussion of 'next' from this document, that is
>> probably better done in a separate followup change. Though personally
>> I think its a useful concept for readers to learn about as they are
>> setting up their own workflows.
> 
> I do not have a particularly strong feeling about 'next' either way.
> 
> As the document states at the top, it lists ingredients from git.git
> management and it is left up to the readers to adopt parts that suit their
> needs, while not using others.  In that spirit, the description of 'next'
> as "ahead of master that is supposed to be rock solid" may be a good thing
> to keep.  It is orthogonal if the project wants to rewind and rebuild
> 'next' after every feature release---they do not need to (and we didn't do
> so for quite some time).  One valid choice by readers is to adopt the
> concept of 'next' in their project but never rewind and rebuild it, and
> you made that clear that it is optional.  So I think this part of your
> patch is good as-is.

It might be useful to add some explanation of why one would want to
rewind and rebuild vs simply continue as is.

I guess the advantage is that the history for next starts out nice and
clean for the next release, without any cruft from repeated merging of
topic branches.

The disadvantage is that one must publish the operation and all forks
must deal with the rebase.

Any other thoughts?

Cheers,
Raman

Re: [PATCH 2/2] Add feature release instructions to gitworkflows man page

[Junio C Hamano]

Raman Gupta <rocketraman@fastmail.fm> writes:

> Junio C Hamano wrote:
> ...
> If you wish to remove discussion of 'next' from this document, that is
> probably better done in a separate followup change. Though personally
> I think its a useful concept for readers to learn about as they are
> setting up their own workflows.

I do not have a particularly strong feeling about 'next' either way.

As the document states at the top, it lists ingredients from git.git
management and it is left up to the readers to adopt parts that suit their
needs, while not using others.  In that spirit, the description of 'next'
as "ahead of master that is supposed to be rock solid" may be a good thing
to keep.  It is orthogonal if the project wants to rewind and rebuild
'next' after every feature release---they do not need to (and we didn't do
so for quite some time).  One valid choice by readers is to adopt the
concept of 'next' in their project but never rewind and rebuild it, and
you made that clear that it is optional.  So I think this part of your
patch is good as-is.

>> Other parts (except for the "branch -f" bit I've already told you
>> about in the other message) looked good.
>
> 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.

Re: [PATCH 2/2] Add feature release instructions to gitworkflows man page

[Raman Gupta]

Junio C Hamano wrote:
> rocketraman@fastmail.fm writes:
> 
>> From: Raman Gupta <raman@rocketraman.com>
>>
>> Based on a mailing list discussion, add a description of the workflow,
>> and associated commands, for creating a feature release.
> 
> The same comment applies to the other one, but this commit log message is
> really lacking.  If you do not bother to summarize the discussion, place a
> pointer to the list archive, and more importantly, please describe *why*
> this change is desiable.

Ok will do.

> I am not sure rewinding and rebuilding of 'next', or even having 'next',
> is applicable for other projects as a BCP.  

Hmmm... The existing gitworkflows man page discusses the 'next' branch
several times. I am simply expanding the document to cover the branch
management associated with the git.git release process as well, which
necessarily includes a discussion of 'next'.

If you wish to remove discussion of 'next' from this document, that is
probably better done in a separate followup change. Though personally
I think its a useful concept for readers to learn about as they are
setting up their own workflows.

> Other parts (except for the "branch -f" bit I've already told you
> about in the other message) looked good.

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?

Cheers,
Raman

Re: [PATCH 2/2] Add feature release instructions to gitworkflows man page

[Junio C Hamano]

rocketraman@fastmail.fm writes:

> From: Raman Gupta <raman@rocketraman.com>
>
> Based on a mailing list discussion, add a description of the workflow,
> and associated commands, for creating a feature release.

The same comment applies to the other one, but this commit log message is
really lacking.  If you do not bother to summarize the discussion, place a
pointer to the list archive, and more importantly, please describe *why*
this change is desiable.

I am not sure rewinding and rebuilding of 'next', or even having 'next',
is applicable for other projects as a BCP.  Other parts (except for the
"branch -f" bit I've already told you about in the other message) looked
good.

Thanks.

[PATCH 2/2] Add feature release instructions to gitworkflows man page

[rocketraman]

From: Raman Gupta <raman@rocketraman.com>

Based on a mailing list discussion, add a description of the workflow,
and associated commands, for creating a feature release.

Signed-off-by: Raman Gupta <raman@rocketraman.com>
---
 Documentation/gitworkflows.txt |   73 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 73 insertions(+), 0 deletions(-)

diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 2b021e3..6a31d7b 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -348,6 +348,79 @@ 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
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The current maintenance branch is optionally copied to another branch
+named with the older release version number to allow for further
+maintenance releases on the older codebase. If the current tip of
+maint corresponds to an older release tag, then creating the maint
+branch for the older codebase can also be done later if and when it
+is required.
+
+.Copy maint
+[caption="Recipe: "]
+=====================================
+`git branch maint-X.Y.(Z-1) maint`
+=====================================
+
+'maint' is 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 branch -f maint master`
+=====================================
+
+This creates 'maint' from 'master', while preserving the 'maint'
+reflog.
+
+
+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