{"thread":{"id":"18555","subject":"[PATCH 2/2] Add feature release instructions to gitworkflows man page","startedAt":"2009-03-26T01:56:14Z","lastAt":"2009-03-26T21:37:06Z","messageCount":7,"participants":["rocketraman@fastmail.fm","Junio C Hamano","Raman Gupta"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"109456","messageId":"1238032575-10987-1-git-send-email-rocketraman@fastmail.fm","threadId":"18555","inReplyTo":null,"subject":"[PATCH 1/2] Add feature release instructions to MaintNotes addendum","fromName":"","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-03-26T01:56:14Z","receivedAt":"2009-03-26T01:56:14Z","isPatch":true,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"From: Raman Gupta <raman@rocketraman.com>\n\nBased on a mailing list discussion, add the operations for creating a\nfeature release.\n\nSigned-off-by: Raman Gupta <raman@rocketraman.com>\n---\n Documentation/howto/maintain-git.txt |   29 +++++++++++++++++++++++++++++\n 1 files changed, 29 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt\nindex 4357e26..f6ee0c5 100644\n--- a/Documentation/howto/maintain-git.txt\n+++ b/Documentation/howto/maintain-git.txt\n@@ -244,6 +244,35 @@ by doing the following:\n    repo.or.cz\n \n \n+A feature release of git is made by tagging 'master' with a tag\n+matching vX.Y.Z, where X.Y.Z is the feature release version.\n+\n+ - Optionally, track the current 'maint' branch to support\n+   new releases for the older codebase if necessary.\n+\n+     $ git branch maint-X.Y.(Z-1) maint\n+\n+ - The 'maint' branch is updated to the new release.\n+\n+     $ git checkout maint\n+     $ git merge master\n+\n+   This is equivalent to deleting maint and recreating it from\n+   master, but it preserves the maint reflog.\n+\n+ - The 'next' branch may be rebuilt from the tip of 'master'\n+   using the surviving topics on 'next'.\n+\n+     $ git branch -f next master\n+\n+   (Again, this approach preserves the reflog and per-branch\n+   configuration of 'next')\n+\n+     $ git merge ai/topic_in_next1\n+     $ git merge ai/topic_in_next2\n+     ...\n+\n+\n Some observations to be made.\n \n  * Each topic is tested individually, and also together with\n-- \n1.6.2\n"},{"id":"109455","messageId":"1238032575-10987-2-git-send-email-rocketraman@fastmail.fm","threadId":"18555","inReplyTo":"1238032575-10987-1-git-send-email-rocketraman@fastmail.fm","subject":"[PATCH 2/2] Add feature release instructions to gitworkflows man page","fromName":"","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-03-26T01:56:15Z","receivedAt":"2009-03-26T01:56:15Z","isPatch":true,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"From: Raman Gupta <raman@rocketraman.com>\n\nBased on a mailing list discussion, add a description of the workflow,\nand associated commands, for creating a feature release.\n\nSigned-off-by: Raman Gupta <raman@rocketraman.com>\n---\n Documentation/gitworkflows.txt |   69 ++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 69 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 2b021e3..1796878 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -348,6 +348,75 @@ in patches to figure out the merge base.  See linkgit:git-am[1] for\n other options.\n \n \n+RELEASE WORKFLOW\n+----------------\n+\n+The maintainer may use the following release workflow:\n+\n+He first tags the tip of 'master' with a release tag, then he updates\n+the 'maint' branch to the current tip of 'master' for managing future\n+maintenance fixes on the current release, and lastly he optionally\n+rebuilds 'next' from the tip of 'master'.\n+\n+\n+Release Tagging\n+~~~~~~~~~~~~~~~\n+\n+The new feature release is tagged on 'master' with a tag matching\n+vX.Y.Z, where X.Y.Z is the new feature release version.\n+\n+.Release tagging\n+[caption=\"Recipe: \"]\n+==========================================\n+`git tag -s -m GIT \"vX.Y.Z\" vX.Y.Z`\n+==========================================\n+\n+\n+Maintenance branch update\n+~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+The current maintenance branch is optionally tracked with the older\n+release version number to allow for further maintenance releases on\n+the older codebase.\n+\n+.Track maint\n+[caption=\"Recipe: \"]\n+=====================================\n+`git branch maint-X.Y.(Z-1) maint`\n+=====================================\n+\n+'maint' is now updated to the new release code so that maintenance\n+fixes can be merged for the current version.\n+\n+.Update maint to new release\n+[caption=\"Recipe: \"]\n+=====================================\n+* `git checkout maint`\n+* `git merge master`\n+=====================================\n+\n+This is equivalent to deleting maint and recreating it from master,\n+but it preserves the maint reflog.\n+\n+Update next branch\n+~~~~~~~~~~~~~~~~~~\n+\n+The 'next' branch may be rebuilt from the tip of 'master' using the\n+surviving topics on 'next'.\n+\n+This step is optional. If it is done by the maintainer, then a public\n+announcement will be made indicating that 'next' was rebased.\n+\n+.Update maint to new release\n+[caption=\"Recipe: \"]\n+=====================================\n+* `git branch -f next master`\n+* `git merge ai/topic_in_next1`\n+* `git merge ai/topic_in_next2`\n+* ...\n+=====================================\n+\n+\n SEE ALSO\n --------\n linkgit:gittutorial[7],\n-- \n1.6.2\n"},{"id":"109491","messageId":"7veiwksrsr.fsf@gitster.siamese.dyndns.org","threadId":"18555","inReplyTo":"1238032575-10987-2-git-send-email-rocketraman@fastmail.fm","subject":"Re: [PATCH 2/2] Add feature release instructions to gitworkflows man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-03-26T06:48:36Z","receivedAt":"2009-03-26T06:48:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"rocketraman@fastmail.fm writes:\n\n> +Release Tagging\n> +~~~~~~~~~~~~~~~\n> +\n> +The new feature release is tagged on 'master' with a tag matching\n> +vX.Y.Z, where X.Y.Z is the new feature release version.\n> +\n> +.Release tagging\n> +[caption=\"Recipe: \"]\n> +==========================================\n> +`git tag -s -m GIT \"vX.Y.Z\" vX.Y.Z`\n> +==========================================\n\nI actually always do:\n\n\tgit tag -s -m \"GIT X.Y.Z\" vX.Y.Z master\n\nThe argument to -m in your descriptoin is incorrectly quoted, and has an\nextra v.  I also spell out 'master' to avoid mistakes, and I would be\nhappy to encourage others to follow it.\n\n> +Maintenance branch update\n> +~~~~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +The current maintenance branch is optionally tracked with the older\n> +release version number to allow for further maintenance releases on\n> +the older codebase.\n> +\n> +.Track maint\n> +[caption=\"Recipe: \"]\n> +=====================================\n> +`git branch maint-X.Y.(Z-1) maint`\n> +=====================================\n\nThis creates maint-X.Y.(Z-1) from maint, but calling this step \"track\nmaint\" entirely misses the point.\n\nWhen people use the word \"track\", the intention is that they intend to\nmerge subsequent changes to the original branch (in this case, 'maint') to\nthe new branch ('maint-X.Y.(Z-1)') from time to time.\n\nThat is exactly opposite to what I create maint-X.Y.(Z-1) branch for.\nThis new \"branch to maintain an older codebase\" will *never* merge from\n'maint' after it forks.\n\n> +Update next branch\n> +~~~~~~~~~~~~~~~~~~\n> +\n> +The 'next' branch may be rebuilt from the tip of 'master' using the\n> +surviving topics on 'next'.\n> +\n> +This step is optional. If it is done by the maintainer, then a public\n> +announcement will be made indicating that 'next' was rebased.\n\nThe wording I use is more like 'rewound and rebuilt'.\n"},{"id":"109530","messageId":"49CB8871.2020605@fastmail.fm","threadId":"18555","inReplyTo":"20090326121017.6117@nanako3.lavabit.com","subject":"Re: [PATCH 1/2] Add feature release instructions to MaintNotes addendum","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-03-26T13:51:45Z","receivedAt":"2009-03-26T13:51:45Z","isPatch":true,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Nanako Shiraishi wrote:\n> Quoting rocketraman@fastmail.fm:\n> \n>> + - The 'maint' branch is updated to the new release.\n>> +\n>> +     $ git checkout maint\n>> +     $ git merge master\n>> +\n>> +   This is equivalent to deleting maint and recreating it from\n>> +   master, but it preserves the maint reflog.\n> \n> After giving a recipe that is better than an alternative, what's\n> the point of describing an inferior alternative as \"equivalent\",\n> when it is obviously not \"equivalent\"?\n\nIs this better:\n\nThe resulting maint tree is equivalent to deleting maint and\nrecreating it from the tip of master, but merging from master\npreserves the maint reflog.\n\nCheers,\nRaman\n"},{"id":"109538","messageId":"49CB92B2.6070909@fastmail.fm","threadId":"18555","inReplyTo":"7veiwksrsr.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH 2/2] Add feature release instructions to gitworkflows man page","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-03-26T14:35:30Z","receivedAt":"2009-03-26T14:35:30Z","isPatch":true,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Junio C Hamano wrote:\n> rocketraman@fastmail.fm writes:\n> \n>> +Release Tagging\n>> +~~~~~~~~~~~~~~~\n>> +\n>> +The new feature release is tagged on 'master' with a tag matching\n>> +vX.Y.Z, where X.Y.Z is the new feature release version.\n>> +\n>> +.Release tagging\n>> +[caption=\"Recipe: \"]\n>> +==========================================\n>> +`git tag -s -m GIT \"vX.Y.Z\" vX.Y.Z`\n>> +==========================================\n> \n> I actually always do:\n> \n> \tgit tag -s -m \"GIT X.Y.Z\" vX.Y.Z master\n> \n> The argument to -m in your descriptoin is incorrectly quoted, and has an\n> extra v.  I also spell out 'master' to avoid mistakes, and I would be\n> happy to encourage others to follow it.\n\nFixed.\n\n>> +Maintenance branch update\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~\n>> +\n>> +The current maintenance branch is optionally tracked with the older\n>> +release version number to allow for further maintenance releases on\n>> +the older codebase.\n>> +\n>> +.Track maint\n>> +[caption=\"Recipe: \"]\n>> +=====================================\n>> +`git branch maint-X.Y.(Z-1) maint`\n>> +=====================================\n> \n> This creates maint-X.Y.(Z-1) from maint, but calling this step \"track\n> maint\" entirely misses the point.\n> \n> When people use the word \"track\", the intention is that they intend to\n> merge subsequent changes to the original branch (in this case, 'maint') to\n> the new branch ('maint-X.Y.(Z-1)') from time to time.\n> \n> That is exactly opposite to what I create maint-X.Y.(Z-1) branch for.\n> This new \"branch to maintain an older codebase\" will *never* merge from\n> 'maint' after it forks.\n\nYeah, I originally had written \"Copy maint\" but copy seemed to be more\nsubversion-speak rather than git-speak so I changed it. However it\ndoes seem to accurately describe the operation. Would \"Copy maint\" be\nacceptable terminology?\n\n>> +Update next branch\n>> +~~~~~~~~~~~~~~~~~~\n>> +\n>> +The 'next' branch may be rebuilt from the tip of 'master' using the\n>> +surviving topics on 'next'.\n>> +\n>> +This step is optional. If it is done by the maintainer, then a public\n>> +announcement will be made indicating that 'next' was rebased.\n> \n> The wording I use is more like 'rewound and rebuilt'.\n\nFixed.\n\nCheers,\nRaman\n"},{"id":"109566","messageId":"7vprg4m3k9.fsf@gitster.siamese.dyndns.org","threadId":"18555","inReplyTo":"49CB8871.2020605@fastmail.fm","subject":"Re: [PATCH 1/2] Add feature release instructions to MaintNotes addendum","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-03-26T20:28:38Z","receivedAt":"2009-03-26T20:28:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Raman Gupta <rocketraman@fastmail.fm> writes:\n\n> Nanako Shiraishi wrote:\n>> Quoting rocketraman@fastmail.fm:\n>> \n>>> + - The 'maint' branch is updated to the new release.\n>>> +\n>>> +     $ git checkout maint\n>>> +     $ git merge master\n>>> +\n>>> +   This is equivalent to deleting maint and recreating it from\n>>> +   master, but it preserves the maint reflog.\n>> \n>> After giving a recipe that is better than an alternative, what's\n>> the point of describing an inferior alternative as \"equivalent\",\n>> when it is obviously not \"equivalent\"?\n>\n> Is this better:\n>\n> The resulting maint tree is equivalent to deleting maint and\n> recreating it from the tip of master, but merging from master\n> preserves the maint reflog.\n\nIt is unclear what you are trying to explain with these two (in your\noriginal) or three (your rewrite) lines.  As an explanation for the two\ncommand sequence, I would expect to see:\n\n    \"This merges the tip of the master into maint\".\n\nBut that is literally what the command sequence does, so it goes without\nsaying.\n\nIf there is anything that needs to be said further, I think it is not how\ndelete-then-recreate is inappropriate (I do not think it is even worth\nteaching).  But you may want to explain the reason _why_ maint gets this\nupdate from master.  I thought the explanation \"... is updated to the new\nrelease\" already covers that motivation, but if you want to make the\ndescription really novice-friendly, you _could_ say something like:\n\n    Now a new release X.Y.Z is out, the 'maint' branch will be used to\n    manage the fixes to it.  The branch used to be used for managing the\n    fixes to X.Y.(Z-1), and does not have any feature development that\n    happened between X.Y.(Z-1) and X.Y.Z.  Because these changes are\n    contained in the 'master' branch, we can merge 'master' to 'maint' to\n    have the latter have them, which prepares it to be used for managing\n    the fixes to X.Y.Z.\n\nI personally would not want to see somebody who needs the above to be\nexplained to take over git maintenance after I get hit by a wayward bus,\nby the way ;-)\n"},{"id":"109581","messageId":"49CBF582.8010406@fastmail.fm","threadId":"18555","inReplyTo":"7vprg4m3k9.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Add feature release instructions to MaintNotes addendum","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-03-26T21:37:06Z","receivedAt":"2009-03-26T21:37:06Z","isPatch":true,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Junio C Hamano wrote:\n> Raman Gupta <rocketraman@fastmail.fm> writes:\n> \n>> Nanako Shiraishi wrote:\n>>> Quoting rocketraman@fastmail.fm:\n>>>\n>>>> + - The 'maint' branch is updated to the new release.\n>>>> +\n>>>> +     $ git checkout maint\n>>>> +     $ git merge master\n>>>> +\n>>>> +   This is equivalent to deleting maint and recreating it from\n>>>> +   master, but it preserves the maint reflog.\n>>> After giving a recipe that is better than an alternative, what's\n>>> the point of describing an inferior alternative as \"equivalent\",\n>>> when it is obviously not \"equivalent\"?\n>> Is this better:\n>>\n>> The resulting maint tree is equivalent to deleting maint and\n>> recreating it from the tip of master, but merging from master\n>> preserves the maint reflog.\n> \n> It is unclear what you are trying to explain with these two (in your\n> original) or three (your rewrite) lines.  As an explanation for the two\n> command sequence, I would expect to see:\n> \n>     \"This merges the tip of the master into maint\".\n> \n> But that is literally what the command sequence does, so it goes without\n> saying.\n\nLet me see if I can explain why I think the extra verbiage, at least\nin some form, is useful...\n\nIt is my understanding that the _goal_ in this case is for the maint\ntree to match the master tree (so that the maint tree matches the new\nfeature release). The \"obvious\" way to do that, at least for less\nexperienced folks, is to delete maint, and recreate it from the tip of\nmaster (or from the feature release tag which should be the same commit).\n\nIn this particular case, because and only because of the semantics of\nthe maint and master branch i.e. we know that master already contains\neverything that maint does, merging from master to maint makes the\ntrees equivalent, while *also* maintaining the reflog. However,\nsomeone less familiar with the semantics of the maint and master\nbranches may not draw this conclusion automatically.\n\nBTW, would:\n\ngit branch -f maint master\n\nbe another way of doing this?\n\n> If there is anything that needs to be said further, I think it is not how\n> delete-then-recreate is inappropriate (I do not think it is even worth\n> teaching).  But you may want to explain the reason _why_ maint gets this\n> update from master.  I thought the explanation \"... is updated to the new\n> release\" already covers that motivation, but if you want to make the\n> description really novice-friendly, you _could_ say something like:\n> \n>     Now a new release X.Y.Z is out, the 'maint' branch will be used to\n>     manage the fixes to it.  The branch used to be used for managing the\n>     fixes to X.Y.(Z-1), and does not have any feature development that\n>     happened between X.Y.(Z-1) and X.Y.Z.  Because these changes are\n>     contained in the 'master' branch, we can merge 'master' to 'maint' to\n>     have the latter have them, which prepares it to be used for managing\n>     the fixes to X.Y.Z.\n> \n> I personally would not want to see somebody who needs the above to be\n> explained to take over git maintenance after I get hit by a wayward bus,\n> by the way ;-)\n\n:) Very true, but there are lots of people out there who are trying to\nunderstand and use git, and when they come across documentation like\nthis they rightfully think \"hey if this works for the git.git guys, it\nwould probably be a pretty good starting point for me as well!\". I\nknow I did. So a bit of explanation may be appropriate, even though\nits not relevant for your intended audience. On the other hand, maybe\nthe newbie-level explanation can be skipped here, and instead be put\ninto gitworkflows(7). For my next patch iteration, I'll assume that's\nwhat you want unless you tell me otherwise.\n\nCheers,\nRaman\n"}]}