Author: juanpablo
Date: Wed Dec 18 23:47:56 2013
New Revision: 1552165
URL: http://svn.apache.org/r1552165
Log:
revamped how to release documentation
Modified:
jspwiki/site/trunk/content/ppmc/how_to_release.mdtext
Modified: jspwiki/site/trunk/content/ppmc/how_to_release.mdtext
URL:
http://svn.apache.org/viewvc/jspwiki/site/trunk/content/ppmc/how_to_release.mdtext?rev=1552165&r1=1552164&r2=1552165&view=diff
==============================================================================
--- jspwiki/site/trunk/content/ppmc/how_to_release.mdtext (original)
+++ jspwiki/site/trunk/content/ppmc/how_to_release.mdtext Wed Dec 18 23:47:56
2013
@@ -1,254 +1,236 @@
-Title: How to Release
-
-## How to Release
-
-[TOC]
-
-<div style="clear:both;">
-(most of the content grabbed/adapted from MRUnit site)
-</div>
-
-
-## First time release managers
-
- 1. Generate [PGP code signing keys][]
- 2. Add the PGP code signing keys to the [KEYS file][] as documented on the
-[Infrastructure site][]
- 3. Put in a [Infrastructure JIRA][] asking to get added to the jspwiki unix
-group on people.apache.org <!--and the jspwiki deployer role for Nexus-->
- 4. Copy the modified KEYS file to the release folder
-/www/www.apache.org/dist/jspwiki on people.apache.org and ensure it
-has 0664 permissions.
-
-<!---
- 5. Add the following to your Maven settings.xml file:
-
- <servers>
- <server>
- <id>apache.releases.https</id>
- <username>APACHE-ID</username>
- <password>APACHE-PASSWORD</password>
- </server>
- </servers>
--->
-It is convenient to [setup the ssh keys][] on people.apache.org, otherwise
-you'll have to enter your login password a number of times.
-
-## Create a release candidate
-
- 1. Generate release notes
-
-
-<!-- TODO
- What exactly do we want to do here?
- Completing the details makes only sense once we're a TLP and thus not
- dependent from externs anymore.
-
-
- 1. Update ReleaseNotes with [new release notes from JIRA][], select the
-version and set the style to Text
- 2. Commit the updated ReleaseNotes with message: "Preparing for release
-X.Y.Z"
--->
-
-<!---
- 2. Create a branch (only required for the first release in a series (X.Y.0))
-
- 1. Create a branch for the X.Y release series
-
- svn copy https://svn.apache.org/repos/asf/jspwiki/trunk \
- https://svn.apache.org/repos/asf/jspwiki/branches/jspwiki-X.Y -m
"Branching for X.Y releases"
-
- 2. Bump the version number in trunk and commit (the update-versions script
-mangles the whitespace in the root XML element):
-
- sed -i "" -e "s/X.Y.0-SNAPSHOT/X.Y+1.0-SNAPSHOT/" pom.xml
-
- 3. Checkout the release branch:
-
- svn checkout
https://svn.apache.org/repos/asf/jspwiki/branches/jspwiki-X.Y
-
- 3. Remove -SNAPSHOT from the release branch and commit
-
- sed -i "" -e "s/X.Y.Z-SNAPSHOT/X.Y.Z/" pom.xml
-
- 4. Deploy to Nexus Staging Repository
-
- 1. Deploy artifact:
-
- mvn clean deploy -Psign
-
- 2. Verify licenses in target/rat.txt
-
- 3. Login to <https://repository.apache.org> and select Staging
Repositories
-on the left under Build Promotion.
- 4. Select org.apache.jspwiki from the list of repositories, select the
-current repository and delete any asc.md5/asc.sha1 files. Then click Close
-using "Apache JSPWiki X.Y.Z" as the description to allow others
-to see the repository.
--->
- 2. Deploy source and binary distributions
-
- 1. Build JSPWiki using Maven:
-
- mvn clean install -Pintegration-tests
-
- 2. Generate the src & bin distributions using Ant:
-
- ant clean signeddist
-
- 3. Copy the src distribution file and checksums to people.apache.org,
-excluding the asc.md5/asc.sha1 files:
-
- scp target/*.tar.gz*
usern...@people.apache.org:~/public_html/jspwiki-X.Y.Z-candidate-$RC
-
-<!---
- 3. Generate the bin distribution:
-
- mvn clean assembly:single gpg:sign checksum:artifacts -Pdist-bin
-
- 4. Copy the bin distribution file and checksums to people.apache.org,
-excluding the asc.md5/asc.sha1 files:
-
- rm target/*asc.*
- scp target/*.tar.gz*
usern...@people.apache.org:~/public_html/jspwiki-X.Y.Z-candidate-$RC
--->
- 3. Tag the release candidate:
-
- svn copy
https://svn.apache.org/repos/asf/jspwiki/branches/jspwiki-X.Y/ \
- https://svn.apache.org/repos/asf/jspwiki/tags/release-X.Y.Z/ -m
"jspwiki X.Y.Z release."
-
-## Run a vote
-
-Send the following to d...@jspwiki.apache.org:
-
-<!---
- Subject: [VOTE] Release JSPWiki version X.Y.Z
-
- This is a release for Apache JSPWiki, version X.Y.Z.
-
- It fixes the following issues:
-
https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12310732&version=<REPLACE>
-
- *** Please download, test and vote by [3 working days after sending].
-
- Note that we are voting upon the source (tag), binaries are provided for
convenience.
-
- Source and binary files:
- http://people.apache.org/~<REPLACE>/jspwiki-X.Y.Z-candidate-$RC
-
- Maven staging repo:
-
https://repository.apache.org/content/repositories/orgapachejspwiki-<REPLACE>/
-
- The tag to be voted upon:
- http://svn.apache.org/repos/asf/jspwiki/tags/release-X.Y.Z/
-
- JSPWiki's KEYS file containing PGP keys we use to sign the release:
- http://www.apache.org/dist/jspwiki/KEYS
--->
-
- Subject: [VOTE] Release JSPWiki version X.Y.Z
-
- This is a release for Apache JSPWiki, version X.Y.Z.
-
- It fixes the following issues:
-
https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12310732&version=<REPLACE>
-
- *** Please download, test and vote by [3 working days after sending].
-
- Note that we are voting upon the source (tag), binaries are provided for
convenience.
-
- Source and binary files:
- http://people.apache.org/~<REPLACE>/jspwiki-X.Y.Z-candidate-$RC
-
- The tag to be voted upon:
- http://svn.apache.org/repos/asf/jspwiki/tags/release-X.Y.Z/
-
- JSPWiki's KEYS file containing PGP keys we use to sign the release:
- http://www.apache.org/dist/jspwiki/KEYS
-
-Note that the PMC needs to vote upon the release before any release can be
made official.
-
-## Roll Out
-
-If the vote passes, roll out the release:
-
-<!---
- 1. Publish Nexus repository:
- 1. Login to <https://repository.apache.org> and select Staging
Repositories
-on the left under Build Promotion.
- 2. Select the repository that was closed earlier, and click Release, using
-the description "Apache jspwiki X.Y.Z artifacts"
--->
- 1. Publish src and bin distributions to the [mirrors][]:
-
- ssh people.apache.org
- VERSION=X.Y.Z
- PREVIOUS_VERSION=X.Y.Z
- CANDIDATE=C
- cp -r ~/public_html/jspwiki-$VERSION-candidate-$CANDIDATE \
- /www/www.apache.org/dist/jspwiki/jspwiki-$VERSION
- cd /www/www.apache.org/dist/jspwiki
- chgrp -R jspwiki jspwiki-$VERSION
- chmod -R g+w jspwiki-$VERSION
- rm -r /www/www.apache.org/dist/jspwiki/jspwiki-$PREVIOUS_VERSION #
remove older versions
-
- The last line is to remove the previous version, since only the most
recent
-version on a particular branch should be in the dist directory. Older versions
-are [archived][] automatically.
-
- 2. Wait 24 hours for mirrors to sync
- 3. Post the javadoc to the site:
-
- 1. Create the javadoc:
-
- mvn javadoc:javadoc
-
- 2. Copy javadocs to
https://svn.apache.org/repos/infra/websites/production/jspwiki/documentation/javadocs/X.Y.Z
- 3. Add a link to index.html of the javadoc in the
documentation/javadoc.mdtext page
-
- 4. Post link to the full release notes along with links to the major JIRA
-changes on the front page of the site
-
-## Announce the release
-
-Send the following from an apache.org address to annou...@apache.org,
-u...@jspwiki.apache.org, d...@jspwiki.apache.org:
-
- Subject: [ANNOUNCE] Apache JSPWiki X.Y.Z released
-
- The Apache JSPWiki team is pleased to announce the release of JSPWiki
X.Y.Z.
-
- This is the <REPLACE> release of Apache JSPWiki, a feature-rich and
- extensible WikiWiki engine built around the standard J2EE components.
-
- The release is available here:
- http://www.apache.org/dyn/closer.cgi/jspwiki/
-
- The full change log is available here:
- https://issues.apache.org/jira/browse/jspwiki/fixforversion/<REPLACE>
-
- We welcome your help and feedback. For more information on how to
- report problems, and to get involved, visit the project website at
- http://jspwiki.apache.org/
-
- The Apache JSPWiki Team
-
-## Add the next release to JIRA
-
- 1. Add the [next version number to JIRA][]
- 2. Mark the released version as "released" with a release date
-
-
-[PGP code signing keys]:
http://www.apache.org/dev/release-signing.html#generate
-[KEYS file]: http://svn.apache.org/repos/asf/jspwiki/dist/KEYS
-[Infrastructure site]:
http://www.apache.org/dev/release-signing.html#keys-policy
-[Infrastructure JIRA]: https://issues.apache.org/jira/browse/INFRA
-[setup the ssh keys]:
http://www.thegeekstuff.com/2008/11/3-steps-to-perform-ssh-login-without-password-using-ssh-keygen-ssh-copy-id/
-
-[new release notes from JIRA]:
https://issues.apache.org/jira/secure/ConfigureReleaseNote.jspa?projectId=12310732
-
-[archived]: http://archive.apache.org/dist/jspwiki/
-[mirrors]: http://www.apache.org/dev/mirrors.html
-
-[next version number to JIRA]:
https://issues.apache.org/jira/plugins/servlet/project-config/jspwiki/versions
+Title: How to Release
+
+Title: How to Release
+
+## How to Release
+
+[TOC]
+
+## First time release managers
+
+ 1. Generate [PGP code signing keys][]
+
+ 2. Add the PGP code signing keys to the [KEYS file][] as documented on the
+[Infrastructure site][]
+
+ 3. Put in a [Infrastructure JIRA][] asking to get added to the jspwiki unix
+group on `people.apache.org`
+
+ 4. Copy the modified KEYS file to the release folder
+`/www/www.apache.org/dist/jspwiki` on `people.apache.org` and ensure it
+has `0664` permissions.
+
+ 5. Add the following `servers` to your Maven `settings.xml` file:
+
+ <servers>
+ <server>
+ <id>apache.releases.https</id>
+ <username>APACHE-ID</username>
+ <password>APACHE-PASSWORD</password>
+ </server>
+ <server>
+ <id>apache.snapshots.https</id>
+ <username>APACHE-ID</username>
+ <password>APACHE-PASSWORD</password>
+ </server>
+ <server>
+ <id>svn.apache.org</id>
+ <username>APACHE-ID</username>
+ <password>APACHE-PASSWORD</password>
+ </server>
+ </servers>
+
+Note that your password doesn't need to be inside the `settings.xml` file, due
to
+[Maven encryption capabilities][]. It is also convenient to [setup the ssh
keys][]
+on `people.apache.org`, otherwise you'll have to enter your login password a
number of times.
+
+## Create a release candidate
+
+### Generate release candidate artifacts
+
+ 1. Generate artifacts
+
+ mvn clean apache-rat:rat install -Papache-release
+
+ This will check that all files have AL headers and also build artifacts,
sources and sign
+
+ 2. Check `POMs` for release
+
+ mvn release:prepare -DdryRun=true -DautoVersionSubmodules=true
+
+ Perform quick diffs between `pom.xml` files and their sibling `pom.xml.tag`
files to see if the
+license or any other info has been removed (should never happen, but just to
stay on the safe side).
+
+### Prepare the release
+
+ 1. **Publish a snapshot**
+
+ mvn deploy
+
+ 2. **Prepare the release**
+
+ mvn release:clean
+ mvn release:prepare -DautoVersionSubmodules=true
+
+ 3. **Stage the release for a vote**
+
+ mvn release:perform
+
+ 4. **Close the staging repository**
+
+ 1. Login to <https://repository.apache.org> and select Staging
Repositories
+on the left under Build Promotion.
+
+ 2. Select org.apache.jspwiki from the list of repositories, select the
+current repository and delete any `asc.md5/asc.sha1` files. Then click
[Close][]
+using "Apache JSPWiki X.Y.Z" as the description to allow others
+to see the repository.
+
+ 5. **Copy the bin distribution files and checksums to people.apache.org**,
+excluding the `asc.md5/asc.sha1` files:
+
+ find . -name target/*asc.* -exec rm {} \;
+ scp target/*
usern...@people.apache.org:~/public_html/jspwiki-X.Y.Z-candidate-$RC
+
+## Run a vote
+
+Send the following to <d...@jspwiki.apache.org>:
+
+ Subject: [VOTE] Release JSPWiki version X.Y.Z
+
+ This is a release for Apache JSPWiki, version X.Y.Z.
+
+ It fixes the following issues:
+
https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12310732&version=<REPLACE>
+
+ *** Please download, test and vote by [3 working days after sending].
+
+ Note that we are voting upon the source (tag), binaries are provided for
convenience.
+
+ Source and binary files:
+ http://people.apache.org/~<REPLACE>/jspwiki-X.Y.Z-candidate-$RC
+
+ The tag to be voted upon:
+ http://svn.apache.org/repos/asf/jspwiki/tags/release-X.Y.Z/
+
+ JSPWiki's KEYS file containing PGP keys we use to sign the release:
+ http://www.apache.org/dist/jspwiki/KEYS
+
+Note that the PMC needs to vote upon the release before any release can be
made official.
+
+## Roll Out
+
+If the vote passes, roll out the release:
+
+ 1. **Publish Nexus repository**
+
+ 1. Login to <https://repository.apache.org> and select Staging
Repositories
+on the left under Build Promotion.
+
+ 2. Select the repository that was closed earlier, and click Release, using
+the description "Apache JSPWiki X.Y.Z"
+
+ 2. **Publish src and bin distributions to the [mirrors][]**
+
+ ssh people.apache.org
+ VERSION=X.Y.Z
+ PREVIOUSVERSION=X.Y.Z
+ CANDIDATE=C
+ cp -r ~/public_html/jspwiki-$VERSION-candidate-$CANDIDATE \
+ /www/www.apache.org/dist/jspwiki/jspwiki-$VERSION
+ cd /www/www.apache.org/dist/jspwiki
+ chgrp -R jspwiki jspwiki-$VERSION
+ chmod -R g+w jspwiki-$VERSION
+ rm -r /www/www.apache.org/dist/jspwiki/jspwiki-$PREVIOUSVERSION #
remove older versions
+
+ The last line is to remove the previous version, since only the most
recent
+version on a particular branch should be in the dist directory. Older versions
+are [archived][] automatically.
+
+ 3. Wait 24 hours for mirrors to sync
+
+ 4. Post link to the full release notes along with links to the major JIRA
+changes on the front page of the site
+
+## Announce the release
+
+Send the following from an apache.org address to <annou...@apache.org>,
+<u...@jspwiki.apache.org>, <d...@jspwiki.apache.org>:
+
+ Subject: [ANNOUNCE] Apache JSPWiki X.Y.Z released
+
+ The Apache JSPWiki team is pleased to announce the release of JSPWiki
X.Y.Z.
+
+ This is the <REPLACE> release of Apache JSPWiki, a feature-rich and
+ extensible WikiWiki engine built around the standard J2EE components.
+
+ The release is available here:
+ http://www.apache.org/dyn/closer.cgi/jspwiki/
+
+ The full change log is available here:
+ https://issues.apache.org/jira/browse/jspwiki/fixforversion/<REPLACE>
+
+ We welcome your help and feedback. For more information on how to
+ report problems, and to get involved, visit the project website at
+ http://jspwiki.apache.org/
+
+ The Apache JSPWiki Team
+
+## Add the next release to JIRA
+
+ 1. Add the [next version number to JIRA][]
+ 2. Mark the released version as "released" with a release date
+
+## Troubleshooting
+
+ 1. Cygwin mixes Windows path with cygdrive, so `mvn release:prepare` fails
on svn commit
+
+ Current workaround: perform release vÃa `cmd.exe`
+
+ 2. Avoid gpg signing prompt when using Maven release plugin
+
+ See [http://stackoverflow.com/q/14114528][stack_overflow_1]
+
+ 3. `mvn release:prepare` doesn't find svn credentials
+
+ On your settings.xml file you should have one <server /> entry for each of
the following ones:
+* `apache.snapshots.https`: to be able to deploy snapshots
+* `apache.releases.https`: to be able to deploy releases
+* `svn.apache.org`: to be able to create tags
+Alternatively, for the last one, you could pass -Dusername=[username]
-Dpassword=[password] to the mvn command
+(source: [http://stackoverflow.com/q/1255593][stack_overflow_2])
+
+ 4. Release fails after a tag has been generated and the pom versions have
been incremented
+
+ No need of `mvn release:rollback`, instead check out the tag and
`release:perform
-DconnectionUrl=scm:svn:https://svn.apache.org/COMPLETE-URL-TO-TAG`
+
+## Other links of interest
+
+* [Maven release plugin cheat sheet][lof_1]
+* [Publishing Maven Artifacts - setup your development environment][lof_2]
+* [Maven release plugin][lof_3]
+* Repository management with Nexus: [Chapter 11. Improved Releases with the
Nexus Staging Suite
+][lof_4]
+
+
+
+[Maven encryption capabilities]:
http://maven.apache.org/guides/mini/guide-encryption.html
+[PGP code signing keys]:
http://www.apache.org/dev/release-signing.html#generate
+[KEYS file]: http://svn.apache.org/repos/asf/jspwiki/dist/KEYS
+[Infrastructure site]:
http://www.apache.org/dev/release-signing.html#keys-policy
+[Infrastructure JIRA]: https://issues.apache.org/jira/browse/INFRA
+[setup the ssh keys]:
http://www.thegeekstuff.com/2008/11/3-steps-to-perform-ssh-login-without-password-using-ssh-keygen-ssh-copy-id/
+
+[Close]:
https://docs.sonatype.org/display/Repository/Closing+a+Staging+Repository
+
+[archived]: http://archive.apache.org/dist/jspwiki/
+[mirrors]: http://www.apache.org/dev/mirrors.html
+
+[next version number to JIRA]:
https://issues.apache.org/jira/plugins/servlet/project-config/jspwiki/versions
+
+[stack_overflow_1]: http://stackoverflow.com/q/14114528
+[stack_overflow_2]: http://stackoverflow.com/q/1255593
+[lof_1]:
https://confluence.sakaiproject.org/display/REL/Maven+release+plugin+cheat+sheet
+[lof_2]: http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env
+[lof_3]: http://maven.apache.org/maven-release/maven-release-plugin/
+[lof_4]: http://books.sonatype.com/nexus-book/reference/staging-sect-intro.html
\ No newline at end of file
