incubator-isis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From danhayw...@apache.org
Subject svn commit: r1126347 - in /incubator/isis/trunk/src: docbkx/guide/isis-contributors-guide.xml site/apt/downloads.apt.vm
Date Mon, 23 May 2011 07:29:06 GMT
Author: danhaywood
Date: Mon May 23 07:29:05 2011
New Revision: 1126347

URL: http://svn.apache.org/viewvc?rev=1126347&view=rev
Log:
minor fixes to downloads page and contributors guide

Modified:
    incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml
    incubator/isis/trunk/src/site/apt/downloads.apt.vm

Modified: incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml?rev=1126347&r1=1126346&r2=1126347&view=diff
==============================================================================
--- incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml (original)
+++ incubator/isis/trunk/src/docbkx/guide/isis-contributors-guide.xml Mon May 23 07:29:05 2011
@@ -3672,8 +3672,8 @@ for a in `find isis -type d -print` ; do
       <title>Formal Release</title>
 
       <abstract>
-        <para>This chapter describes the steps that make up a formal release.
-        </para>
+        <para>This chapter describes the steps that make up a formal
+        release.</para>
       </abstract>
 
       <para>Before starting off the release process it is essential to gain
@@ -3788,7 +3788,7 @@ for a in `find isis -type d -print` ; do
 
           <para>Instead, the tool can be run from the command-line; a JAR
           binary of the tool has been checked into the <emphasis>Apache
-          Isis</emphasis> codebase. </para>
+          Isis</emphasis> codebase.</para>
 
           <para>First, clean up any generated artifacts:</para>
 
@@ -3803,7 +3803,8 @@ for a in `find isis -type d -print` ; do
   *.java.hsp \
   *.ucd *.ucls \
   *-LICENSE.txt \
-  fop-cust.xsl html-cust.xsl *.ent *.dtd *.pdn catalog.xml *.mod usage.txt screen.css docbook.cat \
+  fop-cust.xsl html-cust.xsl *.ent *.dtd *.pdn catalog.xml \
+  *.mod usage.txt screen.css docbook.cat \
   org.apache.isis.viewer.wicket.ui.ComponentFactory \
   fixture-data test.data example.ldif slapd.conf \
   .plxarc MANIFEST.MF \
@@ -3984,1017 +3985,1031 @@ licenses to remove from supplemental-mod
       <sect1>
         <title>Contributor (Release Manager) Prerequisites</title>
 
-        <para>In order that a contributor can make a release it is necessary
-        for them to have generated a key and had that key recognized by other
-        members of the ASF.</para>
-
-        <para>For background information on this topic, see the <ulink
-        url="http://www.apache.org/dev/release-signing.html">release signing
-        page</ulink> and the <ulink
-        url="http://www.apache.org/dev/openpgp.html#generate-key">openpgp
-        page</ulink> on the Apache wiki.</para>
+        <sect2>
+          <title>Key Generation</title>
+
+          <para>In order that a contributor can make a release it is necessary
+          for them to have generated a key and had that key recognized by
+          other members of the ASF. See the key generation appendix, <xref
+          linkend="apx.KeyGeneration" />, for more details.</para>
+        </sect2>
 
         <sect2>
-          <title>Install and Configure gpg</title>
+          <title>Update Maven Settings file
+          (<filename>~/.m2/settings.xml</filename>)</title>
 
