Author: psteitz
Date: Mon Mar 29 01:31:14 2010
New Revision: 928561
URL: http://svn.apache.org/viewvc?rev=928561&view=rev
Log:
First pass at updating releasing docs to reflect current practice.
Modified:
commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml
Modified: commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml
URL:
http://svn.apache.org/viewvc/commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml?rev=928561&r1=928560&r2=928561&view=diff
==============================================================================
--- commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml
(original)
+++ commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml Mon
Mar 29 01:31:14 2010
@@ -48,214 +48,26 @@
</p>
<p>
In particular, it is assumed:
+ <!-- TODO: make sure prepare.xml ensures the following are trun -->
<ul>
<li>
- The build version for the component has been updated to the release
number in pom.xml
+ The signed release candidate source and binary distributions are
available in ~/public_html/commons-foo-1.2-RCx
+ where RCx is the release candidate that passed the release vote.
</li>
<li>
- The build version for the component has been updated to the release
number in build.xml if
- you have a hand-created Ant buildfile.
+ At least one reviewer has verified the hashes and signatures
associated with the release artifacts.
</li>
<li>
- The release directory <code>tags/foo-1.2</code> has been created.
+ The release candidate was built from the tag, tags/foo-1.2-RCx.
+ </li>
+ <li>
+ The maven artifacts associated with the release are available in
~/public_html/commons-foo-1.2-RCx/maven.
</li>
</ul>
</p>
</subsection>
-
- <subsection name="1 Build Distribution Files">
- <p>
- Ensure commons-build is available as a sibling directory to the one you
- will be doing the build in. The most convenient way to do this is simply
- to check out commons-build into its usual place, then create a symbolic
- link to it:
- <pre>
- # we will be building in foo/tags/foo-1.2
- cd foo/tags
- # create a link from ./commons-build to wherever the trunk of
- # commons-build has been checked out
- ln -s {commons-build}/trunk commons-build
- </pre>
- </p>
- <p>
- Now do a clean build of the binary distribution.
- </p>
- <p>For Maven builds, it is assumed that there is a "dist" goal which
creates
- source and binary distributions in subdirectory target/distributions.
- <pre>
- $ cd foo/tags/foo-1.2
- $ maven clean
- $ maven dist
- </pre>
- </p>
- <p>
- For Ant builds, it is assumed that there is a "dist" target which
- creates source and binary distribution (.tgz, .zip) bundles.
- <pre>
- $ cd foo/tags/foo-1.2
- $ ant clean
- $ ant dist
- </pre>
- </p>
- <p>
- Review the generated documentation and in particular ensure that the
version number
- is correct.
- </p>
- </subsection>
-
- <subsection name='2 Create Checksums'>
- <p>
- MD5 is the standard hash algorithm used by Apache to allow users to verify
the integrity of releases.
- There are various applications which can be used to create md5 checksums.
- </p>
- <p>
- For example md5sum (on Linux):
- <pre>
- $ md5sum -b commons-foo-1.2-src.tar.gz > commons-foo-1.2-src.tar.gz.md5
- </pre>
- </p>
- <p>
- If possible, the format of the output should conform to the ASF repository
standard.
- Currently, this is <code>sum filename</code>. For example:
- </p>
- <pre>
- d1dcb0fbee884bb855bb327b8190af36 *commons-foo-1.2.tar.gz
- </pre>
- <p>
- Create md5 sums for the binary and source releases, both tarred and zipped
versions.
- These should be stored in files whose names are formed by appending
<code>.md5</code>.
- to each filename. So, you should end up with the following files:
- <pre>
- commons-foo-1.2-src.tar.gz.md5
- commons-foo-1.2-src.zip.md5
- commons-foo-1.2.tar.gz.md5
- commons-foo-1.2.zip.md5
- </pre>
- </p>
- </subsection>
-
- <subsection name='3 Sign Releases'>
- <p>
- OpenPGP (RFC2440) compatible detached signatures needed to be created for
all releases.
- Various applications can be used to create these signatures. For example,
- <a href='http://www.gnupg.org'>Gnu Privacy Guard</a>.
- </p>
- <p>
- See the <a
href="http://www.apache.org/dev/release-signing.html#faq";>Apache Release
Signing FAQ</a>
- for more information on release signing.
- </p>
- <p>
- Example:
- <pre>
-$ gpg --armor --output commons-foo-1.2-src.tar.gz.asc --detach-sig
commons-foo-1.2-src.tar.gz
-You need a passphrase to unlock the secret key for
-user: "Robert Burrell Donkin (CODE SIGNING KEY) <[email protected]>"
-1024-bit DSA key, ID B1313DE2, created 2003-01-15
- </pre>
- </p>
- <p>
- Signatures for all varieties of release need to be create. The signature
files should be
- named after the original with <code>.asc</code> suffixed.
- <pre>
-$ gpg --armor --output commons-foo-1.2-src.tar.gz.asc --detach-sig
commons-foo-1.2-src.tar.gz
-$ gpg --armor --output commons-foo-1.2-src.zip.asc --detach-sig
commons-foo-1.2-src.zip
-$ gpg --armor --output commons-foo-1.2.zip.asc --detach-sig commons-foo-1.2.zip
-$ gpg --armor --output commons-foo-1.2.tar.gz.asc --detach-sig
commons-foo-1.2.tar.gz
- </pre>
- </p>
- <p>
- If this is the first release you personally have done for Commons, then
your code
- signing public key must be added to the
- <a href='#Check KEYS file'><code>KEYS</code> file for Commons</a>.
- which is in the root of the Commons distribution directory
- (/www/apache.org/dist/commons/KEYS on people.apache.org).
- If this file is not present, it needs to be created.
- </p>
- </subsection>
-
-
- <subsection name='4 Verify the Releases'>
- <ul>
- <li>
- <strong>Verify signatures</strong><br/>
- Use another user to verify the signatures. (The user must have your
code-signing
- public key loaded into their key ring.) Here's an example using GnuPG:
- <pre>
-% gpg --verify commons-foo-1.2.tar.gz.asc commons-foo-1.2.tar.gz
-gpg: Signature made 03/01/03 19:34:31 GMT using DSA key ID B1313DE2
-gpg: Good signature from "Robert Burrell Donkin (CODE SIGNING KEY)
<[email protected]>"
-% gpg --verify commons-foo-1.2.zip.asc commons-foo-1.2.zip
-gpg: Signature made 03/01/03 19:34:05 GMT using DSA key ID B1313DE2
-gpg: Good signature from "Robert Burrell Donkin (CODE SIGNING KEY)
<[email protected]>"
-% gpg --verify commons-foo-1.2-src.zip.asc commons-foo-1.2-src.zip
-gpg: Signature made 03/01/03 19:33:42 GMT using DSA key ID B1313DE2
-gpg: Good signature from "Robert Burrell Donkin (CODE SIGNING KEY)
<[email protected]>"
-% gpg --verify commons-foo-1.2-src.tar.gz.asc commons-foo-1.2-src.tar.gz
-gpg: Signature made 03/01/03 19:32:56 GMT using DSA key ID B1313DE2
-gpg: Good signature from "Robert Burrell Donkin (CODE SIGNING KEY)
<[email protected]>"
- </pre>
- </li>
- <li>
- <strong>Check Sums</strong><br/>.
- Verify md5 check sums. If you can, use another application to double
check the sums. Here
- verifications are performed using openssl.
- <pre>
- % openssl md5 <commons-foo-1.2-src.tar.gz
- a76169177e7a9b58118bcd993aff4a5e
- % cat commons-foo-1.2-src.tar.gz.md5
- a76169177e7a9b58118bcd993aff4a5e
-
- % openssl md5 <commons-foo-1.2-src.zip
- ca0ae8330f666dd1626108346e36f799
- % cat commons-foo-1.2-src.zip.md5
- ca0ae8330f666dd1626108346e36f799
-
- % openssl md5 <commons-foo-1.2.tar.gz
- 460fa7ad1e9ee2b5c4acab4971402395
- % cat commons-foo-1.2.tar.gz.md5
- 460fa7ad1e9ee2b5c4acab4971402395
-
- % openssl md5 <commons-foo-1.2.zip
- d5f98c73f2450e09cc2b1af9509934f0
- % cat commons-foo-1.2.zip.md5
- d5f98c73f2450e09cc2b1af9509934f0
- </pre>
- </li>
- </ul>
- </subsection>
-
-
- <subsection name='5 Upload Releases'>
- <p>
- Upload the following to your home directory on people.apache.org:
- <ul>
- <li>all the release distributions</li>
- <li>the detached signature files (<code>.asc</code>) for these
releases</li>
- <li>the md5 sums (<code>.md5</code>) for these releases</li>
- <li>the release notes. (If you're using Maven, you may need to create
a stripped down plain text
- version.)</li>
- </ul>
- </p>
- <p>
- A tip is to tar and gz everything and upload it all together:
- <pre>
- % scp release.tar.gz [email protected]:~/
- release.tar.gz 100% |*********************************| 841 KB
00:46
- % ssh -l rdonkin www.apache.org
- </pre>
- </p>
- <p>
- Untar in a working directory (named <code>release</code>, say).
- Remember to make sure that the group is <em>commons</em>,
- that they are world readable and that they are group read-writable.
- <pre>
- chgrp commons release/*
- chmod 664 release/* # rw-rw-r--
- </pre>
- </p>
- </subsection>
- <subsection name='6 Move Releases Into Distribution Directories'>
+ <subsection name='1 Move Releases Into Distribution Directories'>
<p>
Change directory to the distribution directory for your component:
<pre>
@@ -267,21 +79,21 @@ gpg: Good signature from "Robert Burrell
All source versions live in the source subdirectory.
</p>
<pre>
- mv ~/release/commons-foo-1.2-src* source
+ mv ~/public_html/foo-1.2-RCx/commons-foo-1.2-src* source
</pre>
<p>
Move the binary distributions, their detached signatures and md5 sums into
position.
All binary versions live in the <em>binaries</em> subdirectory.
</p>
<pre>
- mv ~/release/commons-foo-1.2* binaries
+ mv ~/~/public_html/foo-1.2-RCx/commons-foo-1.2* binaries
</pre>
<p>
Double check the permissions for binaries and source distributions.
</p>
</subsection>
- <subsection name='7 Update Release Directory'>
+ <subsection name='2 Update Release Directory'>
<p>
<strong>Update README</strong><br/>
The contents of the <code>README.html</code> are displayed at the bottom
of the html
@@ -354,7 +166,14 @@ gpg: Good signature from "Robert Burrell
</p>
</subsection>
- <subsection name='8 Deploy Maven Artifacts to Java-Repository'>
+ <subsection name='3 Deploy Maven Artifacts to Java-Repository'>
+ <!--
+ TODO: improve this section to include recommendation to move to
+ org.apache.commons groupId and explain how to edit maven metadata.
+ Make sure prepare includes recommendation to install locally with
+ mvn -Prc -DcreateChecksum=true install so jars get signed and hashed
+ and then copy from there
+ -->
<p>
The ASF Java Respository is the home for distributions in jar format.
Your Maven artifacts (jar and pom, files) should be placed in
@@ -375,7 +194,7 @@ gpg: Good signature from "Robert Burrell
</p>
</subsection>
- <subsection name='9 Test Main Site Downloads'>
+ <subsection name='4 Test Main Site Downloads'>
<p>
You should now be able to get the new release from the main Apache web
site
(<code>http://www.apache.org/dist/commons/foo/</code>).
@@ -402,19 +221,19 @@ gpg: Good signature from "Robert Burrell
</p>
</subsection>
- <subsection name="10 Update Component WebSite">
+ <subsection name="5 Update Component WebSite">
<strong>Publish Updated Website</strong>
<p>
- On your own machine, ensure that the project.xml contains a
<siteDirectory>
- tag that points to /www/commons.apache.org/foo, then run:
+ Run
<pre>
- maven -Dmaven.username=yourapacheid site:deploy
+ mvn site:deploy
</pre>
+ to deploy the new component website.
</p>
<p>
On people.apache.org, verify that the directory has been updated, and that
the
file and directory permissions are correct (readable by all, not writeable
by
- world).
+ world, but group writeable).
</p>
<p>
Note that the files are transferred to the real web site only every
@@ -445,32 +264,7 @@ gpg: Good signature from "Robert Burrell
</p>
</subsection>
- <subsection name='11 Update Commons Web Site'>
- <p>
- If you are creating a component site for the first time, then you will
need to
- update file commons-build/menus/components-items.ent in subversion and
publish
- the updated commons site.
- </p>
- <p>
- To update the commons site:
- <ul>
- <li>check out the entire commons/trunks-proper directory (the build process
- needs all the other components checked out).</li>
- <li>cd commons/trunks-proper/commons-build</li>
- <li>edit downloads/downloads.xml as necessary</li>
- <li>maven site:generate</li>
- <li>ant -f build-downloads.xml</li>
- <li>maven -Dmaven.username=yourapacheid site:deploy</li>
- <li><strong>check that the cgi scripts in the deployed site on
- people.apache.org are executable</strong> (if not chmod 775 the cgi
- scripts)</li>
- </ul>
- Note that the website is actually served from another machine, so it may
take a
- few hours until those changes are transferred to the actual webserver host
machine.
- </p>
- </subsection>
-
- <subsection name='12 Create Announcements'>
+ <subsection name='6 Create Announcements'>
<p>
Announce the availability of the new release.
You can probably use the news item create earlier as a basis for the
announcement body.
@@ -490,17 +284,12 @@ gpg: Good signature from "Robert Burrell
</p>
</subsection>
- <subsection name='13 Post Release Update'>
+ <subsection name='7 Post Release Update'>
<p>
That's it! The release is out there - but there is still some tidying up
to be done.
</p>
<ul>
<li>
- <strong>Update Build Version Number</strong>
- Update build number found in <code>build.xml</code> in the trunk. This
should be
- updated to a <code>dev</code> release, eg change "1.2" to "1.3-dev"
- </li>
- <li>
<strong>Update currentVersion</strong>
Update currentVersion found in <code>pom.xml</code> in the trunk. This
should be
updated to a <code>SNAPSHOT</code> release, eg change "1.2" to
"1.3-SNAPSHOT"
@@ -508,7 +297,7 @@ gpg: Good signature from "Robert Burrell
</ul>
</subsection>
- <subsection name='14 Update JIRA'>
+ <subsection name='8 Update JIRA'>
<p>
Check in JIRA for all bugs which have been marked <code>LATER</code> and
reopen them.
If you need some changes made to JIRA (for example, a new version number
adding)
@@ -520,7 +309,7 @@ gpg: Good signature from "Robert Burrell
</p>
</subsection>
- <subsection name="15 Miscellaneous">
+ <subsection name="9 Miscellaneous">
<p>
There are some scripts available that help to automate some of these steps.
In particular, see the following shell scripts in subversion under
@@ -533,7 +322,7 @@ gpg: Good signature from "Robert Burrell
</p>
</subsection>
- <subsection name="16 DOAP file">
+ <subsection name="10 DOAP file">
<p>
Update the component's <a
href="http://projects.apache.org/guidelines.html";>DOAP file</a>
with details of the released version:
@@ -554,8 +343,6 @@ gpg: Good signature from "Robert Burrell
</subsection>
</section>
-
-
<section name='Feedback'>
<p>
Feedback - yes please!
