[PATCHv2] Update gitworkflows man page to include release workflow
From: Raman Gupta <raman@rocketraman.com>
The gitworkflows man page currently provides an overview of the workflows
used by git.git itself to serve as inspiration for people to use when
designing their own workflows. The current man page does a reasonable
job at describing the development process, but it does not contain any
guidance as to the workflow used for releases. Now add a basic
introduction to the branch management required for a release, so that a
reader may understand how the maint, master, next, and topic branches are
affected.
---
Documentation/gitworkflows.txt | 97 ++++++++++++++++++++++++++++++++++++++++
1 files changed, 97 insertions(+), 0 deletions(-)
diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index 2b021e3..69b789a 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -348,6 +348,103 @@ in patches to figure out the merge base. See linkgit:git-am[1] for
other options.
+RELEASE WORKFLOW
+----------------
+
+The maintainer may use the following release workflow:
+
+He first tags the tip of 'master' with a release tag, then he updates
+the 'maint' branch to the current tip of 'master' for managing future
+maintenance fixes on the current release, and lastly he optionally
+rebuilds 'next' from the tip of 'master'.
+
+
+Release Tagging
+~~~~~~~~~~~~~~~
+
+The new feature release is tagged on 'master' with a tag matching
+vX.Y.Z, where X.Y.Z is the new feature release version.
+
+.Release tagging
+[caption="Recipe: "]
+=====================================
+`git tag -s -m "GIT X.Y.Z" vX.Y.Z master`
+=====================================
+
+
+Maintenance branch update
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Maintenance fixes for the current feature release are tracked on the
+'maint' branch.
+
+
+In order to track maintenance
+fixes to the current release, the maintainer uses a branch called
+'maint'.
+
+
+The current maintenance branch is optionally copied to another branch
+named with the older release version number (e.g. maint-X.Y.(Z-1)
+where X.Y.Z is the previous release). This allows for further
+maintenance releases on the older codebase.
+
+If the current tip of 'maint' corresponds to the previous release
+tag (i.e. that there are no fixes already pending on 'maint' that are
+intended for a maintenance release on the older codebase), then
+creating the 'maint' branch for the older codebase can also be done
+later, if it is needed.
+
+.Copy maint
+[caption="Recipe: "]
+=====================================
+`git branch maint-X.Y.(Z-1) maint`
+=====================================
+
+'maint' should now updated to the new release code so that maintenance
+fixes can be merged for the current version:
+
+.Update maint to new release
+[caption="Recipe: "]
+=====================================
+* `git checkout maint`
+* `git merge master`
+=====================================
+
+This updates 'maint' from 'master', while preserving the 'maint'
+reflog.
+
+An alternative approach to updating the 'maint' branch is to run
+
+ $ git branch -f maint master
+
+This will create a new 'maint' branch based on 'master'. If 'maint'
+already exists, it will be deleted before the new branch is created.
+Any commits on 'maint' that were not previously merged to master will
+therefore be lost and the 'maint' reflog will be reset. However, the
+branch history is "clean" and may be easier to understand.
+
+
+Update next branch
+~~~~~~~~~~~~~~~~~~
+
+The 'next' branch may be rewound and rebuilt from the tip of 'master'
+using the surviving topics on 'next'.
+
+This step is optional. If it is done by the maintainer, then a public
+announcement will be made indicating that 'next' was rewound and
+rebuilt.
+
+.Update maint to new release
+[caption="Recipe: "]
+=====================================
+* `git branch -f next master`
+* `git merge ai/topic_in_next1`
+* `git merge ai/topic_in_next2`
+* ...
+=====================================
+
+
SEE ALSO
--------
linkgit:gittutorial[7],
--
1.6.2