| # |
| # Licensed to the Apache Software Foundation (ASF) under one or more |
| # contributor license agreements. See the NOTICE file distributed with |
| # this work for additional information regarding copyright ownership. |
| # The ASF licenses this file to You under the Apache License, Version 2.0 |
| # (the "License"); you may not use this file except in compliance with |
| # the License. You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| |
| This document is meant as a step-by-step recipe to achieve the release of |
| the Commons RNG component. Note that more general instructions valid |
| for all components, including [rng], are available on the Apache Commons |
| main site: at "http://commons.apache.org/releases/prepare.html" and |
| "http://commons.apache.org/releases/release.html". |
| |
| The files "settings-security.xml" and "settings.xml" are minimal examples |
| of files used by maven to pick up authentication credentials needed to |
| connect to remote servers and to cryptographically sign the artifacts. |
| |
| Release preparation is done 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, 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 |
| 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 |
| 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 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 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 <- X.Y-release branch |
| |
| This process allows: |
| |
| - to never commit release candidate specific changes to the master |
| branch (so the pom on master always holds a SNAPSHOT version), |
| - 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 X.Y-release branch is shared |
| |
| |
| (0) |
| Preliminary checks: |
| * All Java files must contain a license header. The "RAT" maven plugin will |
| generate a report indicating for which files the license is missing. |
| * For a "minor" release, the library must be backward-compatible. Check all |
| the errors reported by the "Clirr" plugin. |
| * Clear all "CheckStyle" warnings. |
| * Make sure that the construct reported by "FindBugs" are intentional. |
| * Mark all fixed issues as such in the bug-tracking system, and add a |
| corresponding entry in "src/changes/changes.xml". |
| |
| |
| (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 |
| |
| $ 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. |
| |
| 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 1.0-release |
| $ git push -u origin 1.0-release |
| |
| |
| (3) |
| Switch to the release branch: |
| |
| $ git checkout 1.0-release |
| |
| |
| (4) |
| 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 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" |
| |
| $ git merge RNG_1_X |
| |
| (4b) |
| 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 |
| 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 |
| about the API docs of the new release. |
| * Estimate a release date (taking into account the release vote delay) and |
| insert it in the "src/changes/changes.xml" file. |
| * Update the "pom.xml" to contain the final version number and not a SNAPSHOT: |
| Assuming that the release version will be "1.0", modify the "<version>" tag to |
| read: |
| |
| <version>1.0</version> |
| |
| Modify the section of "<properties>" that also refers to version numbers. |
| You should uncomment the "<commons.rc.version>" line and indicate the |
| appropriate numbering of the release candidate: This refers to how many |
| times you will need to repeat this whole release process until it is |
| accepted (by a vote): |
| |
| <properties> |
| <!-- ... --> |
| <commons.release.version>1.0</commons.release.version> |
| <commons.rc.version>RC1</commons.rc.version> |
| <!-- ... --> |
| </properties> |
| |
| |
| (6) |
| The "download" page template is located at "src/site/xdoc/download_rng.xml". |
| This file is updated automatically by running the command: |
| |
| $ mvn commons:download-page |
| |
| |
| (7) |
| The "release notes" file will be created by gathering all the changes |
| collected during development in the file "src/changes/changes.xml". |
| Create it by running: |
| |
| $ mvn -Prelease-notes changes:announcement-generate |
| |
| Check the file for weird line breaks, and commit the updated files to git: |
| |
| $ git add src/site/site.xml \ |
| src/changes/changes.xml \ |
| pom.xml \ |
| src/site/xdoc/download_rng.xml \ |
| RELEASE-NOTES.txt |
| |
| Check you did not forget any files: |
| |
| $ git status |
| |
| Commit the changes: |
| |
| $ git commit -m "Release candidate." |
| |
| |
| (8) |
| Create a GPG signed tag that will contain the whole source of this release candidate. |
| 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 |
| will be: |
| |
| $ git tag -u "__Your_key_id__" -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 |
| from the configured e-mail address. |
| |
| Check the tag GPG signature: |
| |
| $ git tag -v RNG_1_0_RC1 |
| |
| You will get something like: |
| |
| object cf4a9d70c9ac24dd7196995390171150e4e56451 |
| type commit |
| tag RNG_1_0_RC1 |
| tagger YourName <YourApacheEmail> 1418934614 +0100 |
| |
| RC1. |
| |
| followed by GPG output lines. |
| |
| Remember the commit ID listed in the object line (here cf4a9d70c9ac24dd7196995390171150e4e56451), |
| as it is the most stable reference for traceability. |
| |
| 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: |
| |
| $ cd /tmp |
| $ git clone https://git-wip-us.apache.org/repos/asf/commons-rng.git --branch RNG_1_0_RC1 |
| |
| 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 in this situation. |
| |
| Check that the last commit has the id you noted in the previous step: |
| |
| $ cd commons-rng |
| $ 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.] |
| |
| Retrieve the files from the SVN repository: |
| |
| $ svn co --depth=immediates \ |
| https://__Your_apache_login__@svn.apache.org/repos/asf/commons/trunks-proper |
| |
| and follow the instructions at the top of the "KEYS" file. |
| |
| |
| (11) |
| Create and transfer the artifacts to the Nexus server (a.k.a. "deploy"). |
| |
| Because the artifacts must be cryptographically signed, this step requires that |
| a profile named "release" exists in the maven "settings.xml" configuration file |
| which will contain the identifier of your GPG key (cf. sample "settings.xml" |
| file). You will also have to follow the instructions at |
| https://maven.apache.org/guides/mini/guide-encryption.html to set your password |
| in the settings.xml file. |
| |
| You can then run |
| |
| $ mvn clean deploy -Prelease |
| |
| which will transfer the artifacts to the Nexus repository located at |
| https://repository.apache.org/index.html#stagingRepositories |
| |
| 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 |
| and their associated fingerprints |
| <file-name>.md5 |
| <file-name>.sha1 |
| and their signatures |
| <file-name>.asc |
| |
| Nexus used to add "md5" and "sha1" checksums files to the "asc" files |
| (cryptographic signature). If these fingerprints on signatures are |
| present, they must 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, 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 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 |
| using the following commands: |
| |
| $ cd /tmp |
| $ svn cp https://dist.apache.org/repos/dist/release/commons/rng/README.html \ |
| https://dist.apache.org/repos/dist/dev/commons/rng/README.html |
| $ svn checkout https://dist.apache.org/repos/dist/dev/commons/rng |
| $ cd rng |
| |
| Edit the "README.html" file to contain the released version number. |
| |
| $ 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 \ |
| CONTRIBUTING.md \ |
| README.md \ |
| README.html \ |
| RELEASE-NOTES.txt \ |
| binaries/* \ |
| source/* |
| $ 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 |
| 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 |
| file to "SSH Key (authorized_keys line)". |
| Then run these commands: |
| |
| $ mvn site |
| $ cd target |
| $ mv site commons-rng-1.0-RC1-site |
| $ lftp sftp://__Your_apache_login__@home.apache.org |
| lftp you@home.apache.org:~> cd public_html |
| lftp you@home.apache.org:~/public_html> mirror -R commons-rng-1.0-RC1-site |
| lftp you@home.apache.org:~/public_html> bye |
| |
| |
| (14) |
| 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 RC1). |
| |
| Tag name: |
| RNG_1_0_RC1 (signature can be checked from git using 'git tag -v') |
| |
| Tag URL: |
| https://git-wip-us.apache.org/repos/asf?p=commons-rng.git;a=commit;h=cf4a9d70c9ac24dd7196995390171150e4e56451 |
| |
| Commit ID the tag points at: |
| cf4a9d70c9ac24dd7196995390171150e4e56451 |
| |
| Site: |
| http://home.apache.org/~__Your_apache_login__/commons-rng-1.0-RC1-site |
| |
| Distribution files: |
| https://dist.apache.org/repos/dist/dev/commons/rng/ |
| |
| Distribution files hashes (SHA1): |
| e02c981d49c1f12b1fc237e69cb551a5620e57b4 commons-rng-1.0-bin.tar.gz |
| 11965eb97033d4d6ef0aeb902f1450641f40d3c5 commons-rng-1.0-bin.zip |
| ce3efda70ac8f850f15154b38438bc337adc027a commons-rng-1.0-src.tar.gz |
| d343c885a9d6eea611403f7f92ff580911363681 commons-rng-1.0-src.zip |
| |
| KEYS file to check signatures: |
| http://www.apache.org/dist/commons/KEYS |
| |
| Maven artifacts: |
| https://repository.apache.org/content/repositories/orgapachecommons-051/org/apache/commons/commons-rng/1.0/ |
| |
| [ ] +1 Release it. |
| [ ] +0 Go ahead; I don't care. |
| [ ] -0 There are a few minor glitches: ... |
| [ ] -1 No, do not release it because ... |
| |
| This vote will close in 72 hours, at YYYY-MM-DDThh:mm:ssZ (this is UTC |
| time). |
| ---------- |
| |
| |
| (15) |
| If some blocking problems have been found in the release deliverables, cancel |
| the vote by sending a "[CANCEL][VOTE]" message to the "dev" ML. |
| After correcting the problems, you'll likely have to start again from step 3, |
| 4 or 5. |
| |
| |
| (16) |
| After at least 72 hours have elapsed, send a "[VOTE][RESULT]" mail to |
| summarize the outcome of the vote. This should tally the votes cast, |
| and state which are binding (PMC members). The vote needs at least three +1's |
| from PMC members to pass. |
| |
| |
| (17) |
| The distribution files must be moved from the development area to the release |
| area of the Apache dist server: |
| |
| $ svnmucc -U https://dist.apache.org/repos/dist \ |
| rm release/commons/rng/README.html \ |
| mv dev/commons/rng/README.html release/commons/rng/README.html \ |
| rm release/commons/rng/RELEASE-NOTES.txt \ |
| mv dev/commons/rng/RELEASE-NOTES.txt release/commons/rng/RELEASE-NOTES.txt \ |
| mv dev/commons/rng/binaries/commons-rng-1.0-bin.tar.gz release/commons/rng/binaries/commons-rng-1.0-bin.tar.gz \ |
| mv dev/commons/rng/binaries/commons-rng-1.0-bin.tar.gz.asc release/commons/rng/binaries/commons-rng-1.0-bin.tar.gz.asc \ |
| mv dev/commons/rng/binaries/commons-rng-1.0-bin.tar.gz.md5 release/commons/rng/binaries/commons-rng-1.0-bin.tar.gz.md5 \ |
| mv dev/commons/rng/binaries/commons-rng-1.0-bin.tar.gz.sha1 release/commons/rng/binaries/commons-rng-1.0-bin.tar.gz.sha1 \ |
| mv dev/commons/rng/binaries/commons-rng-1.0-bin.zip release/commons/rng/binaries/commons-rng-1.0-bin.zip \ |
| mv dev/commons/rng/binaries/commons-rng-1.0-bin.zip.asc release/commons/rng/binaries/commons-rng-1.0-bin.zip.asc \ |
| mv dev/commons/rng/binaries/commons-rng-1.0-bin.zip.md5 release/commons/rng/binaries/commons-rng-1.0-bin.zip.md5 \ |
| mv dev/commons/rng/binaries/commons-rng-1.0-bin.zip.sha1 release/commons/rng/binaries/commons-rng-1.0-bin.zip.sha1 \ |
| mv dev/commons/rng/source/commons-rng-1.0-src.tar.gz release/commons/rng/source/commons-rng-1.0-src.tar.gz \ |
| mv dev/commons/rng/source/commons-rng-1.0-src.tar.gz.asc release/commons/rng/source/commons-rng-1.0-src.tar.gz.asc \ |
| mv dev/commons/rng/source/commons-rng-1.0-src.tar.gz.md5 release/commons/rng/source/commons-rng-1.0-src.tar.gz.md5 \ |
| mv dev/commons/rng/source/commons-rng-1.0-src.tar.gz.sha1 release/commons/rng/source/commons-rng-1.0-src.tar.gz.sha1 \ |
| mv dev/commons/rng/source/commons-rng-1.0-src.zip release/commons/rng/source/commons-rng-1.0-src.zip \ |
| 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 "Release Commons RNG v1.0" |
| |
| |
| (18) |
| Release (a.k.a. "promote") the artifacts on the Nexus server, as shown here: |
| http://books.sonatype.com/nexus-book/reference/staging-repositories.html#staging-sect-releasing |
| |
| |
| (19) |
| Publish the web site. This is done by first committing the web site to the |
| staging area, and then by publishing the staging area (which is shared among |
| all commons components). |
| |
| In order to commit the web site to the staging area, look at the subversion |
| workspace that was automatically checked out during the 'mvn site' command in |
| folder site-content. Note that svn commits in the site-content directory are |
| immediately synced with the live site and so your changes should show up in a |
| few minutes once you commit the new site. You can also check out the site |
| directly by yourself elsewhere: |
| |
| svn checkout https://svn.apache.org/repos/infra/websites/production/commons/content/proper/commons-rng site-content |
| |
| Remove all files there (except .svn folder) and move all the files from the site. |
| |
| $ cd site-content |
| $ rm -fr * |
| $ cp -pR ../target/commons-rng-1.0-RC1-site/* . |
| |
| Check for possibly new files: |
| $ svn status |
| 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). |
| |
| |
| (20) |
| 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 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 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 "pom.xml" to contain |
| |
| <version>1.1-SNAPSHOT</version> |
| |
| 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)" |
| $ git push |
| |
| |
| (23) |
| Switch back to branch "master" and merge the "1.0-release" branch |
| |
| $ git checkout master |
| $ get merge 1.0-release |
| $ git push |
| |
| |
| (24) |
| Update the report database: |
| https://reporter.apache.org/addrelease.html?commons |
| |
| |
| (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 |
| dev@commons.apache.org |
| user@commons.apache.org |
| |
| If you don't have it setup already you can follow these instructions to send |
| email from your apache account : |
| |
| https://reference.apache.org/committer/email#sendingemailfromyourapacheorgemailaddress |
| |
| You can use the following message as a template: |
| |
| ---------- |
| The Apache Commons Team is pleased to announce the availability of: |
| |
| Apache Commons RNG 1.0 |
| |
| Apache Commons RNG provides Java implementations of pseudo-random |
| numbers generators. |
| |
| The release notes can be reviewed at: |
| http://www.apache.org/dist/commons/rng/RELEASE-NOTES.txt |
| |
| Distribution packages can be downloaded from: |
| https://commons.apache.org/proper/commons-rng/download_rng.cgi |
| |
| When downloading, please verify signatures using the KEYS file available at: |
| http://www.apache.org/dist/commons |
| |
| Maven artifacts are also available in the central Maven repository: |
| |
| http://repo1.maven.org/maven2/org/apache/commons/ |
| |
| The Apache Commons Team |
| ---------- |