Mailing-List: contact commits-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@commons.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: luc@apache.org
To: commits@commons.apache.org
Message-Id: <89af95f297cb4c048c38f7cd81f26919@git.apache.org>
Subject: [math] Updated release howto to not delete the release branch after
 release.
Date: Fri,  1 Jan 2016 13:18:09 +0000 (UTC)

Repository: commons-math
Updated Branches:
  refs/heads/master 3e5c248f7 -> 953c23242


Updated release howto to not delete the release branch after release.


Project: http://git-wip-us.apache.org/repos/asf/commons-math/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-math/commit/953c2324
Tree: http://git-wip-us.apache.org/repos/asf/commons-math/tree/953c2324
Diff: http://git-wip-us.apache.org/repos/asf/commons-math/diff/953c2324

Branch: refs/heads/master
Commit: 953c23242b0d84dd7802dbbc2c457b897d832537
Parents: 3e5c248
Author: Luc Maisonobe <luc@apache.org>
Authored: Fri Jan 1 14:17:54 2016 +0100
Committer: Luc Maisonobe <luc@apache.org>
Committed: Fri Jan 1 14:17:54 2016 +0100

----------------------------------------------------------------------
 doc/release/release.howto.txt | 100 ++++++++++++++-----------------------
 1 file changed, 37 insertions(+), 63 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/commons-math/blob/953c2324/doc/release/release.howto.txt
----------------------------------------------------------------------
diff --git a/doc/release/release.howto.txt b/doc/release/release.howto.txt
index dedfd9f..b620e55 100644
--- a/doc/release/release.howto.txt
+++ b/doc/release/release.howto.txt
@@ -25,38 +25,36 @@ of files used by maven to pick up authentication credentials needed to
 connect to remote servers and to cryptographically sign the artifacts.
 
 Since [math] has switched to git as its version control system, release preparation
-can be done easily on the release manager local host in a branch. We will use a
-temporary branch for all release candidates, and delete it afterwards, so the branch
-will be simply named release-candidates. The branch will only be used to store the
-release specific parts (i.e. the pom changes with the version number, the release date
-in the site and so on). Everything else and in particular code change that will remain
-in the component after the release must be committed to the master branch. The release
-candidate branch will be synchronized with master at the start of each new candidate for
+can be done easily on the release manager local host in a branch. As branches deletion
+is now forbidden at Apache, we will use a specific release branch for every version.
+The branch will be simply named X.Y-release, with X.Y being the version number.
+The branch will be used to store the release specific parts (i.e. the pom changes with
+the version number, the release date in the site and so on). Everything else and in
+particular code change that will remain in the component after the release must be
+committed to the master branch (or version branch). The release candidate branch will
+be created from master or version branch at the start of each new candidate for
 this particular release. Once the release is done, the branch will be merged back to
-master and deleted. Of course, this will not delete the history, only the name
-release-candidates pointing to the head of this branch will disappear and can be reused
-for next version.
+master, but it will never be deleted so release history will be preserved.
 
 The example below show a typical workflow. Just after commit A in the master branch, the
-release-candidate branch is created starting from master. This is shown by the 'b' in the
-second line. Then release candidate specific commits are made on the pom and a few other
+X.Y-release branch is created starting from master. This is shown by the 'b' in the
+second line. Then release specific commits are made on the pom and a few other
 files, leading to a commit which will be tagged as RC1. This release candidate fails, and
 a few corrections need to be made on master, corresponding to commits B and C. Then the
-release candidate branch is synchronized by running a 'git merge' command on the branch.
+X.Y-release branch is synchronized by running a 'git merge' command on the branch.
 This is shown by the 'm' in the second line. A new commit is tagged as RC2. This second
 release candidate also fails, and a new correction is made on master branch, a new merge
-is done on the release branch, a new commit is tagged and a third release candidate is
+is done on the X.Y-release branch, a new commit is tagged and a third release candidate is
 create, which succeeds. Then a final tag will be added on the final commit of this branch
 showing the status as released. Then the files are cleaned to prepare for next version
 (pom getting again a SNAPSHOT suffix, changes.xml getting a new placeholder for changes)
