From 365d7bb45615a2cdb44914a64606ef243d2ea45b Mon Sep 17 00:00:00 2001 From: Luc Maisonobe Date: Sun, 7 Apr 2013 12:47:32 +0000 Subject: [PATCH] Updated [math] specific release howto. - added references to the general Apache Commons release howtos, - changed the staging area of the distribution files to the Apache servers (and not the Nexus repository), - added the URL of the site for direct subversion control git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1465382 13f79535-47bb-0310-9956-ffa450edef68 --- doc/release/release.howto.txt | 167 ++++++++++++++++++---------------- 1 file changed, 91 insertions(+), 76 deletions(-) diff --git a/doc/release/release.howto.txt b/doc/release/release.howto.txt index 8d00de038..1e1504cd0 100644 --- a/doc/release/release.howto.txt +++ b/doc/release/release.howto.txt @@ -15,7 +15,10 @@ # limitations under the License. This document is meant as a step-by-step recipe to achieve the release of -the Commons Math component. +the Commons Math component. Note that more general instructions valid +for all components, including [math], 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 @@ -59,7 +62,7 @@ The "pom.xml" on the SVN server must always be in a state for creating snapshot versions of the library, i.e. the tag "" should end with the string "-SNAPSHOT": - 3.3-SNAPSHOT + 3.2-SNAPSHOT Assuming that the release version will be "3.2", modify the "" tag to read: @@ -93,7 +96,7 @@ This file is updated automatically by running the command: (4) The "release notes" file will be created by gathering all the changes -collected during develoment in the file "src/changes/changes.xml". +collected during development in the file "src/changes/changes.xml". Create it by running: $ mvn changes:announcement-generate \ @@ -107,18 +110,19 @@ which you must now copy to the appropriate location: Alternately to the above two commands, you can rely on the "release-notes" profile defined in the "commons-parent" project (which is inherited by the -"commons-math project) and run: +"commons-math project) and run the following command, which will directly create +the RELEASE-NOTES.txt file: $ mvn -Prelease-notes changes:announcement-generate -Commit the updated file to SVN: +Check the file for weird line breaks, and commit the updated file to SVN: $ svn commit RELEASE-NOTES.txt (5) Create the tag that will contain the whole source of this release candidate. -First, make sure that the working is up-to-date: +First, make sure that the workspace is up-to-date: $ svn up @@ -154,30 +158,58 @@ and follow the instructions at the top of the "KEYS" file. (8) -Create and transfer the artefacts to the Nexus server (a.k.a. "deploy"). +Create and transfer the artifacts to the Nexus server (a.k.a. "deploy"). -Because the artefacts must be cryptographically signed, this step requires that +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 can then run - $ mvn -DskipTests=true clean deploy -Prelease + $ mvn clean deploy -Prelease -which will transfer the artefacts to the Nexus repository located at +which will transfer the artifacts to the Nexus repository located at https://repository.apache.org/index.html#stagingRepositories -As a measure of sanity check, the "staging" (i.e. non official) repository must -be manually "closed" before other people review the deliverables just created. -[Note: Nexus automatically adds "md5" and "sha1" checksums files to the "asc" -files (cryptographic signature). These "signatures on signatures" are spurious -and have to be manually removed from Nexus staging area.] +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-math3-3.2.pom, commons-math3-3.2.jar, commons-math3-3.2.javadoc, +commons-math3-3.2.sources, commons-math3-3.2.test-sources commons-math3-3.2.tests, +the associated fingerprints (.md5 and .sha1) and the signatures +.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-math3-3.2.-bin.tar.gz, commons-math3-3.2.-bin.zip, commons-math3-3.2.-src.tar.gz, +commons-math3-3.2.-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 +repository. + +As a measure of sanity check, repository must be manually "closed" before other +people review the deliverables just created. How to "close" the staging repository it is explained at this page: https://docs.sonatype.org/display/Repository/Closing+a+Staging+Repository - (9) +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 +and is still in the checkout directory of the release candidate. All these files +can be uploaded to the development area of the Apache dist server using the +following commands: + + $ cd /tmp + $ svn checkout https://dist.apache.org/repos/dist/dev/commons/math + $ cp /.m2/repository/org/apache/commons/commons-math/3.2*-bin.* binaries + $ cp /.m2/repository/org/apache/commons/commons-math/3.2*-src.* source + $ cp /RELEASE-NOTES.txt . + $ svn commit -m "Creating distribution files for 3.2 RC1" + + +(10) Web site testing (a.k.a "staging") of the generated web site (containing the API documentation, etc.) @@ -199,7 +231,7 @@ The web site will be available for review at: http://people.apache.org/builds/commons/math/3.2/RC1 -(10) +(11) Call to vote by sending a message to the "dev" ML with subject "[VOTE][RC1] Release Commons Math 3.2". You can use the following example as a starting point, replacing the URLs with the appropriate ones: @@ -210,7 +242,10 @@ Tag: Site: http://people.apache.org/builds/commons/math/3.2/RC1/ -Binaries: +Distribution files: + https://dist.apache.org/repos/dist/dev/commons/math/ + +Maven artifacts: https://repository.apache.org/content/repositories/orgapachecommons-051/org/apache/commons/commons-math3/3.2/ [ ] +1 Release it. @@ -222,85 +257,65 @@ This vote will close in 72 hours. ---------- -(11) +(12) 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. -(12) +(13) 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). -(13) -The artefacts must be copied to the distribution area on the ASF web server. +(14) +The distribution files must be moved from the development area to the release +area of the Apache dist server: -The following actions must be performed when after login into your -"people.apache.org" account. - - (a) Create a new directory (e.g. "cm-3.2") and "cd" into it. - - (b) Retrieve the files from the Nexus server: - - $ wget -r -l 1 -np -nH -nd -nv \ - -e robots=off --wait 10 --no-check-certificate \ - https://repository.apache.org/content/repositories/orgapachecommons-051/org/apache/commons/commons-math3/3.2/ - - (c) Verify the checksum of each of the retrieved files. A possibility is to - check out the tools from - https://svn.apache.org/repos/private/committers/tools/releases - and use the "verify_sigs.sh" found in there. - - (d) Change the "group owner" to "commons": - - $ chgrp commons commons-math3-* - - (e) Change to the directory of the component and move the files to their position. - - $ cd /www/www.apache.org/dist/commons/math/ - - Source files go to the "source" subdirectory: - - $ mv -i ~/cm-3.2/commons-math3-3.2-src* source - - Binary files go to the "binaries" subdirectory: - - $ mv -i ~/cm-3.2/commons-math3-3.2-bin* binaries - - (f) Check that the files permissions are all set to "-rw-rw-r--" and that - the group owner is "commons". - - (g) Update the "README.html" file to reflect the new release and copy it - to both "source" and "binaries" subdirectories. - - (h) Replace the "RELEASE-NOTES.txt" with the new one, e.g. using: - - $ wget --no-check-certificate https://svn.apache.org/repos/asf/commons/proper/math/tags/MATH_3_2_RC1/RELEASE-NOTES.txt - $ mv -i RELEASE-NOTES.txt.1 RELEASE-NOTES.txt - - (i) XXX There are no "current" symlinks in the "commmons/math" subdir - Maybe that this is not mandatory (?) - If this is your first release, you'll probably have to check out the - release scripts. In your home directory, run the command: - - $ svn co https://svn.apache.org/repos/private/committers/tools/releases/ +$ svnmucc -U https://dist.apache.org/repos/dist \ + mv dev/commons/math/RELEASE-NOTES.txt release/commons/math/RELEASE-NOTES.txt \ + mv dev/commons/math/binaries/commons-math-3.2-bin.tar.gz release/commons/math/binaries/commons-math-3.2-bin.tar.gz \ + mv dev/commons/math/binaries/commons-math-3.2-bin.tar.gz.asc release/commons/math/binaries/commons-math-3.2-bin.tar.gz.asc \ + mv dev/commons/math/binaries/commons-math-3.2-bin.tar.gz.md5 release/commons/math/binaries/commons-math-3.2-bin.tar.gz.md5 \ + mv dev/commons/math/binaries/commons-math-3.2-bin.tar.gz.asc release/commons/math/binaries/commons-math-3.2-bin.tar.gz.asc \ + mv dev/commons/math/binaries/commons-math-3.2-bin.zip release/commons/math/binaries/commons-math-3.2-bin.zip \ + mv dev/commons/math/binaries/commons-math-3.2-bin.zip.asc release/commons/math/binaries/commons-math-3.2-bin.zip.asc \ + mv dev/commons/math/binaries/commons-math-3.2-bin.zip.md5 release/commons/math/binaries/commons-math-3.2-bin.zip.md5 \ + mv dev/commons/math/binaries/commons-math-3.2-bin.zip.asc release/commons/math/binaries/commons-math-3.2-bin.zip.asc \ + mv dev/commons/math/source/commons-math-3.2-src.tar.gz release/commons/math/source/commons-math-3.2-src.tar.gz \ + mv dev/commons/math/source/commons-math-3.2-src.tar.gz.asc release/commons/math/source/commons-math-3.2-src.tar.gz.asc \ + mv dev/commons/math/source/commons-math-3.2-src.tar.gz.md5 release/commons/math/source/commons-math-3.2-src.tar.gz.md5 \ + mv dev/commons/math/source/commons-math-3.2-src.tar.gz.asc release/commons/math/source/commons-math-3.2-src.tar.gz.asc \ + mv dev/commons/math/source/commons-math-3.2-src.zip release/commons/math/source/commons-math-3.2-src.zip \ + mv dev/commons/math/source/commons-math-3.2-src.zip.asc release/commons/math/source/commons-math-3.2-src.zip.asc \ + mv dev/commons/math/source/commons-math-3.2-src.zip.md5 release/commons/math/source/commons-math-3.2-src.zip.md5 \ + mv dev/commons/math/source/commons-math-3.2-src.zip.asc release/commons/math/source/commons-math-3.2-src.zip.asc \ + -m "Publish commons-math 3.2 Release" -(13) -Release (a.k.a. "promote") the artefacts on the Nexus server, as shown here: +(15) +Release (a.k.a. "promote") the artifacts on the Nexus server, as shown here: https://docs.sonatype.org/display/Repository/Releasing+a+Staging+Repository -(14) +(16) Publish the web site. From your local working copy of the tag, run the command: $ mvn site-deploy +You may want to adjust manually some parts like fixing broken relative links or +copying the content of the current apidocs to javadocs/api-3.2. In order to do +this, you have to check out the production site using svn, make your changes locally +and commit the changes back to the server. -(15) +$ svn checkout https://svn.apache.org/repos/infra/websites/production/commons/content/proper/commons-math +$ +$ svn commit -m "fixing broken links" + + +(17) Copy the the final RC tag to the official tag: $ svn copy \ https://svn.apache.org/repos/asf/commons/proper/math/tags/MATH_3_2_RC1 \ @@ -308,7 +323,7 @@ Copy the the final RC tag to the official tag: https://svn.apache.org/repos/asf/commons/proper/math/tags/MATH_3_2 -(16) +(18) 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