commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject svn commit: r928561 - /commons/proper/commons-site/trunk/src/site/xdoc/releases/release.xml
Date Mon, 29 Mar 2010 01:31:14 GMT
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) &lt;rdonkin@apache.org&gt;"
-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) &lt;rdonkin@apache.org&gt;"
-% 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) &lt;rdonkin@apache.org&gt;"
-% 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) &lt;rdonkin@apache.org&gt;"
-% 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) &lt;rdonkin@apache.org&gt;"
-      </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 &lt;commons-foo-1.2-src.tar.gz
-      a76169177e7a9b58118bcd993aff4a5e
-      % cat commons-foo-1.2-src.tar.gz.md5
-      a76169177e7a9b58118bcd993aff4a5e
-      
-      % openssl md5 &lt;commons-foo-1.2-src.zip
-      ca0ae8330f666dd1626108346e36f799
-      % cat commons-foo-1.2-src.zip.md5
-      ca0ae8330f666dd1626108346e36f799
-      
-      % openssl md5 &lt;commons-foo-1.2.tar.gz
-      460fa7ad1e9ee2b5c4acab4971402395
-      % cat commons-foo-1.2.tar.gz.md5 
-      460fa7ad1e9ee2b5c4acab4971402395
-      
-      % openssl md5 &lt;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 rdonkin@www.apache.org:~/
-    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 &lt;siteDirectory&gt;
-    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! 



Mime
View raw message