{"thread":{"id":"21594","subject":"Add branch management for releases to gitworkflows","startedAt":"2009-11-12T19:46:03Z","lastAt":"2009-11-19T04:11:47Z","messageCount":16,"participants":["rocketraman@fastmail.fm","skillzero@gmail.com","Raman Gupta","Nanako Shiraishi","Björn Gustavsson","Junio C Hamano","Thomas Rast"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"127466","messageId":"1258055164-11876-1-git-send-email-rocketraman@fastmail.fm","threadId":"21594","inReplyTo":null,"subject":"Add branch management for releases to gitworkflows","fromName":"","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-12T19:46:03Z","receivedAt":"2009-11-12T19:46:03Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"\nVersion 3 of the gitworkflows patch follows.\n\nThis version of the patch attempts to incorporate all feedback received from Junio and Thomas. The main changes are:\n\n1) Consistent use of pronouns in the imperative.\n\n2) Reorganization to move the new text into the \"MANAGING BRANCHES\" section. This wasn't explicitly suggested by Junio or Thomas, but it makes sense as it clarifies that the content is not about releases in general, but how releases affect the branch structure previously described in the document.\n\n3) Largely modified and reworded text, to conform to the new reorganization and to include feedback from Junio and Thomas.\n\nCheers,\nRaman\n"},{"id":"127467","messageId":"1258055164-11876-2-git-send-email-rocketraman@fastmail.fm","threadId":"21594","inReplyTo":"1258055164-11876-1-git-send-email-rocketraman@fastmail.fm","subject":"[PATCHv3] Add branch management for releases to gitworkflows","fromName":"","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-12T19:46:04Z","receivedAt":"2009-11-12T19:46:04Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"From: Raman Gupta <raman@rocketraman.com>\n\nThe current man page does a reasonable job at describing branch management\nduring the development process, but it does not contain any guidance as to\nhow the branches are affected by releases.\n\nAdd a basic introduction to the branch management undertaken during a\ngit.git release, so that a reader may gain some insight into how the\nintegration, maintenance, and topic branches are affected during the\nrelease transition, and is thus able to better design the process for their\nown project.\n\nOther release activities such as reviews, testing, and creating\ndistributions are currently out of scope.\n---\n Documentation/gitworkflows.txt |  108 ++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 108 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 2b021e3..7000930 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -209,6 +209,114 @@ chance to see if their in-progress work will be compatible.  `git.git`\n has such an official throw-away integration branch called 'pu'.\n \n \n+Branch management for a release\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Assuming you are using the merge approach discussed above, when you\n+are releasing your project you will need to do some additional branch\n+management work.\n+\n+Creating a release is easy. Since 'master' is tracking the commits\n+that should go into the next feature release, simply tag the tip of\n+'master' with a tag indicating the 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+Similarly, for a maintenance release, 'maint' is tracking the commits\n+to be released. Therefore, simply replace 'master' above with\n+'maint'.\n+\n+Generally, you should push the new tag to a public git server (see\n+\"DISTRIBUTED WORKFLOWS\" below). This push makes the tag available to\n+others tracking your project. The push could also trigger a\n+post-update hook to perform release-related items such as building\n+documentation.\n+\n+\n+Maintenance branch management after a feature release\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+After a feature release, you need to manage your maintenance branches.\n+\n+First, if you wish to continue to release maintenance fixes for the\n+feature release made before the recent one, then you must create\n+another branch to track commits for that previous release.\n+\n+To do this, the current maintenance branch is copied to another branch\n+named with the previous release version number (e.g. maint-X.Y.(Z-1)\n+where X.Y.Z is the current release).\n+\n+.Copy maint\n+[caption=\"Recipe: \"]\n+=====================================\n+`git branch maint-X.Y.(Z-1) maint`\n+=====================================\n+\n+The 'maint' branch should now be fast forwarded to the newly released\n+code so that maintenance fixes can be tracked for the current release:\n+\n+.Update maint to new release\n+[caption=\"Recipe: \"]\n+=====================================\n+* `git checkout maint`\n+* `git merge master`\n+=====================================\n+\n+This 'should' fast forward 'maint' from 'master'. If it is not a fast\n+forward, then 'maint' contained some commits that were not included on\n+'master', which means that the recent feature release could be missing\n+some fixes made on 'maint'. The exception is if there were any commits\n+that were cherry-picked to 'maint' as described above in \"Merging\n+upwards\". In this case, the merge will not be a fast forward.\n+\n+An alternative approach to updating the 'maint' branch, though one\n+not used in git.git, is to rename the current 'maint' branch to track\n+maintenance fixes for the older release and then to recreate 'maint'\n+from 'master':\n+\n+  $ git branch -m maint maint-X.Y.(Z-1)\n+  $ git branch maint master\n+\n+The latter step will create a new 'maint' branch based on 'master'. If\n+commits were cherry-picked to 'maint', then this will create a new\n+'maint' branch without a merge commit.\n+\n+\n+Branch management for next and pu after a feature release\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+After a feature release, the 'next' testing branch may optionally be\n+rewound and rebuilt from the tip of 'master' using the surviving\n+topics on 'next':\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+The advantage of doing this is that the history of 'next' will be\n+clean. For example, some topics merged into 'next' may have initially\n+looked promising, but were later found to be undesirable or premature.\n+In such a case, the topic is reverted out of 'next' but the fact\n+remains in the history that it was once merged and reverted. By\n+recreating 'next', you give another incarnation of such topics a clean\n+slate to retry, and a feature release is a good point in history to do\n+so.\n+\n+If you do this, then you should make a public announcement indicating\n+that 'next' was rewound and rebuilt.\n+\n+The same process may be followed for 'pu'.\n+\n+\n DISTRIBUTED WORKFLOWS\n ---------------------\n \n-- \n1.6.2\n"},{"id":"127470","messageId":"2729632a0911121208r1f51cf9ewb0bc23e757275f30@mail.gmail.com","threadId":"21594","inReplyTo":"1258055164-11876-2-git-send-email-rocketraman@fastmail.fm","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"","fromEmail":"skillzero@gmail.com","sentAt":"2009-11-12T20:08:14Z","receivedAt":"2009-11-12T20:08:14Z","isPatch":false,"sender":{"key":"skillzero@gmail.com","avatar":null},"body":"> +.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\nShouldn't that be something like \"Update next to new release\" instead\nof \"maint\"?\n\nShould it also have 'git checkout next' after the branch command so\nit's on next before merging?\n"},{"id":"127472","messageId":"4AFC7069.1020701@fastmail.fm","threadId":"21594","inReplyTo":"2729632a0911121208r1f51cf9ewb0bc23e757275f30@mail.gmail.com","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-12T20:30:33Z","receivedAt":"2009-11-12T20:30:33Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"skillzero@gmail.com wrote:\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> Shouldn't that be something like \"Update next to new release\" instead\n> of \"maint\"?\n\nOops. I changed the caption to \"Rewind and rebuild next\".\n\n> Should it also have 'git checkout next' after the branch command so\n> it's on next before merging?\n\nRight, fixed also.\n\nThanks,\nRaman\n"},{"id":"127521","messageId":"20091114071946.6117@nanako3.lavabit.com","threadId":"21594","inReplyTo":"1258055164-11876-2-git-send-email-rocketraman@fastmail.fm","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-11-13T22:19:46Z","receivedAt":"2009-11-13T22:19:46Z","isPatch":false,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting rocketraman@fastmail.fm\n\n> From: Raman Gupta <raman@rocketraman.com>\n>\n> The current man page does a reasonable job at describing branch management\n> during the development process, but it does not contain any guidance as to\n> how the branches are affected by releases.\n>\n> Add a basic introduction to the branch management undertaken during a\n> git.git release, so that a reader may gain some insight into how the\n> integration, maintenance, and topic branches are affected during the\n> release transition, and is thus able to better design the process for their\n> own project.\n>\n> Other release activities such as reviews, testing, and creating\n> distributions are currently out of scope.\n> ---\n\nYou are missing Signed-off-by: line. \n\nHere are some corrections that can be applied on top of your change.\n\n-- >8 --\nSubject: [PATCH] Corrections to release management section in gitworkflows.txt\n\nThe maintenance branch is supposed to be a strict subset of the master\nbranch at all times. If you find out that this condition was violated\nafter you pushed a release from the master branch, it is too late.\nCorrecting that mistake will require redoing and retagging an already\npublished release.\n\nIn http://article.gmane.org/gmane.comp.version-control.git/132692, Junio\nexplained that the first step is:\n\n        - doubly make sure that there is nothing left in 'maint' that\n          is not in 'master';\n\nto avoid that mistake.  Explain the exact procedure in a recipe format,\nand make sure it is done before the tip of the master branch is tagged.\nAlso use --ff-only when merging master into maint.\n\nRebuilding of 'next' must be done on 'next' branch; correct the\ncommand sequence in the recipe.\n\nOther minor clarifications in the text are also included in this change:\n\n * Clarify \"building documentation\" a bit; the post-update hook\n   creates preformatted documentation pages.\n\n * The latest documentation set uses \"fast-forward\", not \"fast\n   forward\".\n\n * Call 'next' branch an integration branch, not a \"testing\" branch, to be\n   consistent with the Graduation section.\n\nSigned-off-by: Nanako Shiraishi <nanako3@lavabit.com>\n---\n Documentation/gitworkflows.txt |   57 +++++++++++++++++++++------------------\n 1 files changed, 31 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 7000930..b1c7ef3 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -216,8 +216,19 @@ Assuming you are using the merge approach discussed above, when you\n are releasing your project you will need to do some additional branch\n management work.\n \n-Creating a release is easy. Since 'master' is tracking the commits\n-that should go into the next feature release, simply tag the tip of\n+Since 'master' is supposed to be always a superset of 'maint', you\n+should first make sure that condition holds.\n+\n+.Make sure 'maint' fast-forwards to 'master'\n+[caption=\"Recipe: \"]\n+=====================================\n+git log master..maint\n+=====================================\n+\n+There should be no commit listed from this command (otherwise, check\n+out 'master' and merge 'maint' into it).\n+\n+Then you can tag the tip of\n 'master' with a tag indicating the release version.\n \n .Release tagging\n@@ -230,11 +241,15 @@ Similarly, for a maintenance release, 'maint' is tracking the commits\n to be released. Therefore, simply replace 'master' above with\n 'maint'.\n \n-Generally, you should push the new tag to a public git server (see\n+You need to push the new tag to a public git server,\n+at the same time you push the updated 'master' or 'maint',\n+if you are making a maintenance release. (see\n \"DISTRIBUTED WORKFLOWS\" below). This push makes the tag available to\n others tracking your project. The push could also trigger a\n post-update hook to perform release-related items such as building\n-documentation.\n+release tarballs and preformatted documentation pages.  You may want\n+to wait this push-out before you update your 'maint' branch (see the\n+next section).\n \n \n Maintenance branch management after a feature release\n@@ -256,47 +271,37 @@ where X.Y.Z is the current release).\n `git branch maint-X.Y.(Z-1) maint`\n =====================================\n \n-The 'maint' branch should now be fast forwarded to the newly released\n+The 'maint' branch should now be fast-forwarded to the newly released\n code so that maintenance fixes can be tracked for the current release:\n \n .Update maint to new release\n [caption=\"Recipe: \"]\n =====================================\n-* `git checkout maint`\n-* `git merge master`\n+* `git checkout maint`\n+* `git merge --ff-only master`\n =====================================\n \n-This 'should' fast forward 'maint' from 'master'. If it is not a fast\n-forward, then 'maint' contained some commits that were not included on\n+This should fast-forward 'maint' from 'master'. If it is not a\n+fast-forward, then 'maint' contained some commits that were not included on\n 'master', which means that the recent feature release could be missing\n-some fixes made on 'maint'. The exception is if there were any commits\n-that were cherry-picked to 'maint' as described above in \"Merging\n-upwards\". In this case, the merge will not be a fast forward.\n-\n-An alternative approach to updating the 'maint' branch, though one\n-not used in git.git, is to rename the current 'maint' branch to track\n-maintenance fixes for the older release and then to recreate 'maint'\n-from 'master':\n-\n-  $ git branch -m maint maint-X.Y.(Z-1)\n-  $ git branch maint master\n-\n-The latter step will create a new 'maint' branch based on 'master'. If\n-commits were cherry-picked to 'maint', then this will create a new\n-'maint' branch without a merge commit.\n+some fixes made on 'maint'.  If that happens, you need to go back to the\n+previous \"Branch management for a release\" step.  Correcting this mistake\n+becomes messy if you have already pushed the release tag, and that is why\n+you should wait until finishing this step before pushing the release out.\n \n \n Branch management for next and pu after a feature release\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n-After a feature release, the 'next' testing branch may optionally be\n+After a feature release, the integration branch 'next' may optionally be\n rewound and rebuilt from the tip of 'master' using the surviving\n topics on 'next':\n \n .Update maint to new release\n [caption=\"Recipe: \"]\n =====================================\n-* `git branch -f next master`\n+* `git checkout next`\n+* `git reset --hard master`\n * `git merge ai/topic_in_next1`\n * `git merge ai/topic_in_next2`\n * ...\n-- \n1.6.5.2.159.g67ee8\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"},{"id":"127522","messageId":"4AFDE421.5050307@fastmail.fm","threadId":"21594","inReplyTo":"20091114071946.6117@nanako3.lavabit.com","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-13T22:56:33Z","receivedAt":"2009-11-13T22:56:33Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Nanako Shiraishi wrote:\n>  .Update maint to new release\n>  [caption=\"Recipe: \"]\n>  =====================================\n> -* `git checkout maint`\n> -* `git merge master`\n> +* `git checkout maint`\n> +* `git merge --ff-only master`\n>  =====================================\n>  \n> -This 'should' fast forward 'maint' from 'master'. If it is not a fast\n> -forward, then 'maint' contained some commits that were not included on\n> +This should fast-forward 'maint' from 'master'. If it is not a\n> +fast-forward, then 'maint' contained some commits that were not included on\n>  'master', which means that the recent feature release could be missing\n> -some fixes made on 'maint'. The exception is if there were any commits\n> -that were cherry-picked to 'maint' as described above in \"Merging\n> -upwards\". In this case, the merge will not be a fast forward.\n\nI noticed you removed the discussion I added about the situation in\nwhich maint will *not* be a subset of master i.e. when the user has\ncherry-picked commits from other branches. This type of cherry-pick is\ndescribed as a valid operation, though one to generally be avoided\nearlier in the man page. If we tell users that the occasional\ncherry-pick to maint is ok, then shouldn't we explain how that affects\nthe release process?\n\nCheers,\nRaman\n"},{"id":"127524","messageId":"20091114081040.6117@nanako3.lavabit.com","threadId":"21594","inReplyTo":"4AFDE421.5050307@fastmail.fm","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-11-13T23:10:40Z","receivedAt":"2009-11-13T23:10:40Z","isPatch":false,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting Raman Gupta <rocketraman@fastmail.fm>\n\n> Nanako Shiraishi wrote:\n>>  .Update maint to new release\n>>  [caption=\"Recipe: \"]\n>>  =====================================\n>> -* `git checkout maint`\n>> -* `git merge master`\n>> +* `git checkout maint`\n>> +* `git merge --ff-only master`\n>>  =====================================\n>>  \n>> -This 'should' fast forward 'maint' from 'master'. If it is not a fast\n>> -forward, then 'maint' contained some commits that were not included on\n>> +This should fast-forward 'maint' from 'master'. If it is not a\n>> +fast-forward, then 'maint' contained some commits that were not included on\n>>  'master', which means that the recent feature release could be missing\n>> -some fixes made on 'maint'. The exception is if there were any commits\n>> -that were cherry-picked to 'maint' as described above in \"Merging\n>> -upwards\". In this case, the merge will not be a fast forward.\n>\n> I noticed you removed the discussion I added about the situation in\n> which maint will *not* be a subset of master i.e. when the user has\n> cherry-picked commits from other branches. This type of cherry-pick is\n> described as a valid operation, though one to generally be avoided\n> earlier in the man page. If we tell users that the occasional\n> cherry-pick to maint is ok, then shouldn't we explain how that affects\n> the release process?\n\nIt is irrelevant that you can cherry-pick to 'maint'.\n\nYou can, and Junio does, cherry-pick some commits from master to \nmaint from time to time. But even if you have such cherry-picked \ncommits on the maintenance branch, the result, with zero or more \nother maintenance commits on top, is always merged back to the \nmaster branch (you can look at \"gitk origin/maint origin/master\" \nto see yourself).\n\nSo when Junio tags the release from the tip of the master branch, \nit is a superset of the maintenace branch; it is irrelevant if \nmaint has some commits that are cherry-picked from master.\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"},{"id":"127534","messageId":"4AFE41AF.8050802@fastmail.fm","threadId":"21594","inReplyTo":"20091114081040.6117@nanako3.lavabit.com","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-14T05:35:43Z","receivedAt":"2009-11-14T05:35:43Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Nanako Shiraishi wrote:\n> Quoting Raman Gupta <rocketraman@fastmail.fm>\n>> I noticed you removed the discussion I added about the situation in\n>> which maint will *not* be a subset of master i.e. when the user has\n>> cherry-picked commits from other branches. This type of cherry-pick is\n>> described as a valid operation, though one to generally be avoided\n>> earlier in the man page. If we tell users that the occasional\n>> cherry-pick to maint is ok, then shouldn't we explain how that affects\n>> the release process?\n> \n> It is irrelevant that you can cherry-pick to 'maint'.\n> \n> You can, and Junio does, cherry-pick some commits from master to \n> maint from time to time. But even if you have such cherry-picked \n> commits on the maintenance branch, the result, with zero or more \n> other maintenance commits on top, is always merged back to the \n> master branch (you can look at \"gitk origin/maint origin/master\" \n> to see yourself).\n> \n> So when Junio tags the release from the tip of the master branch, \n> it is a superset of the maintenace branch; it is irrelevant if \n> maint has some commits that are cherry-picked from master.\n\nThanks for the explanation. Makes sense.\n\nOk, another dumb question: since you have now submitted a patch on top\nof my patch, what is the proper etiquette for proceeding? Who\nmaintains this patch series until it is committed? Since your patch\napplies on top of mine I can't really make any more changes without\naffecting your patch right? I can't find any guidance in the\nSubmittingPatches document.\n\nCheers,\nRaman\n"},{"id":"127537","messageId":"6672d0160911140059r78dda7bbvbd3cc67828dc4322@mail.gmail.com","threadId":"21594","inReplyTo":"4AFE41AF.8050802@fastmail.fm","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Björn Gustavsson","fromEmail":"bgustavsson@gmail.com","sentAt":"2009-11-14T08:59:44Z","receivedAt":"2009-11-14T08:59:44Z","isPatch":false,"sender":{"key":"bgustavsson@gmail.com","avatar":"https://avatars.githubusercontent.com/u/74840?v=4"},"body":"On Sat, Nov 14, 2009 at 6:35 AM, Raman Gupta <rocketraman@fastmail.fm> wrote:\n>\n> Ok, another dumb question: since you have now submitted a patch on top\n> of my patch, what is the proper etiquette for proceeding? Who\n> maintains this patch series until it is committed? Since your patch\n> applies on top of mine I can't really make any more changes without\n> affecting your patch right? I can't find any guidance in the\n> SubmittingPatches document.\n\nI can't answer the questions about proper etiquette, but you *can* do\nmore changes\nif you first apply Nanako's patch on top of your previous changes.\n\n/Björn\n-- \nBjörn Gustavsson, Erlang/OTP, Ericsson AB\n"},{"id":"127538","messageId":"20091114180123.6117@nanako3.lavabit.com","threadId":"21594","inReplyTo":"4AFE41AF.8050802@fastmail.fm","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-11-14T09:01:23Z","receivedAt":"2009-11-14T09:01:23Z","isPatch":false,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting Raman Gupta <rocketraman@fastmail.fm>\n\n> Ok, another dumb question: since you have now submitted a patch on top\n> of my patch, what is the proper etiquette for proceeding? Who\n> maintains this patch series until it is committed? Since your patch\n> applies on top of mine I can't really make any more changes without\n> affecting your patch right? I can't find any guidance in the\n> SubmittingPatches document.\n\nWhat usually happens is that we wait now.\n\nIn this case we are in agreement that it is a good idea to apply \nboth of our patches (mine was only repeating what Junio said in \nhis comments), so if I were you, I would anticipate that Junio \nwould apply both of them and start preparing incremental updates \non top of them now, and send them when the patches appear in his \n'pu' branch.\n\nJunio has gone quiet for the past few days; maybe he is too busy\nto read or respond to either of our patch. Instead of preparing \nthe final text you write in the document in a patch format, it \nmay be a better to bring up your ideas here and discuss them \nfirst. What changes do you have in mind? I think the new section \nnow already is in a reasonable shape.\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"},{"id":"127550","messageId":"4AFEE882.4030208@fastmail.fm","threadId":"21594","inReplyTo":"20091114180123.6117@nanako3.lavabit.com","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-14T17:27:30Z","receivedAt":"2009-11-14T17:27:30Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Nanako Shiraishi wrote:\n> Quoting Raman Gupta <rocketraman@fastmail.fm>\n> \n>> Ok, another dumb question: since you have now submitted a patch on top\n>> of my patch, what is the proper etiquette for proceeding? Who\n>> maintains this patch series until it is committed? Since your patch\n>> applies on top of mine I can't really make any more changes without\n>> affecting your patch right? I can't find any guidance in the\n>> SubmittingPatches document.\n> \n> What usually happens is that we wait now.\n> \n> In this case we are in agreement that it is a good idea to apply \n> both of our patches (mine was only repeating what Junio said in \n> his comments), so if I were you, I would anticipate that Junio \n> would apply both of them and start preparing incremental updates \n> on top of them now, and send them when the patches appear in his \n> 'pu' branch.\n> \n> Junio has gone quiet for the past few days; maybe he is too busy\n> to read or respond to either of our patch. Instead of preparing \n> the final text you write in the document in a patch format, it \n> may be a better to bring up your ideas here and discuss them \n> first. What changes do you have in mind? I think the new section \n> now already is in a reasonable shape.\n\nNo specific changes -- it was a hypothetical question...\n\nCheers,\nRaman\n"},{"id":"127596","messageId":"7vy6m8p2sy.fsf@alter.siamese.dyndns.org","threadId":"21594","inReplyTo":"20091114071946.6117@nanako3.lavabit.com","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-11-15T09:14:53Z","receivedAt":"2009-11-15T09:14:53Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nanako Shiraishi <nanako3@lavabit.com> writes:\n\n> Other minor clarifications in the text are also included in this change:\n>\n>  * Clarify \"building documentation\" a bit; the post-update hook\n>    creates preformatted documentation pages.\n>\n>  * The latest documentation set uses \"fast-forward\", not \"fast\n>    forward\".\n>\n>  * Call 'next' branch an integration branch, not a \"testing\" branch, to be\n>    consistent with the Graduation section.\n> ...\n> Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com>\n> ---\n\nYour changes look mostly fine.\n\nI obviously agree with the removal of \"use 'branch -f' to update maint\"\nwhich I said I do not want to see in the document number of times.\n\nThere is another thing; I didn't notice it in the earlier round but the\nway I actually rotate 'master', 'maint' and the 'maint-one-rev-old' is\nsimilar to how Thomas mentioned.  That is:\n\n================================\ngit checkout master\ngit log ..maint        ;# should see nothing\ngit tag ...            ;# release task\ngit checkout maint\ngit branch maint-X.Y.Z ;# without -f so that I can catch a typo to\n                          clobber what already exists\ngit merge --ff-only master\n================================\n\nMy fingers are trained to type \"git merge\" before --ff-only was invented,\nso I actually do use \"merge master\" without --ff-only option in the last\nstep, but if I see a real merge created with that command, I notice it and\ntreat it as a grave error, so in the Recipe we should say --ff-only.\n"},{"id":"127618","messageId":"200911151807.15726.trast@student.ethz.ch","threadId":"21594","inReplyTo":"20091114071946.6117@nanako3.lavabit.com","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2009-11-15T17:07:13Z","receivedAt":"2009-11-15T17:07:13Z","isPatch":false,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Nanako Shiraishi wrote:\n> Quoting rocketraman@fastmail.fm\n> > Add a basic introduction to the branch management undertaken during a\n> > git.git release\n[...]\n> Here are some corrections that can be applied on top of your change.\n\nAt the bottom there are some more corrections on top of your combined\npatches.  At this point I would prefer to squash everything into a\nsingle patch, but if you want to keep them separate I can come up with\na commit message.\n\nAll but the last change are just intended to \"sound nicer\".  Since I'm\nnot a native speaker either (I'm not sure any have commented in the\nthreads so far), it would probably be nice to get some additional\ncomments.\n\nAs for the last hunk, I felt it was misleading to state 'pu' uses the\nsame process as 'next' immediately after mentioning the \"next will be\nrewound shortly\" messages that Junio sends out.  Such a message is\nnever required for 'pu' because (as is already explained in the\nmanpage) the \"contract\" is that the maintainer may rewind it anytime\nhe likes.\n\nApart from that, I'm not entirely happy with the way the \"release\" and\n\"maint, after a feature release\" sections are tangled yet.  There are\nseveral forward and backward references between them.  I see that you\nare trying to drive home the point that maint needs to be contained in\nmaster.  Can't we just deal with that in the \"feature release\"\nsection?\n\n-- 8< --\ndiff --git i/Documentation/gitworkflows.txt w/Documentation/gitworkflows.txt\nindex 2a9329f..490346c 100644\n--- i/Documentation/gitworkflows.txt\n+++ w/Documentation/gitworkflows.txt\n@@ -225,8 +225,8 @@ should first make sure that condition holds.\n git log master..maint\n =====================================\n \n-There should be no commit listed from this command (otherwise, check\n-out 'master' and merge 'maint' into it).\n+This command should not list any commits.  Otherwise, check out\n+'master' and merge 'maint' into it.\n \n Then you can tag the tip of\n 'master' with a tag indicating the release version.\n@@ -241,15 +241,15 @@ Similarly, for a maintenance release, 'maint' is tracking the commits\n to be released. Therefore, simply replace 'master' above with\n 'maint'.\n \n-You need to push the new tag to a public git server,\n-at the same time you push the updated 'master' or 'maint',\n-if you are making a maintenance release. (see\n-\"DISTRIBUTED WORKFLOWS\" below). This push makes the tag available to\n+You need to push the new tag to a public git server\n+when you push the updated 'master' (or 'maint',\n+if you are making a maintenance release).  See\n+\"DISTRIBUTED WORKFLOWS\" below. This makes the tag available to\n others tracking your project. The push could also trigger a\n post-update hook to perform release-related items such as building\n release tarballs and preformatted documentation pages.  You may want\n-to wait this push-out before you update your 'maint' branch (see the\n-next section).\n+to defer the push until after you have updated your 'maint' branch\n+(see the next section).\n \n \n Maintenance branch management after a feature release\n@@ -319,8 +319,6 @@ so.\n If you do this, then you should make a public announcement indicating\n that 'next' was rewound and rebuilt.\n \n-The same process may be followed for 'pu'.\n-\n \n DISTRIBUTED WORKFLOWS\n ---------------------\n"},{"id":"127791","messageId":"4B033D8F.1080309@fastmail.fm","threadId":"21594","inReplyTo":"200911151807.15726.trast@student.ethz.ch","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Raman Gupta","fromEmail":"rocketraman@fastmail.fm","sentAt":"2009-11-18T00:19:27Z","receivedAt":"2009-11-18T00:19:27Z","isPatch":false,"sender":{"key":"rocketraman@fastmail.fm","avatar":null},"body":"Thomas Rast wrote:\n> Nanako Shiraishi wrote:\n>> Quoting rocketraman@fastmail.fm\n>>> Add a basic introduction to the branch management undertaken during a\n>>> git.git release\n> [...]\n>> Here are some corrections that can be applied on top of your change.\n\nOk. I am submitting another patch on top of yours and Nanako's with some additional explanation and guidance, as well as some rewording and reorganization. I also corrected an error that skillzero caught earlier.\n\nI think the basics of Junio's message re rotating 'master', 'maint', and 'maint-one-rev-old' are already in the document, so I haven't added anything explicit regarding that.\n\n> At the bottom there are some more corrections on top of your combined\n> patches.  At this point I would prefer to squash everything into a\n> single patch, but if you want to keep them separate I can come up with\n> a commit message.\n\nSquashing is fine with me.\n\n> All but the last change are just intended to \"sound nicer\".  Since I'm\n> not a native speaker either (I'm not sure any have commented in the\n> threads so far), it would probably be nice to get some additional\n> comments.\n\nI *am* a native English speaker. Sadly, its the *only* language I speak, read, and write. However, additional comments would definitely be nice.\n\n> As for the last hunk, I felt it was misleading to state 'pu' uses the\n> same process as 'next' immediately after mentioning the \"next will be\n> rewound shortly\" messages that Junio sends out.  Such a message is\n> never required for 'pu' because (as is already explained in the\n> manpage) the \"contract\" is that the maintainer may rewind it anytime\n> he likes.\n\nI added it back in with the additional explanation that the public announcement is not necessary. I think its important for a reader to understand how the 'pu' branch might be maintained. Besides, the title of the section includes pu, so some discussion around pu is warranted, or the title should change also.\n\n> Apart from that, I'm not entirely happy with the way the \"release\" and\n> \"maint, after a feature release\" sections are tangled yet.  There are\n> several forward and backward references between them.  I see that you\n> are trying to drive home the point that maint needs to be contained in\n> master.  Can't we just deal with that in the \"feature release\"\n> section?\n\nAgree. I reworded the sections to untangle the information somewhat. Let me know what you think.\n\n-- 8< --\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 490346c..91c0eea 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -216,10 +216,17 @@ Assuming you are using the merge approach discussed above, when you\n are releasing your project you will need to do some additional branch\n management work.\n \n-Since 'master' is supposed to be always a superset of 'maint', you\n-should first make sure that condition holds.\n+A feature release is created from the 'master' branch, since 'master'\n+tracks the commits that should go into the next feature release.\n \n-.Make sure 'maint' fast-forwards to 'master'\n+The 'master' branch is supposed to be a superset of 'maint'. If this\n+condition does not hold, then 'maint' contains some commits that\n+are not included on 'master'. The fixes represented by those commits\n+will therefore not be included in your feature release.\n+\n+To verify that 'master' is indeed a superset of 'maint', use git log:\n+\n+.Verify 'master' is a superset of 'maint'\n [caption=\"Recipe: \"]\n =====================================\n git log master..maint\n@@ -228,8 +235,8 @@ git log master..maint\n This command should not list any commits.  Otherwise, check out\n 'master' and merge 'maint' into it.\n \n-Then you can tag the tip of\n-'master' with a tag indicating the release version.\n+Now you can proceed with the creation of the feature release. Apply a\n+tag to the tip of 'master' indicating the release version:\n \n .Release tagging\n [caption=\"Recipe: \"]\n@@ -237,19 +244,15 @@ Then you can tag the tip of\n `git tag -s -m \"GIT X.Y.Z\" vX.Y.Z master`\n =====================================\n \n-Similarly, for a maintenance release, 'maint' is tracking the commits\n-to be released. Therefore, simply replace 'master' above with\n-'maint'.\n-\n-You need to push the new tag to a public git server\n-when you push the updated 'master' (or 'maint',\n-if you are making a maintenance release).  See\n-\"DISTRIBUTED WORKFLOWS\" below. This makes the tag available to\n+You need to push the new tag to a public git server (see\n+\"DISTRIBUTED WORKFLOWS\" below). This makes the tag available to\n others tracking your project. The push could also trigger a\n post-update hook to perform release-related items such as building\n-release tarballs and preformatted documentation pages.  You may want\n-to defer the push until after you have updated your 'maint' branch\n-(see the next section).\n+release tarballs and preformatted documentation pages.\n+\n+Similarly, for a maintenance release, 'maint' is tracking the commits\n+to be released. Therefore, in the steps above simply tag and push\n+'maint' rather than 'master'.\n \n \n Maintenance branch management after a feature release\n@@ -281,13 +284,10 @@ code so that maintenance fixes can be tracked for the current release:\n * `git merge --ff-only master`\n =====================================\n \n-This should fast-forward 'maint' from 'master'. If it is not a\n-fast-forward, then 'maint' contained some commits that were not included on\n-'master', which means that the recent feature release could be missing\n-some fixes made on 'maint'.  If that happens, you need to go back to the\n-previous \"Branch management for a release\" step.  Correcting this mistake\n-becomes messy if you have already pushed the release tag, and that is why\n-you should wait until finishing this step before pushing the release out.\n+If the merge fails because it is not a fast-forward, then it is\n+possible some fixes on 'maint' were missed in the feature release.\n+This will not happen if the content of the branches was verified as\n+described in the previous section.\n \n \n Branch management for next and pu after a feature release\n@@ -297,7 +297,7 @@ After a feature release, the integration branch 'next' may optionally be\n rewound and rebuilt from the tip of 'master' using the surviving\n topics on 'next':\n \n-.Update maint to new release\n+.Rewind and rebuild next\n [caption=\"Recipe: \"]\n =====================================\n * `git checkout next`\n@@ -319,6 +319,10 @@ so.\n If you do this, then you should make a public announcement indicating\n that 'next' was rewound and rebuilt.\n \n+The same rewind and rebuild process may be followed for 'pu'. A public\n+announcement is not necessary since 'pu' is a throw-away branch, as\n+described above.\n+\n \n DISTRIBUTED WORKFLOWS\n ---------------------\n-- \n1.6.2\n"},{"id":"127854","messageId":"200911181559.02873.trast@student.ethz.ch","threadId":"21594","inReplyTo":"4B033D8F.1080309@fastmail.fm","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2009-11-18T14:59:01Z","receivedAt":"2009-11-18T14:59:01Z","isPatch":false,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Raman Gupta wrote:\n> \n> I *am* a native English speaker. Sadly, its the *only* language I\n> speak, read, and write. However, additional comments would\n> definitely be nice.\n\nOh, my apologies.  I just looked at the names and jumped to\nconclusions from there.\n\n> Agree. I reworded the sections to untangle the information\n> somewhat. Let me know what you think.\n[...]\n>  * `git merge --ff-only master`\n>  =====================================\n>  \n[...]\n> +If the merge fails because it is not a fast-forward, then it is\n> +possible some fixes on 'maint' were missed in the feature release.\n> +This will not happen if the content of the branches was verified as\n> +described in the previous section.\n\nYes, I think that is nicer.  It's no longer a repetition of what was\nsaid above, but merely points out what could have gone wrong and where\nto look for advice.  The last sentence sounds a bit like \"ha ha we\ntold you so!\" though ;-)\n\nFWIW, you can add my\n\n  Acked-by: Thomas Rast <trast@student.ethz.ch>\n\nto the final (squashed) patch.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"127884","messageId":"20091119131147.6117@nanako3.lavabit.com","threadId":"21594","inReplyTo":"200911181559.02873.trast@student.ethz.ch","subject":"Re: [PATCHv3] Add branch management for releases to gitworkflows","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-11-19T04:11:47Z","receivedAt":"2009-11-19T04:11:47Z","isPatch":false,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting Thomas Rast <trast@student.ethz.ch> writes:\n\n> FWIW, you can add my\n>\n>   Acked-by: Thomas Rast <trast@student.ethz.ch>\n>\n> to the final (squashed) patch.\n\nJunio, please also add my\n\n   Acked-by: Nanako Shiraishi <nanako3@lavabit.com>\n\nMy changes were intended to be squashed into the final single patch, too.\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"}]}