{"thread":{"id":"21569","subject":"[PATCHv2] Update gitworkflows man page to include release workflow","startedAt":"2009-11-10T16:08:58Z","lastAt":"2009-11-12T16:54:54Z","messageCount":13,"participants":["rocketraman@fastmail.fm","Štěpán Němec","Raman Gupta","Thiago Farina","Junio C Hamano","Thomas Rast"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"127251","messageId":"1257869339-15999-1-git-send-email-rocketraman@fastmail.fm","threadId":"21569","inReplyTo":null,"subject":"Update gitworkflows man page to include release workflow","fromName":"","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-10T16:08:58Z","receivedAt":"2009-11-10T16:08:58Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"\nResubmission 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:\n\nhttp://thread.gmane.org/gmane.comp.version-control.git/114704/focus=114703\nhttp://thread.gmane.org/gmane.comp.version-control.git/115079/focus=115080\n\nSorry for the delay in resubmitting.\n\nCheers,\nRaman\n"},{"id":"127249","messageId":"1257869339-15999-2-git-send-email-rocketraman@fastmail.fm","threadId":"21569","inReplyTo":"1257869339-15999-1-git-send-email-rocketraman@fastmail.fm","subject":"[PATCHv2] Update gitworkflows man page to include release workflow","fromName":"","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-10T16:08:59Z","receivedAt":"2009-11-10T16:08:59Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"From: Raman Gupta \n\nThe gitworkflows man page currently provides an overview of the workflows\nused by git.git itself to serve as inspiration for people to use when\ndesigning their own workflows. The current man page does a reasonable\njob at describing the development process, but it does not contain any\nguidance as to the workflow used for releases. Now add a basic\nintroduction to the branch management required for a release, so that a\nreader may understand how the maint, master, next, and topic branches are\naffected.\n---\n Documentation/gitworkflows.txt | 97 ++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 97 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 2b021e3..69b789a 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -348,6 +348,103 @@ 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+Maintenance fixes for the current feature release are tracked on the\n+'maint' branch.\n+\n+\n+In order to track maintenance\n+fixes to the current release, the maintainer uses a branch called\n+'maint'.\n+\n+\n+The current maintenance branch is optionally copied to another branch\n+named with the older release version number (e.g. maint-X.Y.(Z-1)\n+where X.Y.Z is the previous release). This allows for further\n+maintenance releases on the older codebase.\n+\n+If the current tip of 'maint' corresponds to the previous release\n+tag (i.e. that there are no fixes already pending on 'maint' that are\n+intended for a maintenance release on the older codebase), then\n+creating the 'maint' branch for the older codebase can also be done\n+later, if it is needed.\n+\n+.Copy maint\n+[caption=\"Recipe: \"]\n+=====================================\n+`git branch maint-X.Y.(Z-1) maint`\n+=====================================\n+\n+'maint' should 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 updates 'maint' from 'master', while preserving the 'maint'\n+reflog.\n+\n+An alternative approach to updating the 'maint' branch is to run\n+\n+ $ git branch -f maint master\n+\n+This will create a new 'maint' branch based on 'master'. If 'maint'\n+already exists, it will be deleted before the new branch is created.\n+Any commits on 'maint' that were not previously merged to master will\n+therefore be lost and the 'maint' reflog will be reset. However, the\n+branch history is \"clean\" and may be easier to understand.\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":"127257","messageId":"20091110180612.GB12012@headley","threadId":"21569","inReplyTo":"1257869339-15999-2-git-send-email-rocketraman@fastmail.fm","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2009-11-10T18:06:12Z","receivedAt":"2009-11-10T18:06:12Z","isPatch":false,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"On Tue, Nov 10, 2009 at 11:08:59AM -0500, rocketraman@fastmail.fm wrote:\n\nA small typo:\n\n> +'maint' should now updated to the new release code so that maintenance\n> +fixes can be merged for the current version:\n\nThere is a missing `be' somewhere, something like: \"'maint' should now be\nupdated...\"\n\nRegards,\n\nŠtěpán\n"},{"id":"127258","messageId":"4AF9AC81.4040902@fastmail.fm","threadId":"21569","inReplyTo":"20091110180612.GB12012@headley","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-10T18:10:09Z","receivedAt":"2009-11-10T18:10:09Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Štěpán Němec wrote:\n> On Tue, Nov 10, 2009 at 11:08:59AM -0500, rocketraman@fastmail.fm wrote:\n> \n> A small typo:\n> \n>> +'maint' should now updated to the new release code so that maintenance\n>> +fixes can be merged for the current version:\n> \n> There is a missing `be' somewhere, something like: \"'maint' should now be\n> updated...\"\n\nOops, thanks, good catch.\n\nCheers,\nRaman\n"},{"id":"127325","messageId":"a4c8a6d00911110505m2f21a787sfb3e0d6c130b0b4d@mail.gmail.com","threadId":"21569","inReplyTo":"1257869339-15999-2-git-send-email-rocketraman@fastmail.fm","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Thiago Farina","fromEmail":"tfransosi@gmail.com","sentAt":"2009-11-11T13:05:57Z","receivedAt":"2009-11-11T13:05:57Z","isPatch":false,"sender":{"key":"tfransosi@gmail.com","avatar":"https://avatars.githubusercontent.com/u/970071?v=4"},"body":"Hi,\n\nOn Tue, Nov 10, 2009 at 2:08 PM, wrote:\n> From: Raman Gupta \n>\n> The gitworkflows man page currently provides an overview of the workflows\n> used by git.git itself to serve as inspiration for people to use when\n> designing their own workflows. The current man page does a reasonable\n> job at describing the development process, but it does not contain any\n> guidance as to the workflow used for releases. Now add a basic\n> introduction to the branch management required for a release, so that a\n> reader may understand how the maint, master, next, and topic branches are\n> affected.\nHere\nhttp://git.kernel.org/?p=git/git.git;a=blob;f=Checklist.txt;h=37745f39487537117fb7f3a9a6f5b8e7d989a884;hb=refs/heads/todo\nthere is a release checklist, maybe you could extend your patch to\ninclude more information from this?\n"},{"id":"127339","messageId":"4AFAD6EE.3010205@fastmail.fm","threadId":"21569","inReplyTo":"a4c8a6d00911110505m2f21a787sfb3e0d6c130b0b4d@mail.gmail.com","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-11T15:23:26Z","receivedAt":"2009-11-11T15:23:26Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Thiago Farina wrote:\n> Hi,\n> \n> On Tue, Nov 10, 2009 at 2:08 PM, wrote:\n>> From: Raman Gupta \n>>\n>> The gitworkflows man page currently provides an overview of the workflows\n>> used by git.git itself to serve as inspiration for people to use when\n>> designing their own workflows. The current man page does a reasonable\n>> job at describing the development process, but it does not contain any\n>> guidance as to the workflow used for releases. Now add a basic\n>> introduction to the branch management required for a release, so that a\n>> reader may understand how the maint, master, next, and topic branches are\n>> affected.\n> Here\n> http://git.kernel.org/?p=git/git.git;a=blob;f=Checklist.txt;h=37745f39487537117fb7f3a9a6f5b8e7d989a884;hb=refs/heads/todo\n> there is a release checklist, maybe you could extend your patch to\n> include more information from this?\n\nMost of the checklist is specific to the git infrastructure rather\nthan git branch management. The latter is the focus of the\ngitworkflows man page. The relevant items from checklist.txt (e.g.\nmerge 'maint' to 'master') are already included in the patch.\n\nCheers,\nRaman\n"},{"id":"127367","messageId":"7vzl6soniu.fsf@alter.siamese.dyndns.org","threadId":"21569","inReplyTo":"1257869339-15999-2-git-send-email-rocketraman@fastmail.fm","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-11-11T19:43:37Z","receivedAt":"2009-11-11T19:43:37Z","isPatch":false,"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> The gitworkflows man page currently provides an overview of the workflows\n> used by git.git itself to serve as inspiration for people to use when\n> designing their own workflows. The current man page does a reasonable\n> job at describing the development process, but it does not contain any\n> guidance as to the workflow used for releases. Now add a basic\n> introduction to the branch management required for a release, so that a\n> reader may understand how the maint, master, next, and topic branches are\n> affected.\n> ---\n\nIs this meant to show how git.git does its release to serve as an\ninspiration to others? The document does not seem to describe how I make\nreleases.\n\n> diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\n> index 2b021e3..69b789a 100644\n> --- a/Documentation/gitworkflows.txt\n> +++ b/Documentation/gitworkflows.txt\n> @@ -348,6 +348,103 @@ 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\nPlease set the tone straight. If this is to suggest various possible\nworkflows in general vague terms, \"may use\" would be good. If this is to\nprecisely describe what I do, then there won't be \"you could do this, or\nyou could do that.\" Your \"may use\" suggests the former, but the commit\nlog message claims the latter. Which document are you writing?\n\nAssuming that you are writing what I do...\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\nNot in that order.\n\n\t- doubly make sure that there is nothing left in 'maint' that\n\t is not in 'master';\n\t- review 'master' more thoroughly than usual;\n\t- review RelNotes symlink, Documentation/RelNotes-X.Y.Z.txt,\n the stalenotes section in Documentation/git.git, and\n GIT-VERSION-GEN for the last time;\n - tag it;\n - review it again for the last time;\n\t- test on buildfarm;\n\t- cut tarball;\n - cut RPM on FC11 i386 and FC11 x86_64;\n - push the tag and master branch alone to the public server---this\n triggers an autobuilder for documentation pages, updates man and\n html branches and documentation tarballs;\n\nWhen making a maintenance release, everything is the same except that\n'maint' is used instead of 'master'.\n\nThen, after all the release task on 'master' (or 'maint') is done,\npropagate that upwards (i.e. merge 'master' to 'next' and 'pu').\n\nMerging 'master' to 'maint' is done totally as a separate step, often a\nfew days later, \"Now the big release is done, let's start maintenance\ntrack for that relase\".\n\nAnd then after that, 'next' may be rebuilt.\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\nThere is no incorrect information here, but I do not think there is\nanything particularly worth saying here, either. It is in \"git tag\"\nmanpage and anybody can run \"git cat-file tag v1.6.3\" to learn what is in\nthere.\n\n> +Maintenance branch update\n> +~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis section largely overlaps with Documentation/howto/maintain-git.txt; I\nam starting to doubt if we even need a new section in the workflows\ndocument. Perhaps we could have a release management section in the\nDocumentation/howto/maintain-git.txt, though.\n\n> +[caption=\"Recipe: \"]\n> +=====================================\n> +* `git checkout maint`\n> +* `git merge master`\n> +=====================================\n> +\n> +This updates 'maint' from 'master', while preserving the 'maint'\n> +reflog.\n> +\n> +An alternative approach to updating the 'maint' branch is to run\n> +\n> + $ git branch -f maint master\n\nAs I already said, I never do this \"alternative\", and I do not want\nanybody who will take over git.git maintenance to do so. There is no\nreason to encourage nor even mention \"branch -f\" here. As 'maint' is\nsupposed to be a strict subset, pulling 'master' to 'maint' should fast\nforward and otherwise you (the maintainer) would notice that there was a\nmistake made. If you use \"branch -f\", you will never notice.\n"},{"id":"127374","messageId":"200911112142.00209.trast@student.ethz.ch","threadId":"21569","inReplyTo":"1257869339-15999-2-git-send-email-rocketraman@fastmail.fm","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2009-11-11T20:41:58Z","receivedAt":"2009-11-11T20:41:58Z","isPatch":false,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"It's nice to see someone work on this manpage :-) I sadly do not have\nthe time to read the whole patch right now, though I'll try and catch\nup tomorrow or so. In the meantime I do have one remark:\n\nrocketraman@fastmail.fm wrote:\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\nThe current gitworkflows is mostly formulated in the imperative, as in\n\n To test the interaction of several topics, merge them into a\n throw-away branch. You must never base any work on such a branch!\n\nor by directly describing the tools in the third person, as in\n\n * linkgit:git-push[1] copies your branches to a remote repository,\n usually to one that can be read by all involved parties;\n\nIt would certainly be nice to be somewhat consistent. Since at first\nglance your description is aimed at the maintainer himself, I assume\nthat would mostly mean addressing the maintainer as \"you\", and\nformulating the rules in the imperative.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"127406","messageId":"4AFB57A3.2020002@fastmail.fm","threadId":"21569","inReplyTo":"7vzl6soniu.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-12T00:32:35Z","receivedAt":"2009-11-12T00:32:35Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Thanks for your review. Comments inline.\n\nJunio C Hamano wrote:\n> rocketraman@fastmail.fm writes:\n> \n>> From: Raman Gupta \n>>\n>> The gitworkflows man page currently provides an overview of the workflows\n>> used by git.git itself to serve as inspiration for people to use when\n>> designing their own workflows. The current man page does a reasonable\n>> job at describing the development process, but it does not contain any\n>> guidance as to the workflow used for releases. Now add a basic\n>> introduction to the branch management required for a release, so that a\n>> reader may understand how the maint, master, next, and topic branches are\n>> affected.\n>> ---\n> \n> Is this meant to show how git.git does its release to serve as an\n> inspiration to others? The document does not seem to describe how I make\n> releases.\n\nHere is the existing intro to gitworkflows:\n\n===================\nThis document attempts to write down and motivate some of the workflow\nelements used for git.git itself. Many ideas apply in general, though\nthe full workflow is rarely required for smaller projects with fewer\npeople involved.\n\nWe formulate a set of rules for quick reference, while the prose tries\nto motivate each of them. Do not always take them literally; you\nshould value good reasons for your actions higher than manpages such\nas this one.\n===================\n\nIt is in this spirit that I am attempting to add to this document in\nrelation to the release process. If after you read through this email\nyou don't agree this patch has any value in gitworkflows, let me know\nso that I can stop wasting my time and yours.\n\n>> diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\n>> index 2b021e3..69b789a 100644\n>> --- a/Documentation/gitworkflows.txt\n>> +++ b/Documentation/gitworkflows.txt\n>> @@ -348,6 +348,103 @@ 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> Please set the tone straight. If this is to suggest various possible\n> workflows in general vague terms, \"may use\" would be good. If this is to\n> precisely describe what I do, then there won't be \"you could do this, or\n> you could do that.\" Your \"may use\" suggests the former, but the commit\n> log message claims the latter. Which document are you writing?\n\nOk. The current document is inconsistent. In places it uses \"the\nmaintainer\" and in other places it uses \"you\". In any case, it seems\nthat the \"maintainer\" here is not \"Junio Hamano\" -- rather, it is the\nreader.\n\nLet me create a separate (and first) cleanup patch to fix the existing\ninconsistencies in this man page. I would prefer to use the pronoun\n\"you\" consistently as also suggested by Thomas Rast.\n\nIn addition, I will update the commit log message to be consistent.\n\n>\n> Assuming that you are writing what I do...\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> Not in that order.\n\nOk, I'll work on the order.\n\n> \t- doubly make sure that there is nothing left in 'maint' that\n> \t is not in 'master';\n> \t- review 'master' more thoroughly than usual;\n\nAs per the intro to the man page, I think you will agree these items\nare not required. They follow under the category of the user thinking\nabout what they are doing -- the man page is not meant to provide the\nuser with a \"monkey-see, monkey-do\" series of steps.\n\n> \t- review RelNotes symlink, Documentation/RelNotes-X.Y.Z.txt,\n> the stalenotes section in Documentation/git.git, and\n> GIT-VERSION-GEN for the last time;\n> - tag it;\n> - review it again for the last time;\n> \t- test on buildfarm;\n> \t- cut tarball;\n> - cut RPM on FC11 i386 and FC11 x86_64;\n\nI will update the commit log message to show that my intent was to\ntalk about how the git.git integration and topic branches are affected\nby the release rather than providing a complete project release\nprocess. General items like release notes, version files, reviews,\ntests, and cutting distribution tarballs are not specific to git.git\nnor git. For git.git, these items better belong in MaintNotes and the\nrelease checklist.txt (as they do) rather than this user distributed\nman page.\n\n> - push the tag and master branch alone to the public server---this\n> triggers an autobuilder for documentation pages, updates man and\n> html branches and documentation tarballs;\n\nI think it makes sense to include some verbiage around the push\naspect, as it is part of the distributed nature of git. I'll add this.\nThe autobuilder is not git specific so should be excluded via the\nlogic above -- except perhaps the hook part, which I could mention in\ngeneral terms when discussing the push e.g.\n\n\"You may decide to use a hook script on the public repository to\ninitiate release-related items such as building documentation.\"\n\n> When making a maintenance release, everything is the same except that\n> 'maint' is used instead of 'master'.\n\nGood point -- I will add a section about maintenance releases.\n\n> Then, after all the release task on 'master' (or 'maint') is done,\n> propagate that upwards (i.e. merge 'master' to 'next' and 'pu').\n\nWill add this.\n\n> Merging 'master' to 'maint' is done totally as a separate step, often a\n> few days later, \"Now the big release is done, let's start maintenance\n> track for that relase\".\n> \n> And then after that, 'next' may be rebuilt.\n\nOk, I'll change the order/wording accordingly.\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> There is no incorrect information here, but I do not think there is\n> anything particularly worth saying here, either. It is in \"git tag\"\n> manpage and anybody can run \"git cat-file tag v1.6.3\" to learn what is in\n> there.\n\nThe intention of this is not to illustrate the \"git tag\" syntax but\nrather so that the user understands the tag description and naming\nconventions used by git.git -- this prompts them mentally to consider\ndefining conventions for their project. Therefore, I'd like to keep this.\n\n>> +Maintenance branch update\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~\n> \n> This section largely overlaps with Documentation/howto/maintain-git.txt; I\n> am starting to doubt if we even need a new section in the workflows\n> document. Perhaps we could have a release management section in the\n> Documentation/howto/maintain-git.txt, though.\n\nBased on my comments and changes above, do you still have this doubt?\n Remember that the audience of a man page is not the git team -- it is\nusers. A new user to git who is considering developing branch\nprocesses and conventions around their git project will have access to\na man page such as gitworkflows but will not have (easy) access to\nmaintain-git.txt.\n\nThis is in fact why I decided to make this patch submission -- I found\ngitworkflows to be very helpful in creating a layout for my git\nprojects, but found that gitworkflows was missing any guidance as to\nwhat to do with my integration and topic branches when I needed to cut\na release. It was a while before I found maintain-git.txt, and most\nusers will never find it.\n\n>> +[caption=\"Recipe: \"]\n>> +=====================================\n>> +* `git checkout maint`\n>> +* `git merge master`\n>> +=====================================\n>> +\n>> +This updates 'maint' from 'master', while preserving the 'maint'\n>> +reflog.\n>> +\n>> +An alternative approach to updating the 'maint' branch is to run\n>> +\n>> + $ git branch -f maint master\n> \n> As I already said, I never do this \"alternative\", and I do not want\n> anybody who will take over git.git maintenance to do so. There is no\n> reason to encourage nor even mention \"branch -f\" here. As 'maint' is\n> supposed to be a strict subset, pulling 'master' to 'maint' should fast\n> forward and otherwise you (the maintainer) would notice that there was a\n> mistake made. If you use \"branch -f\", you will never notice.\n\nI know you do not do this alternative, however I added it as per our\nprevious discussion. I quote from\nhttp://article.gmane.org/gmane.comp.version-control.git/115183:\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> \n> Surely and thanks.\n\nI will try to make the reason why \"branch -f\" is not a good option\nmore clear. I'd like to keep this because many newbies coming from VCs\nlike subversion will default to taking the \"branch -f\" approach\nbecause that is conceptually closer to the way subversion works (I\nknow I did).\n\nThanks for your comments.\n\nCheers,\nRaman\n"},{"id":"127417","messageId":"7v639ggoer.fsf@alter.siamese.dyndns.org","threadId":"21569","inReplyTo":"4AFB57A3.2020002@fastmail.fm","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-11-12T08:03:56Z","receivedAt":"2009-11-12T08:03:56Z","isPatch":false,"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>> Is this meant to show how git.git does its release to serve as an\n>> inspiration to others? The document does not seem to describe how I make\n>> releases.\n>\n> Here is the existing intro to gitworkflows:\n>\n> ===================\n> This document attempts to write down and motivate some of the workflow\n> elements used for git.git itself. Many ideas apply in general, though\n> the full workflow is rarely required for smaller projects with fewer\n> people involved.\n>\n> We formulate a set of rules for quick reference, while the prose tries\n> to motivate each of them. Do not always take them literally; you\n> should value good reasons for your actions higher than manpages such\n> as this one.\n> ===================\n>\n> It is in this spirit that I am attempting to add to this document in\n> relation to the release process.\n\nThanks for reminding me of this.\n\nLet me address the second paragraph from the quoted part first. The\nexisting document is structured as a quick reference. Rules and recipes,\nwith supporting prose to explain them (I do not think \"motivate\" is a good\nway to phrase it, though).\n\nI am not very fond of documents with that style, but that does not mean\nnobody should work on nor we should ship such a document. It just means I\nwould not be a very good judge for one, and major parts of my response \nunfortunately came from my bias against such a document.\n\nWhat the first paragraph says is also important. We will talk about the\nworkflow elements we actually use here. Every description of a workflow\nelement should be read as if we said \"this is what we use and it has\nworked well for us; we recommend you to imitate it.\" after it. Limiting\nthe recommendation to what we practice ourselves and what worked well for\nus keeps the document honest.\n\nIn that light, after I re-read your patch and my comments, I think I\nshould rescind large part of my comments on your \"Release Tagging\" section\nand \"Maintenance branch update\" section. They are mostly good as-is, and\nthey are in line with the goal of the document stated at the beginning.\nThey describe the workflow elements actually used in git.git in a\nquick-reference format.\n\n>>> +RELEASE WORKFLOW\n>>> +----------------\n>>> +\n>>> +The maintainer may use the following release workflow:\n>> \n>> Please set the tone straight. If this is to suggest various possible\n>> workflows in general vague terms, \"may use\" would be good. ...\n>\n> Ok. The current document is inconsistent. In places it uses \"the\n> maintainer\" and in other places it uses \"you\". In any case, it seems\n> that the \"maintainer\" here is not \"Junio Hamano\" -- rather, it is the\n> reader.\n\nI wasn't talking about the difference between these two (Junio vs you).\nThat is not the issue. I was contrasting between\n\n - You _may_ choose to do A for release management as the maintainer, or\n do B or do C as alternatives.\n\nand\n\n - In managing git.git, its maintainer _does_ A when making a release.\n\nAs we are writing down what we practice, aka \"workflow elements used for\ngit.git itself\", in my comment I was hoping the latter was what you were\nwriting. Of course we could say\n\n - In managing git.git, its maintainer _does_ A when making a release.\n It is conceivable we _could_ also do B or C instead, but we do not\n recommend them.\n\nbut I think we are better off without such an addition.\n\nAn anti-recommendation against B and C like that does not carry the same\nweight as our positive recommendation for A, which is backed by our actual\nexperience.\n\n\"In the past, we tried B but it did not work well for us for such and such\nreasons, so we don't recommend you to use B\" would be justifiable, and\nthat is what I mean by \"keeping the document honest by limiting the\ndescription to what we use\".\n\nBut if this document is meant to be a quick reference, such\nanti-recommendation should be kept to minimum for the sake of\n\"quick\"-ness.\n\nAlso I agree with you that ...\n\n>> \t- review RelNotes symlink, Documentation/RelNotes-X.Y.Z.txt,\n>> the stalenotes section in Documentation/git.git, and\n>> GIT-VERSION-GEN for the last time;\n>> - tag it;\n>> - review it again for the last time;\n>> \t- test on buildfarm;\n>> \t- cut tarball;\n>> - cut RPM on FC11 i386 and FC11 x86_64;\n\nthese (except \"tag it\") can safely omitted to keep the document focused on\n\"revision control\" aspect of the system.\n\n> The autobuilder is not git specific so should be excluded via the logic\n> above -- except perhaps the hook part, which I could mention in general\n> terms when discussing the push e.g.\n>\n> \"You may decide to use a hook script on the public repository to\n> initiate release-related items such as building documentation.\"\n\nAgain, if we are going to recommend it, we should say \"We use post-update\nhook in _this_ way\", not \"You may do ...\".\n\nA major difference is that we describe what has worked for us and exactly\nhow, as opposed to giving suggestions that we ourselves haven't even used\nbut suspect it might work in a hand-wavy way.\n\n>>> +Maintenance branch update\n>>> +~~~~~~~~~~~~~~~~~~~~~~~~~\n>> ...\n>>> +An alternative approach to updating the 'maint' branch is to run\n>>> +\n>>> + $ git branch -f maint master\n>> \n>> As I already said, I never do this \"alternative\", and I do not want\n>> ...\n>> mistake made. If you use \"branch -f\", you will never notice.\n>\n> I know you do not do this alternative, however ...\n\nGiven the stated goal of the document of showing what we actually do and\nwhat we know have worked well for us, I do not think we would want it\nmentioned as a valid alternative.\n\n> previous discussion. I quote from\n> http://article.gmane.org/gmane.comp.version-control.git/115183:\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\nExplanation of the difference would have sounded like:\n\n We do not use \"branch -f maint master\" here; it is different from\n merging master into maint in such and such way and using \"branch -f\"\n for this purpose only has downsides.\n\nBut is it really worth mentioning random approaches that novices might\nthink of as alternatives and then refuting every one of them? Should we\nalso say \"don't do 'checkout maint && reset --hard master'\"? Should we\nsay \"'push . master:maint' would work equally well but don't add --force\nto that command line\"?\n\nThe document is an overview of recommended workflows. If we have one best\ncurrent practice for a task, just describing it without covering other\ninferiour (or equivalent but not superiour) alternatives to clutter the\ntext would be better for such a \"quick reference\" document, I think.\n"},{"id":"127420","messageId":"200911120910.57091.trast@student.ethz.ch","threadId":"21569","inReplyTo":"4AFB57A3.2020002@fastmail.fm","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2009-11-12T08:10:55Z","receivedAt":"2009-11-12T08:10:55Z","isPatch":false,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Raman Gupta wrote:\n> Junio C Hamano wrote:\n> > Please set the tone straight. If this is to suggest various possible\n> > workflows in general vague terms, \"may use\" would be good. If this is to\n> > precisely describe what I do, then there won't be \"you could do this, or\n> > you could do that.\" Your \"may use\" suggests the former, but the commit\n> > log message claims the latter. Which document are you writing?\n> \n> Ok. The current document is inconsistent. In places it uses \"the\n> maintainer\" and in other places it uses \"you\". In any case, it seems\n> that the \"maintainer\" here is not \"Junio Hamano\" -- rather, it is the\n> reader.\n> \n> Let me create a separate (and first) cleanup patch to fix the existing\n> inconsistencies in this man page. I would prefer to use the pronoun\n> \"you\" consistently as also suggested by Thomas Rast.\n\nWell, I'm not sure if this is also in reply to my comment\n\n} The current gitworkflows is mostly formulated in the imperative, [...]\n} or by directly describing the tools in the third person, [...]\n\nbut note that I do not consider the current form to be inconsistent\n(though you may of course convince me otherwise). It addresses the\npresumed user with \"you\", which is not always the maintainer. For\nexample, when talking about patch submission we have\n\n If the maintainer tells you that your patch no longer applies to the\n current upstream, you will have to rebase your topic (you cannot use a\n merge because you cannot format-patch merges):\n\nsince the presumed user of a patch-submission workflow is a\ncontributor, not the maintainer. Indeed much of the text talks\n*about* the workflow used by our esteemed maintainer, but is addressed\nto a contributor who wants to understand how it works so he can\nparticipate.\n\nIOW, I'm neither a native speaker nor a professional writer, so you\nmay of course convince me that there is something to fix. I am,\nhowever, fairly sure that s/maintainer/you/ and then fixing the\ngrammar is *not* a good thing.\n\n[BTW, it would have been nice to get a Cc to begin with, since the\nentire manpage blames to me. I noticed the thread anyway, but other\ntimes I do not have the time to scan the entire list.]\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"127421","messageId":"200911120927.16764.trast@student.ethz.ch","threadId":"21569","inReplyTo":"1257869339-15999-2-git-send-email-rocketraman@fastmail.fm","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2009-11-12T08:27:13Z","receivedAt":"2009-11-12T08:27:13Z","isPatch":false,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Here's my promised review of the whole patch. Much of the text fits\nmy understanding of what's actually going on, but Junio will have the\nfinal word on what he actually does (or what a sensible simplification\nmight be).\n\nrocketraman@fastmail.fm wrote:\n> +The current maintenance branch is optionally copied to another branch\n> +named with the older release version number (e.g. maint-X.Y.(Z-1)\n> +where X.Y.Z is the previous release). This allows for further\n> +maintenance releases on the older codebase.\n\nThe use of Z-1 confused me; I guess by \"previous release\" you mean\n\"the release we just tagged in the last step\". Otherwise the maint\nversion number would come out wrong.\n\n> +.Update maint to new release\n> +[caption=\"Recipe: \"]\n> +=====================================\n> +* `git checkout maint`\n> +* `git merge master`\n> +=====================================\n> +\n> +This updates 'maint' from 'master', while preserving the 'maint'\n> +reflog.\n\nI agree with what Junio said in the other mail: it's important at this\npoint that this was a fast-forward. (If it's not, master could be\nmissing some fixes made on maint.)\n\n> +An alternative approach to updating the 'maint' branch is to run\n> +\n> + $ git branch -f maint master\n\nIn my book the alternative approach is\n\n git branch -m maint maint-X.Y.(Z-1)\n git branch maint master\n\nI'd rather not teach users to play with loaded guns, much less in a\n\"good examples of workflows\" manpage.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"127458","messageId":"4AFC3DDE.7000202@fastmail.fm","threadId":"21569","inReplyTo":"200911120910.57091.trast@student.ethz.ch","subject":"Re: [PATCHv2] Update gitworkflows man page to include release workflow","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-12T16:54:54Z","receivedAt":"2009-11-12T16:54:54Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Thomas Rast wrote:\n> Raman Gupta wrote:\n>> Junio C Hamano wrote:\n>>> Please set the tone straight. If this is to suggest various possible\n>>> workflows in general vague terms, \"may use\" would be good. If this is to\n>>> precisely describe what I do, then there won't be \"you could do this, or\n>>> you could do that.\" Your \"may use\" suggests the former, but the commit\n>>> log message claims the latter. Which document are you writing?\n>> Ok. The current document is inconsistent. In places it uses \"the\n>> maintainer\" and in other places it uses \"you\". In any case, it seems\n>> that the \"maintainer\" here is not \"Junio Hamano\" -- rather, it is the\n>> reader.\n>>\n>> Let me create a separate (and first) cleanup patch to fix the existing\n>> inconsistencies in this man page. I would prefer to use the pronoun\n>> \"you\" consistently as also suggested by Thomas Rast.\n> \n> Well, I'm not sure if this is also in reply to my comment\n\nIt was mostly, yes.\n\n> } The current gitworkflows is mostly formulated in the imperative, [...]\n> } or by directly describing the tools in the third person, [...]\n> \n> but note that I do not consider the current form to be inconsistent\n> (though you may of course convince me otherwise). It addresses the\n> presumed user with \"you\", which is not always the maintainer. For\n> example, when talking about patch submission we have\n\nYou're right, upon re-reading the original man page I realized it is\nconsistent.\n\nThanks,\nRaman\n"}]}