-          <para>Download and install GnuPG (gpg), version 1.4.10 or
-          higher.</para>
+          <para>The Maven release plugin will automatically sign the release,
+          however it is necessary to update the
+          <filename>~/.m2/settings.xml</filename> file with your GPG
+          passphrase in order that it can use your secret key. This is defined
+          under a profile so that it is activated only when we perform a
+          release (as defined by <package>[org,apache:apache]</package> parent
+          <acronym>POM</acronym>.</para>
 
-          <para>Then, edit <filename>~/.gnupg/gpg.conf</filename> (on Windows,
-          the file to edit is
-          <filename>C:\Users\xxx\AppData\Roaming\gnupg\gpg.conf</filename>) so
-          that the default is to generate a strong key:</para>
+          <para>Therefore, make the following</para>
 
-          <programlisting>{code}
-personal-digest-preferences SHA512
-cert-digest-algo SHA512
-default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
-{code}</programlisting>
+          <programlisting>&lt;settings&gt;
+  ...
+  &lt;profiles&gt;
+    &lt;profile&gt;
+      &lt;id&gt;apache-release&lt;/id&gt;
+      &lt;properties&gt;
+    &lt;gpg.passphrase&gt;xxx xxx xxx xxx xxx xxx xxx&lt;/gpg.passphrase&gt;
+      &lt;/properties&gt;
+    &lt;/profile&gt;
+  &lt;/profiles&gt;
+&lt;/settings&gt;</programlisting>
+
+          <para>In addition, to allow the release plugin to tag SVN changes,
+          you must either add in your LDAP username/password or configure
+          .ssh:</para>
+
+          <programlisting>&lt;settings&gt;
+  ...
+  &lt;servers&gt;
+    ...
+    &lt;server&gt;
+      &lt;id&gt;apache.releases.https&lt;/id&gt;
+      &lt;username&gt;xxxx&lt;/username&gt;
+      &lt;password&gt;xxxx&lt;/password&gt;
+    &lt;/server&gt;
+  &lt;/servers&gt;
+  ...
+&lt;/settings&gt;</programlisting>
         </sect2>
+      </sect1>
+
+      <sect1 id="sec.MavenReleasePrepare">
+        <title>Preparing a Release (<code>mvn release:prepare</code>)</title>
+
+        <para>We recommend creating release candidates from branches, and then
+        the final release from trunk.</para>
 
         <sect2>
-          <title>Key Generation</title>
+          <title>Branch (release candidates only)</title>
 
-          <para>The ASF requires that keys are signed with a key (or subkey)
-          based on RSA 4096 bits. To do this:</para>
+          <para>First, create a branch:</para>
 
-          <programlisting>$ gpg --gen-key
-gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
+          <programlisting>svn mkdir https://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating \
+   -m "branching to create x.x.x-RCn-incubating"
+svn copy https://svn.apache.org/repos/asf/incubator/isis/trunk \
+    https://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating/trunk \
+    -m "copying trunk to branches/x.x.x-RCn-incubating"</programlisting>
 
-Please select what kind of key you want:
-   (1) RSA and RSA (default)
-   (2) DSA and Elgamal
-   (3) DSA (sign only)
-   (4) RSA (sign only)
-Your selection?</programlisting>
+          <para>Now create a workspace for this branch. The easiest approach
+          is to copy <filename>trunk</filename> and perform an <code>svn
+          switch</code>:</para>
 
-          <para>Specify RSA key:</para>
+          <programlisting>cd .../trunk   # your local workspace for isis/trunk
 
-          <programlisting>Your selection? 1
+cd ..
+mkdir -p branches/x.x.x-RCn-incubating
+cp -R trunk branches/x.x.x-RCn-incubating/trunk
 
-RSA keys may be between 1024 and 4096 bits long.
-What keysize do you want? (2048)</programlisting>
+cd branches/x.x.x-RCn-incubating/trunk
+svn switch https://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating/trunk</programlisting>
 
-          <para>Specify key length as 4096 bits:</para>
+          <para>Because the release is being performed in a branch, it is then
+          necessary to edit the parent <filename>pom.xml</filename> in
+          <package>[oai:isis-parent]</package>. Change
+          <emphasis>trunk</emphasis> to
+          <emphasis>branches/x.x.x-RCn-incubating/trunk</emphasis> for each of
+          the children of the <code>&lt;scm&gt;</code> tag:</para>
 
-          <programlisting>What keysize do you want? (2048) 4096
-Requested keysize is 4096 bits
+          <programlisting>&lt;scm&gt;
+  &lt;connection&gt;
+    scm:svn:http://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating/trunk/
+  &lt;/connection&gt;
+  &lt;developerConnection&gt;
+    scm:svn:https://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating/trunk/
+  &lt;/developerConnection&gt;
+  &lt;url&gt;
+    http://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating/trunk/
+  &lt;/url&gt;
+&lt;/scm&gt;</programlisting>
 
-Please specify how long the key should be valid.
-         0 = key does not expire
-      &lt;n&gt;  = key expires in n days
-      &lt;n&gt;w = key expires in n weeks
-      &lt;n&gt;m = key expires in n months
-      &lt;n&gt;y = key expires in n years
-Key is valid for? (0)</programlisting>
+          <para>The commit the <filename>pom.xml</filename> file.</para>
+        </sect2>
 
-          <para>Specify key as non-expiring:</para>
+        <sect2>
+          <title>Dry run</title>
 
-          <programlisting>Key is valid for? (0) 0
-Key does not expire at all
-Is this correct? (y/N) y
+          <para>The release:prepare command updates all POMs, creates a tag.
+          It's common practice to perform a dry run first:</para>
 
-You need a user ID to identify your key; the software constructs the user ID
-from the Real Name, Comment and Email Address in this form:
-    "Heinrich Heine (Der Dichter) &lt;heinrichh@duesseldorf.de&gt;"
+          <programlisting>mvn release:clean release:prepare -P apache-release -D dryRun=true</programlisting>
 
-Real name: </programlisting>
+          <para>Specify version as
+          <emphasis>0.x.x-RCn-incubating</emphasis>.</para>
 
-          <para>Enter your name, email and comment:</para>
+          <para></para>
 
-          <itemizedlist>
-            <listitem>
-              <para>use your apache.org email</para>
-            </listitem>
+          <para>*** more detail required here.</para>
 
-            <listitem>
-              <para>the comment should be "CODE SIGNING KEY" </para>
-            </listitem>
-          </itemizedlist>
+          <para></para>
+        </sect2>
 
-          <programlisting>Real name: Xxx Xxxxxxxxx
-Email address: &lt;xxx@apache.org&gt;
-Comment: CODE SIGNING KEY
-You selected this USER-ID:
-    "Xxx Xxxxxxxxx (CODE SIGNING KEY) &lt;xxx@apache.org&gt;"
+        <sect2>
+          <title>Release Proper</title>
 
-Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
+          <para>Assuming that the dry run has succeeded, it's time to create
+          the release proper</para>
 
-You need a Passphrase to protect your secret key.
-Enter passphrase:</programlisting>
+          <programlisting>mvn release:clean release:prepare -P apache-release -D skipTests=true</programlisting>
 
-          <para>Provide a passphrase to secure your key. </para>
+          <para>Specify version as
+          <emphasis>0.x.x-RCn-incubating</emphasis>.</para>
 
-          <programlisting>Enter passphrase:
-Repeat passphrase:</programlisting>
+          <para><note>
+              <para>If you are in Europe the <code>mvn release:prepare</code>
+              command almost always fails at the last step, with a message
+              like:</para>
 
-          <para>GPG will goes on to generate your key:</para>
+              <programlisting>[ERROR]
+ BUILD FAILURE
+[INFO]
+ ------------------------------------------------------------------------
+[INFO]
+ Unable to tag SCM
+Provider message:
+The svn tag command failed.
+Command output:
+svn: No such revision 936951</programlisting>
 
-          <programlisting>We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-...+++++
-.........................+++++
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-....+++++
-...+++++
-gpg: key nnnnnnnn marked as ultimately trusted
-public and secret key created and signed.
+              <para>This is due to the SVN mirroring in place between Europe
+              and the master in the US. When you make a commit, it isn't
+              immediately available in Europe to svn up to. Just wait 10 secs
+              and repeat the mvn release:prepare command for it to restart
+              where it left off.</para>
+            </note><note>
+              <para>If other things go wrong, then <code>mvn
+              release:clean</code> will do most of the cleaning up in the
+              event of failures.</para>
+            </note></para>
 
-gpg: checking the trustdb
-gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
-gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
-pub   4096R/nnnnnnnn yyyy-mm-dd
-      Key fingerprint = xxxx xxxx xxxx xxxx xxxx  xxxx xxxx xxxx xxxx xxxx
-uid                  Xxx Xxxxxx &lt;xxx@apache.org&gt;
-sub   4096R/kkkkkkkk yyyy-mm-dd</programlisting>
+          <para></para>
 
-          <para>The public key with id nnnnnnnn should now be stored in
-          <filename>~/.gnupg/pubring.pgp</filename> (on Windows 7, this is in
-          c<filename>:/Users/xxx/AppData/Roaming/gnupg/pubring.pgp</filename>).
-          </para>
-
-          <para>To confirm the key has been generated, use:</para>
-
-          <programlisting>$ gpg --list-keys --fingerprint</programlisting>
-
-          <para>The key Id is the one true way to identify the key, and is
-          also the last 8 digits of the fingerprint. The corresponding secret
-          key for id nnnnnnnn is stored in
-          <filename>~/.gnupg/secring.pgp</filename> (on Windows 7, this is in
-          <filename>c:/Users/xxx/AppData/Roaming/gnupg/secring.pgp</filename>).</para>
-
-          <para>It's also worth confirming the key has the correct preference
-          of algorithms (reflecting the initial configuration we did earlier).
-          For this, enter the gpg shell for your new key:</para>
+          <para>*** more detail required here.</para>
 
-          <para><programlisting>$ gpg --edit-key nnnnnnnnn
-gpg&gt;</programlisting>where nnnnnnnn is your key id. Now, use the 'showpref'
-          subcommand to list details:</para>
+          <para></para>
 
-          <programlisting>gpg&gt; showpref
-[ultimate] (1). Xxx Xxxxxxxx (CODE SIGNING KEY) &lt;xxx@apache.org&gt;
-     Cipher: AES256, AES192, AES, CAST5, 3DES
-     Digest: SHA512, SHA384, SHA256, SHA224, SHA1
-     Compression: ZLIB, BZIP2, ZIP, Uncompressed
-     Features: MDC, Keyserver no-modify
+          <para>*** check the archetype versions; may need manual tweaking
+          beforehand if doesn't bump versions correctly?</para>
 
-gpg&gt;</programlisting>
+          <para></para>
+        </sect2>
 
-          <para>The Digest line should list SHA-512 first and SHA-1 last.
-          </para>
+        <sect2>
+          <title>Post-build sanity check</title>
+
+          <para>You should end up with artifacts in your local repo with the
+          new version <emphasis>0.x.x-RCn-incubating</emphasis>. As a sanity
+          check, use the quickstart archetype to generate the application, and
+          make sure that the generated application runs ok.</para>
 
-          <para>Finally, remember to take a backup of your key and the keyring
-          (ie, backup the <filename>.gnupg</filename> directory and its
-          contents).</para>
+          <para>If you find problems and the release was performed on trunk
+          (rather than a branch) then you may need to revert the changes. The
+          release commands make and commit changes to the project's
+          <filename>pom.xml</filename> files and they create a tag in SVN;
+          you'll need to revert the <filename>pom.xml</filename> files and
+          delete the tag from SVN.</para>
         </sect2>
+      </sect1>
+
+      <sect1 id="sec.UploadReleaseForVoting">
+        <title>Upload Release for Voting</title>
+
+        <para>Once the release has been built locally, it should be uploaded
+        for voting. This consists of two things: uploading the source release,
+        and deploying the Maven artifacts to a staging directory.</para>
 
         <sect2>
-          <title>Subkey Generation</title>
+          <title>Upload Source Zip</title>
 
-          <para>It's recommended to use a subkey with an expiry date to sign
-          releases, rather than your main, non-expiring subkey. If a subkey is
-          present, then gpg will use it in preference to the main key.</para>
+          <para>The source ZIP can be found in the <filename>target</filename>
+          directory of the parent project (ie at
+          <filename>trunk/target</filename>), along with its signature. The
+          two files of interest are:</para>
 
-          <para>Enter the gpg shell using (the identifier of) your main
-          key:</para>
+          <itemizedlist>
+            <listitem>
+              <para><filename>isis-parent-0.x.x-RCn-incubating-incubating-source-release.zip</filename>,
+              and</para>
+            </listitem>
 
-          <programlisting>gpg --edit-key xxxxxxxx
-gpg&gt;</programlisting>
+            <listitem>
+              <para><filename>isis-parent-0.x.x-RCn-incubating-incubating-source-release.zip.asc</filename></para>
+            </listitem>
+          </itemizedlist>
 
-          <para>Type 'addkey' to create a subkey, and enter your passphrase
-          for the main key:</para>
+          <para>Upload these to your public_html directory on
+          people.apache.org so that they can be referenced in your vote email
+          (see <xref linkend="sec.Voting" />).</para>
+        </sect2>
 
-          <para><programlisting>gpg&gt; addkey
-Key is protected.
-[enter your secret passphrase]
+        <sect2>
+          <title>Deploying Binaries to Staging Repository (<classname>mvn
+          release:perform</classname>)</title>
 
-You need a passphrase to unlock the secret key for
-user: "Dan Haywood (CODE SIGNING KEY) &lt;danhaywood@apache.org&gt;"
-4096-bit RSA key, ID xxxxxxxx, created 2011-02-01
+          <para>The Apache staging repository lives on the Nexus repository
+          hosted at <ulink
+          url="https://repository.apache.org">https://repository.apache.org</ulink>.
+          The process of uploading will create a staging repository that is
+          associated with the host (IP address) performing the release. Once
+          the repository is staged, the newly created staging repository is
+          "closed" in order to make it available to others.</para>
 
-Please select what kind of key you want:
-   (3) DSA (sign only)
-   (4) RSA (sign only)
-   (5) Elgamal (encrypt only)
-   (6) RSA (encrypt only)
-Your selection?</programlisting></para>
+          <sect3>
+            <title>Perform the Release</title>
 
-          <para>Select (4) to choose an RSA key for signing:</para>
+            <para>The command to stage the release is:</para>
 
-          <programlisting>Your selection? 4
+            <programlisting>mvn release:perform -Papache-release</programlisting>
 
-RSA keys may be between 1024 and 4096 bits long.
-What keysize do you want? (2048) 4096
+            <para></para>
 
-Requested keysize is 4096 bits
+            <para>*** further details required here.</para>
 
-Please specify how long the key should be valid.
-         0 = key does not expire
-      &lt;n&gt;  = key expires in n days
-      &lt;n&gt;w = key expires in n weeks
-      &lt;n&gt;m = key expires in n months
-      &lt;n&gt;y = key expires in n years
-Key is valid for?</programlisting>
+            <para></para>
+          </sect3>
 
-          <para>Specify that the key is valid for 1 year:</para>
+          <sect3>
+            <title>Check the Repository</title>
 
-          <programlisting>Key is valid for? (0) 1y
+            <para>This will put release artifacts into a newly created staging
+            repository . You will need to log into repository.apache.org to
+            see it.</para>
 
-Key expires at yy/MM/dd hh:mm:ss
-Is this correct? (y/N) y
-Really create? (y/N) y
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-...+++++
-.+++++
+            <para>If nothing appears in a staging repo you should stop here
+            and work out why.</para>
 
-pub  4096R/xxxxxxxx  created: yyyy-mm-dd  expires: never       usage: SC
-                     trust: ultimate      validity: ultimate
-sub  4096R/xxxxxxxx  created: yyyy-mm-dd  expires: never       usage: E
-sub  4096R/xxxxxxxx  created: yyyy-mm-dd  expires: yyYY-mm-dd  usage: S
-[ultimate] (1). Dan Haywood (CODE SIGNING KEY) &lt;danhaywood@apache.org&gt;
+            <para>Assuming that the repo has been populated, make a note of
+            its repo id; this is needed for the voting thread (see <xref
+            linkend="sec.VotingThread" />).</para>
 
-gpg&gt;</programlisting>
+            <para></para>
 
-          <para>Quit the gpg shell; you now have a subkey.</para>
-        </sect2>
+            <para>*** confirm the procedure described here.</para>
 
-        <sect2>
-          <title>Generate a Revocation Certificate</title>
+            <para></para>
+          </sect3>
+
+          <sect3>
+            <title>Close the Repository</title>
 
-          <para>It's good practice to generate a number of revocation
-          certificates so that the key can be revoked if it happens to be
-          compromised. See <ulink
-          url="http://www.apache.org/dev/openpgp.html#revocation-certs">the
-          gpg page</ulink> on the Apache wiki for more background on this
-          topic.</para>
+            <para>After checking that the staging repository contains the
+            artifacts that you expect you should close the staging repository.
+            This will make it available so that people can check the
+            release.</para>
 
-          <para>First, generate a "no reason specified" key:</para>
+            <para></para>
 
-          <programlisting>$ gpg --output revoke-nnnnnnnn-0.asc --armor --gen-revoke nnnnnnnn
+            <para>*** further details required here.</para>
 
-sec  4096R/nnnnnnnn yyyy-mm-dd Xxx Xxxxxxx (CODE SIGNING KEY) &lt;xx@apache.org&gt;
-Create a revocation certificate for this key? (y/N) Y
+            <para></para>
+          </sect3>
+        </sect2>
+      </sect1>
 
-Please select the reason for the revocation:
-  0 = No reason specified
-  1 = Key has been compromised
-  2 = Key is superseded
-  3 = Key is no longer used
-  Q = Cancel
-(Probably you want to select 1 here)
-Your decision?</programlisting>
+      <sect1 id="sec.Voting">
+        <title>Voting</title>
 
-          <para>Select 0.</para>
+        <para>Once the artifacts have been uploaded, you can call a vote.
+        Votes last for 72 hours and require a +3 vote from members. While
+        incubating, this vote should be performed on the
+        isis-dev@incubator.apache.org mailing list, and then repeated on the
+        incubator@apache.org mailing list.</para>
 
-          <programlisting>Your decision? 0
+        <sect2 id="sec.VotingThread">
+          <title>Start voting thread on isis-dev@incubator.a.o</title>
 
-Enter an optional description; end it with an empty line:</programlisting>
+          <para>You can use the following boilerplate for the vote on
+          isis-dev.</para>
 
-          <para>Provide a description:</para>
+          <para>Use the following subject:</para>
 
-          <programlisting>&gt; Generic certificate to revoke key, generated at time of key creation.
-&gt;
-Reason for revocation: No reason specified
-Generic certificate to revoke key, generated at time of key creation.
-Is this okay? (y/N)</programlisting>
+          <programlisting>[VOTE] Apache Isis release candidate 0.x.x-RCn-incubating</programlisting>
 
-          <para>Confirm this is ok.</para>
+          <para>And use the following body:</para>
 
-          <programlisting>Is this okay? y
+          <programlisting>I've staged a release candidate for Apache Isis, namely 0.x.x-RCn-incubating.
 
-You need a passphrase to unlock the secret key for
-user: "Xxx Xxxxxxx (CODE SIGNING KEY) &lt;xxx@apache.org&gt;"
-4096-bit RSA key, ID nnnnnnnn, created yyyy-mm-dd
+The signed source ZIP can be downloaded from my home directory on people.apache.org:
+* http://people.apache.org/~uuuuuuuu/isis-parent-0.x.x-RCn-incubating-source-release.zip (zip file), and
+* http://people.apache.org/~uuuuuuuu/isis-parent-0.x.x-RCn-incubating-source-release.zip.asc (signature)
 
-Enter passphrase:</programlisting>
+The code has been tagged as tags/0.x.x-RCn-incubating.
 
-          <para>Enter a passphrase:</para>
+In addition, the Maven artifacts have been staged to staging repository on repository.apache.org:
+* https://repository.apache.org/content/repositories/orgapacheisis-zzz/
 
-          <programlisting>Enter passphrase:
-Revocation certificate created.
+The RAT checks have passed (see contributors guide for files that are considered as being excluded).
 
-Please move it to a medium which you can hide away; if Mallory gets
-access to this certificate he can use it to make your key unusable.
-It is smart to print this certificate and store it away, just in case
-your media become unreadable.  But have some caution:  The print system of
-your machine might store the data and make it available to others!</programlisting>
+Please verify the release and cast your vote.  The vote will be open for 72 hours.
 
-          <para>The file 'revoke-nnnnnnnn-0.asc' should be created: Then,
-          backup this file.</para>
+[ ] +1
+[ ]  0
+[ ] -1</programlisting>
 
-          <para>Now repeat the process to create two further revocation
-          certificates: </para>
+          <para>where:</para>
 
           <itemizedlist>
             <listitem>
-              <para><code>gpg --output revoke-nnnnnnnn-1.asc --armor
-              --gen-revoke nnnnnnnn</code></para>
-
-              <para>Specify reason as "1 = Key has been compromised"</para>
+              <para><emphasis>uuuuuuuu</emphasis> is your Apache LDAP
+              username</para>
             </listitem>
 
             <listitem>
-              <para><code>gpg --output revoke-nnnnnnnn-3.asc --armor
-              --gen-revoke nnnnnnnn</code></para>
-
-              <para>Specify reason as "3 = Key is no longer used"</para>
+              <para><emphasis>zzz</emphasis> is the newly created staging
+              repository, from above.</para>
             </listitem>
           </itemizedlist>
-
-          <para>Backup these files also.</para>
-
-          <para><note>
-              <para>if you find that you need to revoke your certificate, this
-              <ulink
-              url="http://www.hackdiary.com/2004/01/18/revoking-a-gpg-key">blog
-              post</ulink> explains how.</para>
-            </note></para>
         </sect2>
 
         <sect2>
-          <title>Publish Key</title>
+          <title>Other contributors cast their vote</title>
+
+          <para>It is the responsibility of other contributors (or any ASF
+          member) to cast their vote on the release. This section provides
+          some guidance on this process.</para>
 
-          <para>It is also necessary to publish your key. There are several
-          places where this should be done. In most cases, you'll need the
-          "armored" " (ie ASCII) representation of your key. This can be
-          generated using:</para>
+          <sect3>
+            <title>Verifying the source release artifacts</title>
 
-          <programlisting>$ gpg --armor --export nnnnnnnn &gt; nnnnnnnn.asc</programlisting>
+            <para>Download both the ZIP and .ASC files from the location
+            specified in the voting email. To verify that the signature is
+            correct, use:</para>
 
-          <para>where nnnnnnnn is the id of your public key.</para>
+            <programlisting>gpg --verify isis-parent-x.x.x-RCn-incubating.zip.asc isis-parent-x.x.x-RCn-incubating.zip</programlisting>
 
-          <para>You'll also need the fingerprint of your key. This can be
-          generated using:</para>
+            <para>The ZIP file should then be unpacked.</para>
 
-          <programlisting>$ gpg --fingerprint nnnnnnnn</programlisting>
+            <para>Once unpacked, it is recommended that voters at a minimum
+            sanity check the contents, as per <xref
+            linkend="sec.SanityCheck" />.</para>
 
-          <para>The output from this command includes a line beginning "Key
-          fingerprint", followed by a (space delimited) 40 character
-          hexadecimal fingerprint. The last 8 characters should be the same as
-          the key id (nnnnnnnn).</para>
+            <para>In particular, when building locally, confirm that the
+            versions in your local repository
+            (<filename>~/.m2/repository/org/apache/isis</filename>) are
+            correct.</para>
+          </sect3>
 
           <sect3>
-            <title>Publish to a public key server</title>
+            <title>Verifying the binary release artifacts</title>
+
+            <para>Optionally, voters can verify the binary releases (in the
+            Maven staging repository).</para>
 
-            <para>To a publish your key to a public key server (eg the MIT key
-            server hosted at <ulink
-            url="http://pgp.mit.edu">http://pgp.mit.edu</ulink>), use the
-            procedure below. Public key servers synchronize with each other,
-            so publishing to one key server should be sufficient. For
-            background reading on this, see the <ulink
-            url="http://www.apache.org/dev/release-signing.html#keyserver-upload">release
-            signing page</ulink> on the Apache wiki, and the <ulink
-            url="http://maven.apache.org/developers/release/pmc-gpg-keys.html">gpg
-            key page</ulink> on the Maven wiki.</para>
+            <para></para>
 
-            <para>To send the key up to the key server:</para>
+            <para>*** more detail required here.</para>
 
-            <programlisting>$ gpg --send-keys --keyserver pgp.mit.edu nnnnnnnn</programlisting>
+            <para></para>
+          </sect3>
 
-            <para>where nnnnnnnn is the key Id.</para>
+          <sect3>
+            <title>Casting a Vote</title>
 
-            <para>Alternatively, you can browse to the <ulink
-            url="http://pgp.mit.edu">MIT key server</ulink> and paste in the
-            armored representation of your key.</para>
+            <para>When the above checks have been made (and any other checks
+            that the voter thinks is relevant), they should cast a vote by
+            replying to the email thread above.</para>
+          </sect3>
+        </sect2>
 
-            <para>Confirm the key has been added by browsing to submitting the
-            following URL:</para>
+        <sect2>
+          <title>After the vote</title>
 
-            <programlisting>http://pgp.mit.edu:11371/pks/lookup?search=0xnnnnnnnnn&amp;op=vindex</programlisting>
+          <para>If the vote has been unsuccessful, then address the problems
+          and go again, incrementing the -RCn suffix.</para>
 
-            <para>again, where nnnnnnnn is the key Id.</para>
-          </sect3>
+          <para>If the vote has been successful, then cut a new release, with
+          no -RCn suffix, and move onto the next step.</para>
 
-          <sect3>
-            <title>Publish to your Apache home directory</title>
+          <para><note>
+              <para>care should be taken to ensure that the new release is
+              based on the same version as the approved release candidate. One
+              way to do this is to ensure that the local copy from which the
+              release is taken is obtained specifying the correct SVN
+              revision.</para>
+            </note></para>
+        </sect2>
 
-            <para>The armored representation of your public key should be
-            uploaded to your home directory on people.apache.org, and renamed
-            as <filename>.pgpkey</filename>. Make sure this is readable by
-            all.</para>
-          </sect3>
+        <sect2>
+          <title>Start voting thread on incubator@a.o</title>
 
-          <sect3>
-            <title>Publish to your Apache HTML home directory</title>
+          <para>Once the vote has been approved on isis-dev and a new non-RCn
+          release has been created, then the release process should be
+          performed again on incubator@apache.org.</para>
+        </sect2>
+      </sect1>
 
-            <para>The armored representation of your public key should be
-            uploaded to your <filename>public_html</filename> home directory
-            on people.apache.org, named nnnnnnnn.asc. Make sure this is
-            readable by all.</para>
+      <sect1 id="sec.PromotingReleaseToDistribution">
+        <title>Promoting Release to Distribution</title>
 
-            <para>Check the file is accessible by browsing to:<programlisting>http://people.apache.org/~xxxxxxxx/nnnnnnnn.asc</programlisting></para>
+        <sect2>
+          <title>Release Source Zip</title>
 
-            <para>where xxxxxxxx is your apache LDAP user name and nnnnnnnn is
-            your public key id.</para>
-          </sect3>
+          <para>Releasing the source ZIP is a matter of copying the ZIP into
+          the dist directory on people.apache.org.</para>
 
-          <sect3>
-            <title>FOAF</title>
+          <note>
+            <para>There is an alternative and newer approach, namely to check
+            in the release to subversion. At some stage these procedures will
+            be updated to reflcet this newer approach.</para>
+          </note>
+
+          <para>Therefore, log onto people.apache.org, and copy the files
+          over:</para>
+
+          <programlisting>mkdir /www/www.apache.org/incubator/isis/
+cp ~/public_html/isis-parent-x.x.x-incubating-source-release.* /www/www.apache.org/incubator/isis/.</programlisting>
+        </sect2>
 
-            <para>First, check out the committers/info directory:</para>
+        <sect2>
+          <title>Release Binaries to Maven Central Repo</title>
 
-            <programlisting>svn co https://svn.apache.org/repos/private/committers/info</programlisting>
+          <para>From the <ulink
+          url="https://repository.apache.org/index.html#stagingRepositories">Nexus
+          pages</ulink>, select the staging repository and select 'release'
+          from the top menu.</para>
 
-            <para>Go to Apache FOAF-a-matic <ulink
-            url="http://people.apache.org/foaf/foafamatic.html">web
-            page</ulink> to generate the FOAF file text (we copy this text out
-            in a minute):</para>
+          <para>This moves the release artifacts into an Apache releases
+          repository, from there they will be automatically moved to the Maven
+          repository.</para>
+        </sect2>
+      </sect1>
 
-            <itemizedlist>
-              <listitem>
-                <para>enter ASF LDAP user name</para>
-              </listitem>
+      <sect1 id="sec.ManuallyDeployReleaseSite">
+        <title>Manually Deploy the Release Website</title>
 
-              <listitem>
-                <para>enter First name, Last name</para>
-              </listitem>
+        <para>The mechanics of deploying the release site is the same as
+        deploying a snapshot site, however there is the complication of
+        deploying from the relevant <filename>tags/x.x.x-incubating</filename>
+        tag (rather than <filename>trunk</filename>) as well as ensuring that
+        the released binaries are correctly referenced on the downloads
+        page.</para>
+      </sect1>
+    </chapter>
 
-              <listitem>
-                <para>for PGP key fingerprints, add Key</para>
+    <appendix id="apx.KeyGeneration">
+      <title>Key Generation</title>
 
-                <itemizedlist>
-                  <listitem>
-                    <para>paste in the key id</para>
-                  </listitem>
+      <abstract>
+        <para>How to generate keys and subkeys in order to sign a
+        release.</para>
+      </abstract>
 
-                  <listitem>
-                    <para>paste in the fingerprint</para>
-                  </listitem>
-                </itemizedlist>
-              </listitem>
+      <para>In order that a contributor can make a release it is necessary for
+      them to have generated a key and had that key recognized by other
+      members of the Apache Software Foundation. This appendix describes the
+      steps involved. For further background information on this topic, see
+      the <ulink url="http://www.apache.org/dev/release-signing.html">release
+      signing page</ulink> and the <ulink
+      url="http://www.apache.org/dev/openpgp.html#generate-key">openpgp
+      page</ulink> on the Apache wiki.</para>
 
-              <listitem>
-                <para>press "Create"</para>
-              </listitem>
-            </itemizedlist>
+      <sect1>
+        <title>Install and Configure gpg</title>
 
-            <para>In the box below, you should have a FOAF file, something
-            like:</para>
+        <para>Download and install GnuPG (gpg), version 1.4.10 or
+        higher.</para>
 
-            <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
-&lt;rdf:RDF
-      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-      xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
-      xmlns:foaf="http://xmlns.com/foaf/0.1/"
-      xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
-      xmlns:pm="http://www.web-semantics.org/ns/pm#"
-      xmlns:wot="http://xmlns.com/wot/0.1/"
-      xmlns:rss="http://purl.org/rss/1.0/"
-      xmlns:dc="http://purl.org/dc/elements/1.1/"
-      xmlns:ical="http://www.w3.org/2002/12/cal/ical#"
-      xmlns:doap="http://usefulinc.com/ns/doap#"&gt;
-  &lt;foaf:Person rdf:ID="danhaywood"&gt;
-    &lt;foaf:name&gt;Xxx Xxxxxxxx&lt;/foaf:name&gt;
-    &lt;foaf:givenname&gt;Xxx&lt;/foaf:givenname&gt;
-    &lt;foaf:family_name&gt;Xxxxxxxx&lt;/foaf:family_name&gt;
-    &lt;wot:hasKey&gt;
-      &lt;wot:PubKey&gt;
-        &lt;wot:fingerprint&gt;nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn&lt;/wot:fingerprint&gt;
-        &lt;wot:hex_id&gt;nnnnnnnn&lt;/wot:hex_id&gt;
-      &lt;/wot:PubKey&gt;
-    &lt;/wot:hasKey&gt;
-  &lt;/foaf:Person&gt;
-&lt;/rdf:RDF&gt;</programlisting>
+        <para>Then, edit <filename>~/.gnupg/gpg.conf</filename> (on Windows,
+        the file to edit is
+        <filename>C:\Users\xxx\AppData\Roaming\gnupg\gpg.conf</filename>) so
+        that the default is to generate a strong key:</para>
 
-            <para>(If you are creating the FOAF file for the first time, you
-            may want to add additional details).</para>
+        <programlisting>{code}
+personal-digest-preferences SHA512
+cert-digest-algo SHA512
+default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
+{code}</programlisting>
+      </sect1>
 
-            <para>From this, copy out the wot:key, and paste into your FDF
-            file in committers/info: </para>
+      <sect1>
+        <title>Key Generation</title>
 
-            <programlisting>    &lt;wot:hasKey&gt;
-      &lt;wot:PubKey&gt;
-        &lt;wot:fingerprint&gt;nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn&lt;/wot:fingerprint&gt;
-        &lt;wot:hex_id&gt;nnnnnnnn&lt;/wot:hex_id&gt;
-      &lt;/wot:PubKey&gt;
-    &lt;/wot:hasKey&gt;</programlisting>
+        <para>The ASF requires that keys are signed with a key (or subkey)
+        based on RSA 4096 bits. To do this:</para>
 
-            <para>Then, manually add in a &lt;wot:pubkeyAddress&gt; element
-            within &lt;wot:PubKey&gt;:</para>
+        <programlisting>$ gpg --gen-key
+gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
 
-            <programlisting>    &lt;wot:hasKey&gt;
-      &lt;wot:PubKey&gt;
-        &lt;wot:fingerprint&gt;nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn&lt;/wot:fingerprint&gt;
-        &lt;wot:hex_id&gt;nnnnnnnn&lt;/wot:hex_id&gt;
-        &lt;wot:pubkeyAddress
-          rdf:resource="http://people.apache.org/~username/nnnnnnnn.asc/&gt;
-      &lt;/wot:PubKey&gt;
-    &lt;/wot:hasKey&gt;</programlisting>
+Please select what kind of key you want:
+   (1) RSA and RSA (default)
+   (2) DSA and Elgamal
+   (3) DSA (sign only)
+   (4) RSA (sign only)
+Your selection?</programlisting>
 
-            <para>ie, referencing your publically exported public key</para>
+        <para>Specify RSA key:</para>
 
-            <para>Finally, commit your changes.</para>
-          </sect3>
+        <programlisting>Your selection? 1
 
-          <sect3>
-            <title>Save to KEYS</title>
+RSA keys may be between 1024 and 4096 bits long.
+What keysize do you want? (2048)</programlisting>
 
-            <para>The armored representation of the public key should be saved
-            to Isis' KEYS file, <ulink
-            url="https://svn.apache.org/repo/asf/incubator/isis/KEYS">https://svn.apache.org/repo/asf/incubator/isis/KEYS</ulink>
-            (ie, parent of <filename>trunk</filename>).</para>
+        <para>Specify key length as 4096 bits:</para>
 
-            <para>First, in a new directory, checkout this file:</para>
+        <programlisting>What keysize do you want? (2048) 4096
+Requested keysize is 4096 bits
 
-            <programlisting>svn -N co https://svn.apache.org/repos/asf/incubator/isis/ .</programlisting>
+Please specify how long the key should be valid.
+         0 = key does not expire
+      &lt;n&gt;  = key expires in n days
+      &lt;n&gt;w = key expires in n weeks
+      &lt;n&gt;m = key expires in n months
+      &lt;n&gt;y = key expires in n years
+Key is valid for? (0)</programlisting>
 
-            <para>This should bring down the <filename>KEYS</filename>
-            file.</para>
+        <para>Specify key as non-expiring:</para>
 
-            <para>Then, export your signature and armored
-            representation.</para>
+        <programlisting>Key is valid for? (0) 0
+Key does not expire at all
+Is this correct? (y/N) y
 
-            <programlisting>gpg --list-sigs nnnnnnnn &gt;&gt;KEYS
-gpg --armor --export nnnnnnnn &gt;&gt;KEYS</programlisting>
+You need a user ID to identify your key; the software constructs the user ID
+from the Real Name, Comment and Email Address in this form:
+    "Heinrich Heine (Der Dichter) &lt;heinrichh@duesseldorf.de&gt;"
 
-            <para>Then commit.</para>
-          </sect3>
+Real name: </programlisting>
 
-          <sect3>
-            <title>id.apache.org</title>
+        <para>Enter your name, email and comment:</para>
 
-            <para>Log onto id.apache.org and ensure that the finger print of
-            your public key is correct.</para>
-          </sect3>
-        </sect2>
+        <itemizedlist>
+          <listitem>
+            <para>use your apache.org email</para>
+          </listitem>
+
+          <listitem>
+            <para>the comment should be "CODE SIGNING KEY"</para>
+          </listitem>
+        </itemizedlist>
 
-        <sect2>
-          <title>Attend Key Signing Party (Apache web of trust)</title>
+        <programlisting>Real name: Xxx Xxxxxxxxx
+Email address: &lt;xxx@apache.org&gt;
+Comment: CODE SIGNING KEY
+You selected this USER-ID:
+    "Xxx Xxxxxxxxx (CODE SIGNING KEY) &lt;xxx@apache.org&gt;"
 
-          <para>It is strongly advised that the contributor attend a key
-          signing party at an Apache event, in order that other Apache
-          committers/members can in person verify their identity against the
-          key. The process for this is described <ulink
-          url="http://www.apache.org/dev/release-signing.html#key-signing-party">here</ulink>
-          and <ulink
-          url="http://wiki.apache.org/apachecon/PgpKeySigning">here</ulink>.</para>
-        </sect2>
+Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
 
-        <sect2>
-          <title>Update Maven Settings file
-          (<filename>~/.m2/settings.xml</filename>)</title>
+You need a Passphrase to protect your secret key.
+Enter passphrase:</programlisting>
 
-          <para>The Maven release plugin will automatically sign the release,
-          however it is necessary to update the
-          <filename>~/.m2/settings.xml</filename> file with your GPG
-          passphrase in order that it can use your secret key. This is defined
-          under a profile so that it is activated only when we perform a
-          release (as defined by <package>[org,apache:apache]</package> parent
-          <acronym>POM</acronym>.</para>
+        <para>Provide a passphrase to secure your key.</para>
 
-          <para>Therefore, make the following </para>
+        <programlisting>Enter passphrase:
+Repeat passphrase:</programlisting>
 
-          <programlisting>&lt;settings&gt;
-  ...
-  &lt;profiles&gt;
-    &lt;profile&gt;
-      &lt;id&gt;apache-release&lt;/id&gt;
-      &lt;properties&gt;
-    &lt;gpg.passphrase&gt;xxx xxx xxx xxx xxx xxx xxx&lt;/gpg.passphrase&gt;
-      &lt;/properties&gt;
-    &lt;/profile&gt;
-  &lt;/profiles&gt;
-&lt;/settings&gt;</programlisting>
+        <para>GPG will goes on to generate your key:</para>
 
-          <para>In addition, to allow the release plugin to tag SVN changes,
-          you must either add in your LDAP username/password or configure
-          .ssh:</para>
+        <programlisting>We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+...+++++
+.........................+++++
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+....+++++
+...+++++
+gpg: key nnnnnnnn marked as ultimately trusted
+public and secret key created and signed.
 
-          <programlisting>&lt;settings&gt;
-  ...
-  &lt;servers&gt;
-    ...
-    &lt;server&gt;
-      &lt;id&gt;apache.releases.https&lt;/id&gt;
-      &lt;username&gt;xxxx&lt;/username&gt;
-      &lt;password&gt;xxxx&lt;/password&gt;
-    &lt;/server&gt;
-  &lt;/servers&gt;
-  ...
-&lt;/settings&gt;</programlisting>
-        </sect2>
-      </sect1>
+gpg: checking the trustdb
+gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
+pub   4096R/nnnnnnnn yyyy-mm-dd
+      Key fingerprint = xxxx xxxx xxxx xxxx xxxx  xxxx xxxx xxxx xxxx xxxx
+uid                  Xxx Xxxxxx &lt;xxx@apache.org&gt;
+sub   4096R/kkkkkkkk yyyy-mm-dd</programlisting>
 
-      <sect1 id="sec.MavenReleasePrepare">
-        <title>Preparing a Release (<code>mvn release:prepare</code>)</title>
+        <para>The public key with id nnnnnnnn should now be stored in
+        <filename>~/.gnupg/pubring.pgp</filename> (on Windows 7, this is in
+        c<filename>:/Users/xxx/AppData/Roaming/gnupg/pubring.pgp</filename>).</para>
 
-        <para>We recommend creating release candidates from branches, and then
-        the final release from trunk.</para>
+        <para>To confirm the key has been generated, use:</para>
 
-        <sect2>
-          <title>Branch (release candidates only)</title>
+        <programlisting>$ gpg --list-keys --fingerprint</programlisting>
 
-          <para>First, create a branch:</para>
+        <para>The key Id is the one true way to identify the key, and is also
+        the last 8 digits of the fingerprint. The corresponding secret key for
+        id nnnnnnnn is stored in <filename>~/.gnupg/secring.pgp</filename> (on
+        Windows 7, this is in
+        <filename>c:/Users/xxx/AppData/Roaming/gnupg/secring.pgp</filename>).</para>
 
-          <programlisting>svn mkdir https://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating \
-   -m "branching to create x.x.x-RCn-incubating"
-svn copy https://svn.apache.org/repos/asf/incubator/isis/trunk \
-    https://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating/trunk \
-    -m "copying trunk to branches/x.x.x-RCn-incubating"</programlisting>
+        <para>It's also worth confirming the key has the correct preference of
+        algorithms (reflecting the initial configuration we did earlier). For
+        this, enter the gpg shell for your new key:</para>
 
-          <para>Now create a workspace for this branch. The easiest approach
-          is to copy <filename>trunk</filename> and perform an <code>svn
-          switch</code>:</para>
+        <para><programlisting>$ gpg --edit-key nnnnnnnnn
+gpg&gt;</programlisting>where nnnnnnnn is your key id. Now, use the 'showpref'
+        subcommand to list details:</para>
 
-          <programlisting>cd .../trunk   # your local workspace for isis/trunk
+        <programlisting>gpg&gt; showpref
+[ultimate] (1). Xxx Xxxxxxxx (CODE SIGNING KEY) &lt;xxx@apache.org&gt;
+     Cipher: AES256, AES192, AES, CAST5, 3DES
+     Digest: SHA512, SHA384, SHA256, SHA224, SHA1
+     Compression: ZLIB, BZIP2, ZIP, Uncompressed
+     Features: MDC, Keyserver no-modify
 
-cd ..
-mkdir -p branches/x.x.x-RCn-incubating
-cp -R trunk branches/x.x.x-RCn-incubating/trunk
+gpg&gt;</programlisting>
 
-cd branches/x.x.x-RCn-incubating/trunk
-svn switch https://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating/trunk</programlisting>
+        <para>The Digest line should list SHA-512 first and SHA-1 last.</para>
 
-          <para>Because the release is being performed in a branch, it is then
-          necessary to edit the parent <filename>pom.xml</filename> in
-          <package>[oai:isis-parent]</package>. Change
-          <emphasis>trunk</emphasis> to
-          <emphasis>branches/x.x.x-RCn-incubating/trunk</emphasis> for each of
-          the children of the <code>&lt;scm&gt;</code> tag:</para>
+        <para>Finally, remember to take a backup of your key and the keyring
+        (ie, backup the <filename>.gnupg</filename> directory and its
+        contents).</para>
+      </sect1>
 
-          <programlisting>&lt;scm&gt;
-  &lt;connection&gt;
-    scm:svn:http://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating/trunk/
-  &lt;/connection&gt;
-  &lt;developerConnection&gt;
-    scm:svn:https://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating/trunk/
-  &lt;/developerConnection&gt;
-  &lt;url&gt;
-    http://svn.apache.org/repos/asf/incubator/isis/branches/x.x.x-RCn-incubating/trunk/
-  &lt;/url&gt;
-&lt;/scm&gt;</programlisting>
+      <sect1>
+        <title>Subkey Generation</title>
 
-          <para>The commit the <filename>pom.xml</filename> file.</para>
-        </sect2>
+        <para>It's recommended to use a subkey with an expiry date to sign
+        releases, rather than your main, non-expiring subkey. If a subkey is
+        present, then gpg will use it in preference to the main key.</para>
 
-        <sect2>
-          <title>Dry run</title>
+        <para>Enter the gpg shell using (the identifier of) your main
+        key:</para>
 
-          <para>The release:prepare command updates all POMs, creates a tag.
-          It's common practice to perform a dry run first:</para>
+        <programlisting>gpg --edit-key xxxxxxxx
+gpg&gt;</programlisting>
 
-          <programlisting>mvn release:clean release:prepare -P apache-release -D dryRun=true</programlisting>
+        <para>Type 'addkey' to create a subkey, and enter your passphrase for
+        the main key:</para>
 
-          <para>Specify version as
-          <emphasis>0.x.x-RCn-incubating</emphasis>.</para>
+        <para><programlisting>gpg&gt; addkey
+Key is protected.
+[enter your secret passphrase]
 
-          <para></para>
+You need a passphrase to unlock the secret key for
+user: "Dan Haywood (CODE SIGNING KEY) &lt;danhaywood@apache.org&gt;"
+4096-bit RSA key, ID xxxxxxxx, created 2011-02-01
 
-          <para>*** more detail required here.</para>
+Please select what kind of key you want:
+   (3) DSA (sign only)
+   (4) RSA (sign only)
+   (5) Elgamal (encrypt only)
+   (6) RSA (encrypt only)
+Your selection?</programlisting></para>
 
-          <para></para>
-        </sect2>
+        <para>Select (4) to choose an RSA key for signing:</para>
 
-        <sect2>
-          <title>Release Proper</title>
+        <programlisting>Your selection? 4
 
-          <para>Assuming that the dry run has succeeded, it's time to create
-          the release proper</para>
+RSA keys may be between 1024 and 4096 bits long.
+What keysize do you want? (2048) 4096
 
-          <programlisting>mvn release:clean release:prepare -P apache-release -D skipTests=true</programlisting>
+Requested keysize is 4096 bits
 
-          <para>Specify version as
-          <emphasis>0.x.x-RCn-incubating</emphasis>.</para>
+Please specify how long the key should be valid.
+         0 = key does not expire
+      &lt;n&gt;  = key expires in n days
+      &lt;n&gt;w = key expires in n weeks
+      &lt;n&gt;m = key expires in n months
+      &lt;n&gt;y = key expires in n years
+Key is valid for?</programlisting>
 
-          <para><note>
-              <para>If you are in Europe the <code>mvn release:prepare</code>
-              command almost always fails at the last step, with a message
-              like:</para>
+        <para>Specify that the key is valid for 1 year:</para>
 
-              <programlisting>[ERROR]
- BUILD FAILURE
-[INFO]
- ------------------------------------------------------------------------
-[INFO]
- Unable to tag SCM
-Provider message:
-The svn tag command failed.
-Command output:
-svn: No such revision 936951</programlisting>
+        <programlisting>Key is valid for? (0) 1y
 
-              <para>This is due to the SVN mirroring in place between Europe
-              and the master in the US. When you make a commit, it isn't
-              immediately available in Europe to svn up to. Just wait 10 secs
-              and repeat the mvn release:prepare command for it to restart
-              where it left off.</para>
-            </note><note>
-              <para>If other things go wrong, then <code>mvn
-              release:clean</code> will do most of the cleaning up in the
-              event of failures.</para>
-            </note></para>
+Key expires at yy/MM/dd hh:mm:ss
+Is this correct? (y/N) y
+Really create? (y/N) y
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+...+++++
+.+++++
 
-          <para></para>
+pub  4096R/xxxxxxxx  created: yyyy-mm-dd  expires: never       usage: SC
+                     trust: ultimate      validity: ultimate
+sub  4096R/xxxxxxxx  created: yyyy-mm-dd  expires: never       usage: E
+sub  4096R/xxxxxxxx  created: yyyy-mm-dd  expires: yyYY-mm-dd  usage: S
+[ultimate] (1). Dan Haywood (CODE SIGNING KEY) &lt;danhaywood@apache.org&gt;
 
-          <para>*** more detail required here.</para>
+gpg&gt;</programlisting>
 
-          <para></para>
+        <para>Quit the gpg shell; you now have a subkey.</para>
+      </sect1>
 
-          <para>*** check the archetype versions; may need manual tweaking
-          beforehand if doesn't bump versions correctly?</para>
+      <sect1>
+        <title>Generate a Revocation Certificate</title>
 
-          <para></para>
-        </sect2>
+        <para>It's good practice to generate a number of revocation
+        certificates so that the key can be revoked if it happens to be
+        compromised. See <ulink
+        url="http://www.apache.org/dev/openpgp.html#revocation-certs">the gpg
+        page</ulink> on the Apache wiki for more background on this
+        topic.</para>
 
-        <sect2>
-          <title>Post-build sanity check</title>
+        <para>First, generate a "no reason specified" key:</para>
 
-          <para>You should end up with artifacts in your local repo with the
-          new version <emphasis>0.x.x-RCn-incubating</emphasis>. As a sanity
-          check, use the quickstart archetype to generate the application, and
-          make sure that the generated application runs ok.</para>
+        <programlisting>$ gpg --output revoke-nnnnnnnn-0.asc --armor --gen-revoke nnnnnnnn
 
-          <para>If you find problems and the release was performed on trunk
-          (rather than a branch) then you may need to revert the changes. The
-          release commands make and commit changes to the project's
-          <filename>pom.xml</filename> files and they create a tag in SVN;
-          you'll need to revert the <filename>pom.xml</filename> files and
-          delete the tag from SVN.</para>
-        </sect2>
-      </sect1>
+sec  4096R/nnnnnnnn yyyy-mm-dd Xxx Xxxxxxx (CODE SIGNING KEY) &lt;xx@apache.org&gt;
+Create a revocation certificate for this key? (y/N) Y
 
-      <sect1 id="sec.UploadReleaseForVoting">
-        <title>Upload Release for Voting</title>
+Please select the reason for the revocation:
+  0 = No reason specified
+  1 = Key has been compromised
+  2 = Key is superseded
+  3 = Key is no longer used
+  Q = Cancel
+(Probably you want to select 1 here)
+Your decision?</programlisting>
 
-        <para>Once the release has been built locally, it should be uploaded
-        for voting. This consists of two things: uploading the source release,
-        and deploying the Maven artifacts to a staging directory.</para>
+        <para>Select 0.</para>
 
-        <sect2>
-          <title>Upload Source Zip</title>
+        <programlisting>Your decision? 0
 
-          <para>The source ZIP can be found in the <filename>target</filename>
-          directory of the parent project (ie at
-          <filename>trunk/target</filename>), along with its signature. The
-          two files of interest are:</para>
+Enter an optional description; end it with an empty line:</programlisting>
 
-          <itemizedlist>
-            <listitem>
-              <para><filename>isis-parent-0.x.x-RCn-incubating-incubating-source-release.zip</filename>,
-              and</para>
-            </listitem>
+        <para>Provide a description:</para>
 
-            <listitem>
-              <para><filename>isis-parent-0.x.x-RCn-incubating-incubating-source-release.zip.asc</filename></para>
-            </listitem>
-          </itemizedlist>
+        <programlisting>&gt; Generic certificate to revoke key, generated at time of key creation.
+&gt;
+Reason for revocation: No reason specified
+Generic certificate to revoke key, generated at time of key creation.
+Is this okay? (y/N)</programlisting>
 
-          <para>Upload these to your public_html directory on
-          people.apache.org so that they can be referenced in your vote email
-          (see <xref linkend="sec.Voting" />).</para>
-        </sect2>
+        <para>Confirm this is ok.</para>
 
-        <sect2>
-          <title>Deploying Binaries to Staging Repository (<classname>mvn
-          release:perform</classname>)</title>
+        <programlisting>Is this okay? y
 
-          <para>The Apache staging repository lives on the Nexus repository
-          hosted at <ulink
-          url="https://repository.apache.org">https://repository.apache.org</ulink>.
-          The process of uploading will create a staging repository that is
-          associated with the host (IP address) performing the release. Once
-          the repository is staged, the newly created staging repository is
-          "closed" in order to make it available to others.</para>
+You need a passphrase to unlock the secret key for
+user: "Xxx Xxxxxxx (CODE SIGNING KEY) &lt;xxx@apache.org&gt;"
+4096-bit RSA key, ID nnnnnnnn, created yyyy-mm-dd
 
-          <sect3>
-            <title>Perform the Release</title>
+Enter passphrase:</programlisting>
 
-            <para>The command to stage the release is:</para>
+        <para>Enter a passphrase:</para>
 
-            <programlisting>mvn release:perform -Papache-release</programlisting>
+        <programlisting>Enter passphrase:
+Revocation certificate created.
 
-            <para></para>
+Please move it to a medium which you can hide away; if Mallory gets
+access to this certificate he can use it to make your key unusable.
+It is smart to print this certificate and store it away, just in case
+your media become unreadable.  But have some caution:  The print system of
+your machine might store the data and make it available to others!</programlisting>
 
-            <para>*** further details required here.</para>
+        <para>The file 'revoke-nnnnnnnn-0.asc' should be created: Then, backup
+        this file.</para>
 
-            <para></para>
-          </sect3>
+        <para>Now repeat the process to create two further revocation
+        certificates:</para>
 
-          <sect3>
-            <title>Check the Repository</title>
+        <itemizedlist>
+          <listitem>
+            <para><code>gpg --output revoke-nnnnnnnn-1.asc --armor
+            --gen-revoke nnnnnnnn</code></para>
+
+            <para>Specify reason as "1 = Key has been compromised"</para>
+          </listitem>
+
+          <listitem>
+            <para><code>gpg --output revoke-nnnnnnnn-3.asc --armor
+            --gen-revoke nnnnnnnn</code></para>
+
+            <para>Specify reason as "3 = Key is no longer used"</para>
+          </listitem>
+        </itemizedlist>
+
+        <para>Backup these files also.</para>
+
+        <para><note>
+            <para>if you find that you need to revoke your certificate, this
+            <ulink
+            url="http://www.hackdiary.com/2004/01/18/revoking-a-gpg-key">blog
+            post</ulink> explains how.</para>
+          </note></para>
+      </sect1>
 
-            <para>This will put release artifacts into a newly created staging
-            repository . You will need to log into repository.apache.org to
-            see it.</para>
+      <sect1>
+        <title>Publish Key</title>
 
-            <para>If nothing appears in a staging repo you should stop here
-            and work out why.</para>
+        <para>It is also necessary to publish your key. There are several
+        places where this should be done. In most cases, you'll need the
+        "armored" " (ie ASCII) representation of your key. This can be
+        generated using:</para>
 
-            <para>Assuming that the repo has been populated, make a note of
-            its repo id; this is needed for the voting thread (see <xref
-            linkend="sec.VotingThread" />).</para>
+        <programlisting>$ gpg --armor --export nnnnnnnn &gt; nnnnnnnn.asc</programlisting>
 
-            <para></para>
+        <para>where nnnnnnnn is the id of your public key.</para>
 
-            <para>*** confirm the procedure described here.</para>
+        <para>You'll also need the fingerprint of your key. This can be
+        generated using:</para>
 
-            <para></para>
-          </sect3>
+        <programlisting>$ gpg --fingerprint nnnnnnnn</programlisting>
 
-          <sect3>
-            <title>Close the Repository</title>
+        <para>The output from this command includes a line beginning "Key
+        fingerprint", followed by a (space delimited) 40 character hexadecimal
+        fingerprint. The last 8 characters should be the same as the key id
+        (nnnnnnnn).</para>
 
-            <para>After checking that the staging repository contains the
-            artifacts that you expect you should close the staging repository.
-            This will make it available so that people can check the
-            release.</para>
+        <sect3>
+          <title>Publish to a public key server</title>
 
-            <para></para>
+          <para>To a publish your key to a public key server (eg the MIT key
+          server hosted at <ulink
+          url="http://pgp.mit.edu">http://pgp.mit.edu</ulink>), use the
+          procedure below. Public key servers synchronize with each other, so
+          publishing to one key server should be sufficient. For background
+          reading on this, see the <ulink
+          url="http://www.apache.org/dev/release-signing.html#keyserver-upload">release
+          signing page</ulink> on the Apache wiki, and the <ulink
+          url="http://maven.apache.org/developers/release/pmc-gpg-keys.html">gpg
+          key page</ulink> on the Maven wiki.</para>
 
-            <para>*** further details required here.</para>
+          <para>To send the key up to the key server:</para>
 
-            <para></para>
-          </sect3>
-        </sect2>
-      </sect1>
+          <programlisting>$ gpg --send-keys --keyserver pgp.mit.edu nnnnnnnn</programlisting>
 
-      <sect1 id="sec.Voting">
-        <title>Voting</title>
+          <para>where nnnnnnnn is the key Id.</para>
 
-        <para>Once the artifacts have been uploaded, you can call a vote.
-        Votes last for 72 hours and require a +3 vote from members. While
-        incubating, this vote should be performed on the
-        isis-dev@incubator.apache.org mailing list, and then repeated on the
-        incubator@apache.org mailing list.</para>
+          <para>Alternatively, you can browse to the <ulink
+          url="http://pgp.mit.edu">MIT key server</ulink> and paste in the
+          armored representation of your key.</para>
 
-        <sect2 id="sec.VotingThread">
-          <title>Start voting thread on isis-dev@incubator.a.o</title>
+          <para>Confirm the key has been added by browsing to submitting the
+          following URL:</para>
 
-          <para>You can use the following boilerplate for the vote on
-          isis-dev.</para>
+          <programlisting>http://pgp.mit.edu:11371/pks/lookup?search=0xnnnnnnnnn&amp;op=vindex</programlisting>
 
-          <para>Use the following subject:</para>
+          <para>again, where nnnnnnnn is the key Id.</para>
+        </sect3>
 
-          <programlisting>[VOTE] Apache Isis release candidate 0.x.x-RCn-incubating</programlisting>
+        <sect3>
+          <title>Publish to your Apache home directory</title>
 
-          <para>And use the following body:</para>
+          <para>The armored representation of your public key should be
+          uploaded to your home directory on people.apache.org, and renamed as
+          <filename>.pgpkey</filename>. Make sure this is readable by
+          all.</para>
+        </sect3>
 
-          <programlisting>I've staged a release candidate for Apache Isis, namely 0.x.x-RCn-incubating.
+        <sect3>
+          <title>Publish to your Apache HTML home directory</title>
 
-The signed source ZIP can be downloaded from my home directory on people.apache.org:
-* http://people.apache.org/~uuuuuuuu/isis-parent-0.x.x-RCn-incubating-source-release.zip (zip file), and
-* http://people.apache.org/~uuuuuuuu/isis-parent-0.x.x-RCn-incubating-source-release.zip.asc (signature)
+          <para>The armored representation of your public key should be
+          uploaded to your <filename>public_html</filename> home directory on
+          people.apache.org, named nnnnnnnn.asc. Make sure this is readable by
+          all.</para>
 
-The code has been tagged as tags/0.x.x-RCn-incubating.
+          <para>Check the file is accessible by browsing to:<programlisting>http://people.apache.org/~xxxxxxxx/nnnnnnnn.asc</programlisting></para>
 
-In addition, the Maven artifacts have been staged to staging repository on repository.apache.org:
-* https://repository.apache.org/content/repositories/orgapacheisis-zzz/
+          <para>where xxxxxxxx is your apache LDAP user name and nnnnnnnn is
+          your public key id.</para>
+        </sect3>
 
-The RAT checks have passed (see contributors guide for files that are considered as being excluded).
+        <sect3>
+          <title>FOAF</title>
 
-Please verify the release and cast your vote.  The vote will be open for 72 hours.
+          <para>First, check out the committers/info directory:</para>
 
-[ ] +1
-[ ]  0
-[ ] -1</programlisting>
+          <programlisting>svn co https://svn.apache.org/repos/private/committers/info</programlisting>
 
-          <para>where:</para>
+          <para>Go to Apache FOAF-a-matic <ulink
+          url="http://people.apache.org/foaf/foafamatic.html">web page</ulink>
+          to generate the FOAF file text (we copy this text out in a
+          minute):</para>
 
           <itemizedlist>
             <listitem>
-              <para><emphasis>uuuuuuuu</emphasis> is your Apache LDAP
-              username</para>
+              <para>enter ASF LDAP user name</para>
             </listitem>
 
             <listitem>
-              <para><emphasis>zzz</emphasis> is the newly created staging
-              repository, from above.</para>
+              <para>enter First name, Last name</para>
             </listitem>
-          </itemizedlist>
-        </sect2>
-
-        <sect2>
-          <title>Other contributors cast their vote</title>
-
-          <para>It is the responsibility of other contributors (or any ASF
-          member) to cast their vote on the release. This section provides
-          some guidance on this process.</para>
-
-          <sect3>
-            <title>Verifying the source release artifacts</title>
-
-            <para>Download both the ZIP and .ASC files from the location
-            specified in the voting email. To verify that the signature is
-            correct, use:</para>
-
-            <programlisting>gpg --verify isis-parent-x.x.x-RCn-incubating.zip.asc isis-parent-x.x.x-RCn-incubating.zip</programlisting>
-
-            <para>The ZIP file should then be unpacked.</para>
-
-            <para>Once unpacked, it is recommended that voters at a minimum
-            sanity check the contents, as per <xref
-            linkend="sec.SanityCheck" />. </para>
 
-            <para>In particular, when building locally, confirm that the
-            versions in your local repository
-            (<filename>~/.m2/repository/org/apache/isis</filename>) are
-            correct.</para>
-          </sect3>
+            <listitem>
+              <para>for PGP key fingerprints, add Key</para>
 
-          <sect3>
-            <title>Verifying the binary release artifacts</title>
+              <itemizedlist>
+                <listitem>
+                  <para>paste in the key id</para>
+                </listitem>
 
-            <para>Optionally, voters can verify the binary releases (in the
-            Maven staging repository).</para>
+                <listitem>
+                  <para>paste in the fingerprint</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
 
-            <para></para>
+            <listitem>
+              <para>press "Create"</para>
+            </listitem>
+          </itemizedlist>
 
-            <para>*** more detail required here.</para>
+          <para>In the box below, you should have a FOAF file, something
+          like:</para>
 
-            <para></para>
-          </sect3>
+          <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;rdf:RDF
+      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+      xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
+      xmlns:foaf="http://xmlns.com/foaf/0.1/"
+      xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
+      xmlns:pm="http://www.web-semantics.org/ns/pm#"
+      xmlns:wot="http://xmlns.com/wot/0.1/"
+      xmlns:rss="http://purl.org/rss/1.0/"
+      xmlns:dc="http://purl.org/dc/elements/1.1/"
+      xmlns:ical="http://www.w3.org/2002/12/cal/ical#"
+      xmlns:doap="http://usefulinc.com/ns/doap#"&gt;
+  &lt;foaf:Person rdf:ID="danhaywood"&gt;
+    &lt;foaf:name&gt;Xxx Xxxxxxxx&lt;/foaf:name&gt;
+    &lt;foaf:givenname&gt;Xxx&lt;/foaf:givenname&gt;
+    &lt;foaf:family_name&gt;Xxxxxxxx&lt;/foaf:family_name&gt;
+    &lt;wot:hasKey&gt;
+      &lt;wot:PubKey&gt;
+        &lt;wot:fingerprint&gt;nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn&lt;/wot:fingerprint&gt;
+        &lt;wot:hex_id&gt;nnnnnnnn&lt;/wot:hex_id&gt;
+      &lt;/wot:PubKey&gt;
+    &lt;/wot:hasKey&gt;
+  &lt;/foaf:Person&gt;
+&lt;/rdf:RDF&gt;</programlisting>
 
-          <sect3>
-            <title>Casting a Vote</title>
+          <para>(If you are creating the FOAF file for the first time, you may
+          want to add additional details).</para>
 
-            <para>When the above checks have been made (and any other checks
-            that the voter thinks is relevant), they should cast a vote by
-            replying to the email thread above.</para>
-          </sect3>
-        </sect2>
+          <para>From this, copy out the wot:key, and paste into your FDF file
+          in committers/info:</para>
 
-        <sect2>
-          <title>After the vote</title>
+          <programlisting>    &lt;wot:hasKey&gt;
+      &lt;wot:PubKey&gt;
+        &lt;wot:fingerprint&gt;nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn&lt;/wot:fingerprint&gt;
+        &lt;wot:hex_id&gt;nnnnnnnn&lt;/wot:hex_id&gt;
+      &lt;/wot:PubKey&gt;
+    &lt;/wot:hasKey&gt;</programlisting>
 
-          <para>If the vote has been unsuccessful, then address the problems
-          and go again, incrementing the -RCn suffix.</para>
+          <para>Then, manually add in a &lt;wot:pubkeyAddress&gt; element
+          within &lt;wot:PubKey&gt;:</para>
 
-          <para>If the vote has been successful, then cut a new release, with
-          no -RCn suffix, and move onto the next step.</para>
+          <programlisting>    &lt;wot:hasKey&gt;
+      &lt;wot:PubKey&gt;
+        &lt;wot:fingerprint&gt;nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn&lt;/wot:fingerprint&gt;
+        &lt;wot:hex_id&gt;nnnnnnnn&lt;/wot:hex_id&gt;
+        &lt;wot:pubkeyAddress
+          rdf:resource="http://people.apache.org/~username/nnnnnnnn.asc/&gt;
+      &lt;/wot:PubKey&gt;
+    &lt;/wot:hasKey&gt;</programlisting>
 
-          <para><note>
-              <para>care should be taken to ensure that the new release is
-              based on the same version as the approved release candidate. One
-              way to do this is to ensure that the local copy from which the
-              release is taken is obtained specifying the correct SVN
-              revision.</para>
-            </note></para>
-        </sect2>
+          <para>ie, referencing your publically exported public key</para>
 
-        <sect2>
-          <title>Start voting thread on incubator@a.o</title>
+          <para>Finally, commit your changes.</para>
+        </sect3>
 
-          <para>Once the vote has been approved on isis-dev and a new non-RCn
-          release has been created, then the release process should be
-          performed again on incubator@apache.org.</para>
-        </sect2>
-      </sect1>
+        <sect3>
+          <title>Save to KEYS</title>
 
-      <sect1 id="sec.PromotingReleaseToDistribution">
-        <title>Promoting Release to Distribution</title>
+          <para>The armored representation of the public key should be saved
+          to Isis' KEYS file, <ulink
+          url="https://svn.apache.org/repo/asf/incubator/isis/KEYS">https://svn.apache.org/repo/asf/incubator/isis/KEYS</ulink>
+          (ie, parent of <filename>trunk</filename>).</para>
 
-        <sect2>
-          <title>Release Source Zip</title>
+          <para>First, in a new directory, checkout this file:</para>
 
-          <para>Releasing the source ZIP is a matter of copying the ZIP into
-          the dist directory on people.apache.org.</para>
+          <programlisting>svn -N co https://svn.apache.org/repos/asf/incubator/isis/ .</programlisting>
 
-          <note>
-            <para>There is an alternative and newer approach, namely to check
-            in the release to subversion. At some stage these procedures will
-            be updated to reflcet this newer approach.</para>
-          </note>
+          <para>This should bring down the <filename>KEYS</filename>
+          file.</para>
 
-          <para>Therefore, log onto people.apache.org, and copy the files
-          over:</para>
+          <para>Then, export your signature and armored representation.</para>
 
-          <programlisting>mkdir /www/www.apache.org/incubator/isis/
-cp ~/public_html/isis-parent-x.x.x-incubating-source-release.* /www/www.apache.org/incubator/isis/.</programlisting>
-        </sect2>
+          <programlisting>gpg --list-sigs nnnnnnnn &gt;&gt;KEYS
+gpg --armor --export nnnnnnnn &gt;&gt;KEYS</programlisting>
 
-        <sect2>
-          <title>Release Binaries to Maven Central Repo</title>
+          <para>Then commit.</para>
+        </sect3>
 
-          <para>From the <ulink
-          url="https://repository.apache.org/index.html#stagingRepositories">Nexus
-          pages</ulink>, select the staging repository and select 'release'
-          from the top menu.</para>
+        <sect3>
+          <title>id.apache.org</title>
 
-          <para>This moves the release artifacts into an Apache releases
-          repository, from there they will be automatically moved to the Maven
-          repository.</para>
-        </sect2>
+          <para>Log onto id.apache.org and ensure that the finger print of
+          your public key is correct.</para>
+        </sect3>
       </sect1>
 
-      <sect1 id="sec.ManuallyDeployReleaseSite">
-        <title>Manually Deploy the Release Website</title>
+      <sect1>
+        <title>Attend Key Signing Party (Apache web of trust)</title>
 
-        <para>The mechanics of deploying the release site is the same as
-        deploying a snapshot site, however there is the complication of
-        deploying from the relevant <filename>tags/x.x.x-incubating</filename>
-        tag (rather than <filename>trunk</filename>) as well as ensuring that
-        the released binaries are correctly referenced on the downloads
-        page.</para>
+        <para>It is strongly advised that the contributor attend a key signing
+        party at an Apache event, in order that other Apache
+        committers/members can in person verify their identity against the
+        key. The process for this is described <ulink
+        url="http://www.apache.org/dev/release-signing.html#key-signing-party">here</ulink>
+        and <ulink
+        url="http://wiki.apache.org/apachecon/PgpKeySigning">here</ulink>.d</para>
       </sect1>
-    </chapter>
+    </appendix>
   </part>
 </book>

Modified: incubator/isis/trunk/src/site/apt/downloads.apt.vm
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/src/site/apt/downloads.apt.vm?rev=1126347&r1=1126346&r2=1126347&view=diff
==============================================================================
--- incubator/isis/trunk/src/site/apt/downloads.apt.vm (original)
+++ incubator/isis/trunk/src/site/apt/downloads.apt.vm Mon May 23 07:29:05 2011
@@ -24,18 +24,18 @@
 
 Release
  
- Apache Isis is distributed in both source and binary form:
+ <Apache Isis> is distributed in both source and binary form:
  
  * the source can be downloaded from 
    {{{http://www.apache.org/dyn/closer.cgi/incubator/isis/isis-parent-${project.version}-source-release.zip}here}} 
    ({{{http://www.apache.org/dist/incubator/isis/isis-parent-${project.version}-source-release.zip.asc}asc}}, {{{http://www.apache.org/dist/incubator/isis/isis-parent-${project.version}-source-release.zip.md5}md5}}, {{{http://www.apache.org/dist/incubator/isis/isis-parent-${project.version}-source-release.zip.sha1}sha1}})
    
-   Details of building Isis from source can be found in the contributors guide ({{{./docbkx/html/guide/isis-contributors-guide.html}HTML or {{{./docbkx/pdf/isis-contributors-guide.pdf}PDF}})
+   Details of building <Isis> from source can be found in the contributors guide ({{{./docbkx/html/guide/isis-contributors-guide.html}HTML}} or {{{./docbkx/pdf/isis-contributors-guide.pdf}PDF}})
    for further details.
  
- * the binaries can be downloaded from {{{http://repo1.maven.org}Maven central repo}}, typically by using the Isis quickstart archetype.
+ * the binaries can be downloaded from {{{http://repo1.maven.org}Maven central repo}}, typically by using the <Isis> quickstart archetype.
  
-   See the quickstart {{{./quickstart-app.html}page}} for details on how to using the quickstart archetype.
+   See the {{{./quickstart-app.html}quickstart page}} for details on how to using the quickstart archetype.
    
  * Release notes can be found {{{./release-notes-${project.version}.html}here}}.  
  



Mime
View raw message