Repository: commons-rng Updated Branches: refs/heads/master 1084b60a3 -> 2471de816
Update release howto. Project: http://git-wip-us.apache.org/repos/asf/commons-rng/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-rng/commit/b5aac707 Tree: http://git-wip-us.apache.org/repos/asf/commons-rng/tree/b5aac707 Diff: http://git-wip-us.apache.org/repos/asf/commons-rng/diff/b5aac707 Branch: refs/heads/master Commit: b5aac707ff75350a3b7e53f7097b9e144ea7722c Parents: 1084b60 Author: Gilles <[email protected]> Authored: Sat Sep 10 06:16:13 2016 +0200 Committer: Gilles <[email protected]> Committed: Sat Sep 10 06:16:13 2016 +0200 ---------------------------------------------------------------------- doc/release/release.howto.txt | 153 ++++++++++++++++++++++--------------- doc/release/settings.xml | 1 + 2 files changed, 92 insertions(+), 62 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-rng/blob/b5aac707/doc/release/release.howto.txt ---------------------------------------------------------------------- diff --git a/doc/release/release.howto.txt b/doc/release/release.howto.txt index e749302..12a0a69 100644 --- a/doc/release/release.howto.txt +++ b/doc/release/release.howto.txt @@ -80,12 +80,17 @@ Preliminary checks: (1) As a first optional step, you can test that everything works locally, i.e. -that the build process can create all the necessary artifacts. The command +that the build process can create all the necessary artifacts. +The command $ mvn clean deploy -Prelease -Ptest-deploy should create the artifacts in the "target/deploy". +At some point when processing the above command, the GPG passphrase will be +requested; to avoid problems, the "gpg2" executable should be specified in +the "settings.xml" file (see below). + (2) At this point, you will work mainly on the X.Y-release branch. @@ -95,13 +100,14 @@ 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 X.Y-release - $ git push -u origin X.Y-release + $ git branch 1.0-release + $ git push -u origin 1.0-release + (3) Switch to the release branch: - $ git checkout X.Y-release + $ git checkout 1.0-release (4) @@ -109,24 +115,25 @@ 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 X.Y-release - merge master branch or version branch into X.Y-release branch: + if all these changes must be included in version 1.0, merge "master" + or the version branch into "1.0-release": $ git merge master - or, if the version branch is called RNG_1_X + or, if the version branch is called "RNG_1_X" $ git merge RNG_1_X (4b) - if only part of these changes must be included in the X.Y-release, - cherry-pick the required commits into X.Y-release branch: + if only part of these changes must be included in version 1.0, + cherry-pick the required commits into the "1.0-release" branch: $ git cherry-pick commit-SHA + (5) Update the release specific files, checking you are really working on the -X.Y-release branch and *not* on the master branch. +1.0-release branch and *not* on the master branch. In particular: * Update and commit the "src/site/site.xml" file to contain the information @@ -167,7 +174,7 @@ Create it by running: $ mvn -Prelease-notes changes:announcement-generate -Check the file for weird line breaks, and commit the updated file to git: +Check the file for weird line breaks, and commit the updated files to git: $ git add src/site/site.xml \ src/changes/changes.xml \ @@ -175,13 +182,13 @@ Check the file for weird line breaks, and commit the updated file to git: src/site/xdoc/download_rng.xml \ RELEASE-NOTES.txt -Check you did not forget any file: +Check you did not forget any files: $ git status Commit the changes: - $ git commit -m "Creating release candidate." + $ git commit -m "Release candidate." (8) @@ -191,10 +198,10 @@ First, make sure once again that the workspace is up-to-date: $ git status Then, assuming the first candidate, the suffix will be "RC1" (this should -be the same as in the "<properties>" in the "pom.xml"), and the command +be the same as in the "<properties>" in the "pom.xml"), and the command will be: - $ git tag -s -m "Creating Apache Commons Rng v1.0 RC1 tag." RNG_1_0_RC1 + $ git tag -s -m "RC1." RNG_1_0_RC1 If you have several GPG keys, you may prefer to use "-u keyId" to select a specific key for signing the tag instead of "-s" which select automatically one key @@ -211,7 +218,7 @@ You will get something like: tag RNG_1_0_RC1 tagger YourName <YourApacheEmail> 1418934614 +0100 - Creating Apache Commons Rng v1.0 RC1 tag. + RC1. followed by GPG output lines @@ -222,6 +229,7 @@ Push everything (including the tag!) on the Apache repository: $ git push --tags + (9) Switch to a new directory out of your regular workspace, and retrieve the official tag from the Apache repository: @@ -232,12 +240,13 @@ the official tag from the Apache repository: In the command above, the --branch option accepts both branch names and tags names, so we specify directly the tag here. Git will warn that the resulting workspace is in 'detached HEAD' state and 'git status' commands will warn that you are not -currently on any branch. This is expected is this situation. +currently on any branch. This is expected in this situation. Check that the last commit has the id you noted in the previous step: $ git log -1 + (10) If this is your first release, you might need to add your GPG encryption key to the KEYS file. [If you have already done so, skip this section.] @@ -269,29 +278,43 @@ which will transfer the artifacts to the Nexus repository located at This process transfers more files than really needed in the the "staging" (i.e. non official) maven repository. The files expected in the repository are -commons-rng-1.0.pom, commons-rng-1.0.jar, commons-rng-1.0.javadoc, -commons-rng-1.0.sources, commons-rng-1.0.test-sources commons-rng-1.0.tests, -the associated fingerprints (<file-name>.md5 and <file-name>.sha1) and the signatures -<file-name>.asc. Note that Nexus automatically adds "md5" and "sha1" checksums files -to the "asc" files (cryptographic signature). These fingerprints on signatures are -spurious and have to be manually removed from Nexus staging area. The process also -transfers the complete source and binaries distributions files -commons-rng-1.0.-bin.tar.gz, commons-rng-1.0.-bin.zip, commons-rng-1.0.-src.tar.gz, -commons-rng-1.0.-src.zip as well as the associated .md5 and .sha1 fingerprints and the -.asc signatures. These are not really maven artifacts but rather distribution archives, -and they belong elsewhere, so they must also been removed from the Nexus staging + commons-rng-1.0.pom + commons-rng-1.0.jar + commons-rng-1.0.javadoc + commons-rng-1.0.sources + commons-rng-1.0.test-sources + commons-rng-1.0.tests +and their associated fingerprints + <file-name>.md5 + <file-name>.sha1 +and their signatures + <file-name>.asc + +Note that Nexus automatically adds "md5" and "sha1" checksums files to the "asc" +files (cryptographic signature). These fingerprints on signatures are spurious +and have to be manually removed from Nexus staging area. + +The process also transfers the complete source and binaries distributions files: + commons-rng-1.0.-bin.tar.gz + commons-rng-1.0.-bin.zip + commons-rng-1.0.-src.tar.gz + commons-rng-1.0.-src.zip +as well as their associated .md5 and .sha1 fingerprints and .asc signatures. +All these files are not maven artifacts but rather distribution archives: They +belong elsewhere; hence they must also been removed from the Nexus staging repository. -As a measure of sanity check, repository must be manually "closed" before other -people review the deliverables just created. +As a measure of sanity check, the Nexus repository must be manually "closed" +before other people review the deliverables just created. How to "close" the staging repository is explained at this page: http://books.sonatype.com/nexus-book/reference/staging-repositories.html#staging-sect-closing + (12) Upload the other distribution files to the Apache servers. The archive files have been created during the previous step. They have been put -in the .m2 local repository. The RELEASE_NOTES.txt file hase been created earlier +in the .m2 local repository. The RELEASE_NOTES.txt file has been created earlier and is still in the checkout directory of the release candidate. The README.html file can be copied from the release area of the Apache dist server. All these files can be uploaded to the development area of the Apache dist server @@ -303,23 +326,24 @@ using the following commands: $ svn checkout https://dist.apache.org/repos/dist/dev/commons/rng $ cd rng -edit README.html with released version number +Edit the "README.html" file to contain the released version number. - $ cp ~/.m2/repository/org/apache/commons/commons-rng3/1.0/*-bin.* binaries - $ cp ~/.m2/repository/org/apache/commons/commons-rng3/1.0/*-src.* source + $ cp ~/.m2/repository/org/apache/commons/commons-rng/1.0/*-bin.* binaries + $ cp ~/.m2/repository/org/apache/commons/commons-rng/1.0/*-src.* source $ cp <path-to-the-RC-workspace>/RELEASE-NOTES.txt . $ svn add README.html RELEASE-NOTES.txt binaries/* source/* - $ svn commit -m "Creating distribution files for 1.0 RC1" + $ svn commit -m "Distribution files for Commons Rng v1.0 (RC1)." (13) As the web site staging area is shared among all commons components and therefore -can be published before vote ends, it is not recommended to use the standard staging -area for the release candidate. So you will just archive the site and transfer it -to your apache personal area for review. Here is how to do this using lftp to -initiate the sftp transfer (lftp supports a mirror command for recursive transfers, -don't forget the -R flag for uploading instead of downloading the site). If you -haven't setup your login on home.apache.org you will need to go to +could be published before the vote ends, it is not recommended to use the standard +staging area for the release candidate. So you will just archive the site and +transfer it to your apache personal area for review. +Here is how to do this using "lftp" to initiate the sftp transfer. "lftp" supports +a mirror command for recursive transfers; don't forget the -R flag for uploading +instead of downloading the site. +If you haven't setup your login on home.apache.org you will need to go to https://id.apache.org/ login and copy the contents of your ~/.ssh/id_rsa.pub @@ -340,7 +364,7 @@ Call to vote by sending a message to the "dev" ML with subject "[VOTE][RC1] Release Commons Rng 1.0". You can use the following example as a starting point, replacing the URLs with the appropriate ones: ---------- -This is a [VOTE] for releasing Apache Commons Rng 1.0 from release candidate 1. +This is a [VOTE] for releasing Apache Commons Rng 1.0 (from RC1). Tag name: RNG_1_0_RC1 (signature can be checked from git using 'git tag -v') @@ -418,7 +442,7 @@ $ svnmucc -U https://dist.apache.org/repos/dist \ mv dev/commons/rng/source/commons-rng-1.0-src.zip.asc release/commons/rng/source/commons-rng-1.0-src.zip.asc \ mv dev/commons/rng/source/commons-rng-1.0-src.zip.md5 release/commons/rng/source/commons-rng-1.0-src.zip.md5 \ mv dev/commons/rng/source/commons-rng-1.0-src.zip.sha1 release/commons/rng/source/commons-rng-1.0-src.zip.sha1 \ - -m "Publish commons-rng 1.0 Release" + -m "Release Commons Rng v1.0" (18) @@ -453,43 +477,49 @@ and "svn add" them if necessary. Commit the new contents of the web site: $ svn commit -m "Version 1.0 was released: Updating site." -Beware the commit command may be very long (several hours ...). +Beware the commit command may be very long (several hours). + (20) -The javadocs for several version is kept available on the website under the javadocs directory. -This corresponds to a huge number of files which never changes, so they are not retrieved by -default in the working copy when running 'svn checkout'. These javadocs must therefore be -copied manually using server side copy from the apidocs directory after release, in order for -the links to former versions to work. This is done as follows: +The Javadoc for several versions is kept available on the website, under the +"javadocs" directory. +There is a huge number of files that never change, so they are not retrieved by +default in the working copy when running 'svn checkout'. +The Javadoc must therefore be copied manually using server side copy from the +"apidocs" directory after release, in order for the links to former versions +to work. This is done as follows: $ svn cp -m "copying 1.0 apidocs to versioned directory for the long-term links" \ https://svn.apache.org/repos/infra/websites/production/commons/content/proper/commons-rng/apidocs \ https://svn.apache.org/repos/infra/websites/production/commons/content/proper/commons-rng/javadocs/api-1.0 Now wait a few minutes for the live site to fully sync and then check -http://commons.apache.org/proper/commons-rng/ to make sure everything looks -correct. + http://commons.apache.org/proper/commons-rng/ +to make sure that everything looks correct. + (21) Put the official final tag to point at the same commit as the last release candidate tag: - $ git tag -s -m "RC1 becomes the 1.0 official version." RNG_1_0 cf4a9d70c9ac24dd7196995390171150e4e56451 + $ git tag -s -m "RC1 becomes v1.0 official release." RNG_1_0 cf4a9d70c9ac24dd7196995390171150e4e56451 $ git push --tags (22) Clean up files and prepare for next version (here we assume it will be 1.1): -edit "doap_rng.rdf" to add the just released version date. +Edit "doap_rng.rdf" to add the just released version date. -edit "pom.xml" so it contains - - <version>1.1-SNAPSHOT</version> +Edit "pom.xml" to contain -edit "src/changes/changes.xml" to add a new section for the next release, setting -the release date to "TBD" and the description to the empty string. + <version>1.1-SNAPSHOT</version> -Double-check "pom.xml" *really* has a -SNAPSHOT version and commit everything: +Edit "src/changes/changes.xml" to add a new section for the next release, +setting the release date to "TBD" and the description to the empty string. + +Double-check that the "pom.xml" file *really* has a "-SNAPSHOT" suffix in +the "<version>" property. +Then commit everything: $ git add doap_rng.rdf pom.xml src/changes/changes.xml $ git commit -m "Preparing next version (1.1)" @@ -497,10 +527,10 @@ Double-check "pom.xml" *really* has a -SNAPSHOT version and commit everything: (23) -Switch back to master and merge the X.Y-release branch +Switch back to branch "master" and merge the "1.0-release" branch $ git checkout master - $ get merge X.Y-release + $ get merge 1.0-release $ git push @@ -546,4 +576,3 @@ http://repo1.maven.org/maven2/org/apache/commons/ The Apache Commons Team ---------- - http://git-wip-us.apache.org/repos/asf/commons-rng/blob/b5aac707/doc/release/settings.xml ---------------------------------------------------------------------- diff --git a/doc/release/settings.xml b/doc/release/settings.xml index ff0adf6..3123dc0 100644 --- a/doc/release/settings.xml +++ b/doc/release/settings.xml @@ -55,6 +55,7 @@ <id>release</id> <properties> <gpg.keyname>__Your_key_identifier__</gpg.keyname> + <gpg.executable>gpg2</gpg.executable> </properties> </profile> </profiles>