-and the cleaned branch is merged back to master. Once the branch has been merged, it is not
-useful anymore so it is deleted, hence the name release-candidate can be used again for
-the release branch of the next version.
+and the cleaned branch is merged back to master. Once the X.Y-release branch has been merged,
+it is kept for history. The release for next version will use another specific branch.
 
 
  ----A-------> B --> C----------> D--------------------------------------m---->    <- master branch
       \               \            \                                    /
-       b---> RC1 ------m---> RC2 ---m---> RC3/final release --> cleaning --X       <- release-candidates branch
+       b---> RC1 ------m---> RC2 ---m---> RC3/final release --> cleaning --X       <- X.Y-release branch
 
 This process allows:
 
@@ -65,9 +63,7 @@ This process allows:
  - to preserve future reference to the release
  - to allow parallel work on master during the release
  - if necessary to have multiple release managers or help on the
-   release as the release-candidates branch is shared
- - to abort a release by deleting the branch early if some
-   larger change is needed on master
+   release as the X.Y-release branch is shared
 
 
 (0)
@@ -92,41 +88,43 @@ should create the artifacts in the "target/deploy".
 
 
 (2)
-At this point, you will work mainly on the release-candidates branch.
+At this point, you will work mainly on the X.Y-release branch.
 
-If the release-candidates branch does not exist because it is the first release
-candidate, create it locally starting from the master branch and push it to
-Apache repository (assuming it is called origin), remembering the binding
-between the local and remote origin branches:
+If the X.Y-release branch does not exist because it is the first release
+candidate, create it locally starting from the master branch or the version
+branch and push it to Apache repository (assuming it is called origin),
+remembering the binding between the local and remote origin branches:
 
-  $ git branch release-candidates
-  $ git push -u origin release-candidates
+  $ git branch X.Y-release
+  $ git push -u origin X.Y-release
 
 (3)
-Switch to the release candidate branch:
+Switch to the release branch:
 
-  $ git checkout release-candidates
+  $ git checkout X.Y-release
 
 
 (4)
-If there have been changes committed in the master branch since the creation of
-the release candidate branch, there are two cases:
+If there have been changes committed in the master branch or the version
+branch since the creation of the release branch, there are two cases:
 
   (4a)
-  if all these changes must be included in the release-candidate,
-  merge master branch into release-candidates branch:
+  if all these changes must be included in the X.Y-release
+  merge master branch or version branch into X.Y-release branch:
 
   $ git merge master
+  or, if the version branch is called MATH_3_X
+  $ git merge MATH_3_X
 
   (4b)
-  if only part of these changes must be included in the release-candidate,
-  cherry-pick the required commits into release-candidates branch:
+  if only part of these changes must be included in the X.Y-release,
+  cherry-pick the required commits into X.Y-release branch:
 
   $ git cherry-pick commit-SHA
 
 (5)
 Update the release specific files, checking you are really working on the
-release-candidate branch and *not* on the master branch.
+X.Y-release branch and *not* on the master branch.
 
 In particular:
  * Update and commit the "src/site/site.xml" file to contain the information
@@ -488,38 +486,14 @@ Double-check "pom.xml" *really* has a -SNAPSHOT version and commit everything:
 
 
 (23)
-Switch back to master and merge the release-candidate branch
+Switch back to master and merge the X.Y-release branch
 
   $ git checkout master
-  $ get merge release-candidates
+  $ get merge X.Y-release
   $ git push
 
 
 (24)
-Delete the now useless release-candidates branch locally (i.e. on your machine):
-
- $ git branch -d release-candidates
-
-Take care at this step to *never* use the "-D" switch, but to use the "-d" switch
-as shown above. The difference is that if you forgot to merge branch release-candidates
-to another still existing branch (here master) as written in the preceding step, git
-will refuse to delete the branch if you use "-d" and will warn you that you are deleting
-a branch that is not merged, but it will delete the branch regardless of its merged
-status if you use "-D".
-
-If you deleted the branch by error without merging it, don't push the deletion to
-Apache repository!
-
-Once you are really sure everything is OK and the tags belong to the ancestors of the
-Apache repository head, you can delete the release-candidates branch also on the
-Apache repository. Beware that deleting a remote branch as a weird syntax, as it
-uses "git push" to push "nothing" (because there is nothing before the colon) into
-the "release-candidates" branch of the "origin" repository):
-
- $ git push origin :release-candidates
-
-
-(25)
 Allow for the web site mirrors to be updated (possibly several hours); then
 send (from your apache account) a release announcement to the following ML:
   announce@apache.org