{"thread":{"id":"18632","subject":"[PATCH 1/2] Add feature release instructions to MaintNotes addendum","startedAt":"2009-03-30T05:35:18Z","lastAt":"2009-04-01T16:15:08Z","messageCount":9,"participants":["rocketraman@fastmail.fm","Junio C Hamano","Raman Gupta"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"109829","messageId":"1238391319-4953-1-git-send-email-rocketraman@fastmail.fm","threadId":"18632","inReplyTo":null,"subject":"[PATCH 1/2] Add feature release instructions to MaintNotes addendum","fromName":"","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-03-30T05:35:18Z","receivedAt":"2009-03-30T05:35:18Z","isPatch":true,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"From: Raman Gupta \n\nBased on a mailing list discussion, add the operations for creating a\nfeature release.\n\nSigned-off-by: Raman Gupta \n---\n Documentation/howto/maintain-git.txt | 21 +++++++++++++++++++++\n 1 files changed, 21 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt\nindex 4357e26..f8b7614 100644\n--- a/Documentation/howto/maintain-git.txt\n+++ b/Documentation/howto/maintain-git.txt\n@@ -244,6 +244,27 @@ 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 branch -f maint master\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+ $ 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":"109830","messageId":"1238391319-4953-2-git-send-email-rocketraman@fastmail.fm","threadId":"18632","inReplyTo":"1238391319-4953-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-30T05:35:19Z","receivedAt":"2009-03-30T05:35:19Z","isPatch":true,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"From: Raman Gupta \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 \n---\n Documentation/gitworkflows.txt | 73 ++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 73 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 2b021e3..6a31d7b 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -348,6 +348,79 @@ 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 X.Y.Z\" vX.Y.Z master`\n+==========================================\n+\n+\n+Maintenance branch update\n+~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+The current maintenance branch is optionally copied to another branch\n+named with the older release version number to allow for further\n+maintenance releases on the older codebase. If the current tip of\n+maint corresponds to an older release tag, then creating the maint\n+branch for the older codebase can also be done later if and when it\n+is required.\n+\n+.Copy 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 branch -f maint master`\n+=====================================\n+\n+This creates 'maint' from 'master', while preserving the 'maint'\n+reflog.\n+\n+\n+Update next branch\n+~~~~~~~~~~~~~~~~~~\n+\n+The 'next' branch may be rewound and rebuilt from the tip of 'master'\n+using the 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 rewound and\n+rebuilt.\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":"109842","messageId":"7vr60fijn5.fsf@gitster.siamese.dyndns.org","threadId":"18632","inReplyTo":"1238391319-4953-1-git-send-email-rocketraman@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-30T06:56:14Z","receivedAt":"2009-03-30T06:56:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"rocketraman@fastmail.fm writes:\n\n> + - The 'maint' branch is updated to the new release.\n> +\n> + $ git branch -f maint master\n\nIt appears that you are trying to make this document into a canned set of\ninsns for people who want a ready-to-cut-and-paste-without-thinking\nrecipe, and I am perfectly fine with such a document, but as I mentioned\nalready, \"how to maintain git\" is not a good place to do so. You seem to\nhave taken it as a joke, but I am serious.\n\nIn any case, I highly doubt we would want to have this \"branch -f\" here.\nNot in \"how to maintain git\", but especially in a document you would give\nto people who do not like to think for themselves but would want to follow\ncut-and-paste recipe.\n\n_I_ can do the above, but that is _only_ because I maintain 'master' with\ncertain discipline---it almost always is a superset of maint (it sometimes\nisn't---when I am too tired to do so late at night and the leftover fix on\nthe 'maint' unmerged to 'master' is really trivial and unimportant in the\ngrand scheme of things), and especially after a big release it always is.\n\nBut for people who want to use a ready-to-cut-and-paste-without-thinking\nrecipe, it is much better to use:\n\n\t$ git checkout maint\n\t$ git merge master\n\njust in case they have leftover fixes that later need to get merged to\nmaster. Otherwise they will be discarding the fixes with \"branch -f\".\n\nAn obvious alternative is to firmly describe in the release workflow to\nmake sure that 'maint' is fully merged to 'master' before a release is\nmade, but people tend to cherry-pick the parts they want to use without\nthinking things through when presented a cut-and-paste recipe, and in\npractice I do not think such an alternative would work well.\n\nMore important bits of release checklist, a bit outdated, is found in\nChecklist.txt file on the 'todo' branch. \n\nI would need to talk a bit more about how to maintain What's in/cooking,\nhow the automated maintenance of html/man branches work, and how to set up\nRPM building infrastructure for use with Meta/DoKernelOrg, in order to\nmake the Documentation/howto/maintain-git.txt truly to be usable by\nsomebody capable to take over when I cease to function as the maintainer\nhere.\n"},{"id":"109843","messageId":"7vk567ijlf.fsf@gitster.siamese.dyndns.org","threadId":"18632","inReplyTo":"1238391319-4953-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-30T06:57:16Z","receivedAt":"2009-03-30T06:57:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"rocketraman@fastmail.fm writes:\n\n> From: Raman Gupta \n>\n> Based on a mailing list discussion, add a description of the workflow,\n> and associated commands, for creating a feature release.\n\nThe same comment applies to the other one, but this commit log message is\nreally lacking. If you do not bother to summarize the discussion, place a\npointer to the list archive, and more importantly, please describe *why*\nthis change is desiable.\n\nI am not sure rewinding and rebuilding of 'next', or even having 'next',\nis applicable for other projects as a BCP. Other parts (except for the\n\"branch -f\" bit I've already told you about in the other message) looked\ngood.\n\nThanks.\n"},{"id":"109929","messageId":"49D10826.9080003@fastmail.fm","threadId":"18632","inReplyTo":"7vr60fijn5.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-30T17:57:58Z","receivedAt":"2009-03-30T17:57:58Z","isPatch":true,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Junio C Hamano wrote:\n> rocketraman@fastmail.fm writes:\n> \n>> + - The 'maint' branch is updated to the new release.\n>> +\n>> + $ git branch -f maint master\n> \n> It appears that you are trying to make this document into a canned set of\n> insns for people who want a ready-to-cut-and-paste-without-thinking\n> recipe, and I am perfectly fine with such a document, but as I mentioned\n> already, \"how to maintain git\" is not a good place to do so. You seem to\n> have taken it as a joke, but I am serious.\n\nI guess the smiley face when you said that threw me off :)\n\nBased on your feedback, I'll withdraw my patch for MaintNotes -- my\nintention in patching it was to provide more information for newbies\nor people reading it out of curiosity, however you're absolutely right\n-- it is not the right place for that type of information.\n\nIt does need more info in some of the other areas you mentioned and I\nwould love to help but I'm not knowledgeable enough to do so and I\nfear I'll be more of a hindrance than a help.\n\nCheers,\nRaman\n"},{"id":"109930","messageId":"49D10875.2060008@fastmail.fm","threadId":"18632","inReplyTo":"7vk567ijlf.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-30T17:59:17Z","receivedAt":"2009-03-30T17:59:17Z","isPatch":true,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Junio C Hamano wrote:\n> rocketraman@fastmail.fm writes:\n> \n>> From: Raman Gupta \n>>\n>> Based on a mailing list discussion, add a description of the workflow,\n>> and associated commands, for creating a feature release.\n> \n> The same comment applies to the other one, but this commit log message is\n> really lacking. If you do not bother to summarize the discussion, place a\n> pointer to the list archive, and more importantly, please describe *why*\n> this change is desiable.\n\nOk will do.\n\n> I am not sure rewinding and rebuilding of 'next', or even having 'next',\n> is applicable for other projects as a BCP. \n\nHmmm... The existing gitworkflows man page discusses the 'next' branch\nseveral times. I am simply expanding the document to cover the branch\nmanagement associated with the git.git release process as well, which\nnecessarily includes a discussion of 'next'.\n\nIf you wish to remove discussion of 'next' from this document, that is\nprobably better done in a separate followup change. Though personally\nI think its a useful concept for readers to learn about as they are\nsetting up their own workflows.\n\n> Other parts (except for the \"branch -f\" bit I've already told you\n> about in the other message) looked good.\n\nI'll add some discussion about the branch -f bit -- I hope you agree\nthat in this document that is distributed with git, some\nbeginner-level explanation of the difference between the branch -f and\nthe merge approach is warranted?\n\nCheers,\nRaman\n"},{"id":"109933","messageId":"7vljqmdgj0.fsf@gitster.siamese.dyndns.org","threadId":"18632","inReplyTo":"49D10875.2060008@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-30T18:14:43Z","receivedAt":"2009-03-30T18:14:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Raman Gupta writes:\n\n> Junio C Hamano wrote:\n> ...\n> If you wish to remove discussion of 'next' from this document, that is\n> probably better done in a separate followup change. Though personally\n> I think its a useful concept for readers to learn about as they are\n> setting up their own workflows.\n\nI do not have a particularly strong feeling about 'next' either way.\n\nAs the document states at the top, it lists ingredients from git.git\nmanagement and it is left up to the readers to adopt parts that suit their\nneeds, while not using others. In that spirit, the description of 'next'\nas \"ahead of master that is supposed to be rock solid\" may be a good thing\nto keep. It is orthogonal if the project wants to rewind and rebuild\n'next' after every feature release---they do not need to (and we didn't do\nso for quite some time). One valid choice by readers is to adopt the\nconcept of 'next' in their project but never rewind and rebuild it, and\nyou made that clear that it is optional. So I think this part of your\npatch is good as-is.\n\n>> Other parts (except for the \"branch -f\" bit I've already told you\n>> about in the other message) looked good.\n>\n> I'll add some discussion about the branch -f bit -- I hope you agree\n> that in this document that is distributed with git, some\n> beginner-level explanation of the difference between the branch -f and\n> the merge approach is warranted?\n\nSurely and thanks.\n"},{"id":"109936","messageId":"49D1120B.8060601@fastmail.fm","threadId":"18632","inReplyTo":"7vljqmdgj0.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-30T18:40:11Z","receivedAt":"2009-03-30T18:40:11Z","isPatch":true,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Junio C Hamano wrote:\n> Raman Gupta writes:\n> \n>> Junio C Hamano wrote:\n>> ...\n>> If you wish to remove discussion of 'next' from this document, that is\n>> probably better done in a separate followup change. Though personally\n>> I think its a useful concept for readers to learn about as they are\n>> setting up their own workflows.\n> \n> I do not have a particularly strong feeling about 'next' either way.\n> \n> As the document states at the top, it lists ingredients from git.git\n> management and it is left up to the readers to adopt parts that suit their\n> needs, while not using others. In that spirit, the description of 'next'\n> as \"ahead of master that is supposed to be rock solid\" may be a good thing\n> to keep. It is orthogonal if the project wants to rewind and rebuild\n> 'next' after every feature release---they do not need to (and we didn't do\n> so for quite some time). One valid choice by readers is to adopt the\n> concept of 'next' in their project but never rewind and rebuild it, and\n> you made that clear that it is optional. So I think this part of your\n> patch is good as-is.\n\nIt might be useful to add some explanation of why one would want to\nrewind and rebuild vs simply continue as is.\n\nI guess the advantage is that the history for next starts out nice and\nclean for the next release, without any cruft from repeated merging of\ntopic branches.\n\nThe disadvantage is that one must publish the operation and all forks\nmust deal with the rebase.\n\nAny other thoughts?\n\nCheers,\nRaman\n"},{"id":"110149","messageId":"7vtz581hbn.fsf@gitster.siamese.dyndns.org","threadId":"18632","inReplyTo":"49D1120B.8060601@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-04-01T16:15:08Z","receivedAt":"2009-04-01T16:15:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Raman Gupta writes:\n\n> It might be useful to add some explanation of why one would want to\n> rewind and rebuild vs simply continue as is.\n>\n> I guess the advantage is that the history for next starts out nice and\n> clean for the next release, without any cruft from repeated merging of\n> topic branches.\n\nRepeated merges are usually not a major issue. Summarization tools such\nas log and shortlog can be told not to list merges.\n\nWhat matters more is a revert of a topic, that looked promising when it\nstarted, but later found undesirable or premature. In such a case, the\ntopic is reverted out of 'next' and but the fact remains in the history\nthat it was once merged, and it was reverted. We would want to get rid of\nthese records at some point to give a chance for another incarnation of\nthe topic done right a clean slate to retry, and a feature release is a\ngood point in history to do so.\n\n\n> The disadvantage is that one must publish the operation and all forks\n> must deal with the rebase.\n\nYes.\n"}]}