commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject svn commit: r930725 - /commons/proper/commons-site/trunk/src/site/xdoc/releases/prepare.xml
Date Sun, 04 Apr 2010 17:53:30 GMT
Author: psteitz
Date: Sun Apr  4 17:53:29 2010
New Revision: 930725

URL: http://svn.apache.org/viewvc?rev=930725&view=rev
Log:
Continued updates and improvements:
* Improved sequencing so RC will have the right contents and structure
* Added info on commons properties
* Added instruction to regenerate and checkin download page
* Consolidated checks on jar manifests
* Added instructions on how to generate release notes
* Fixed various errors / obsolete references
* Added instructions for layout of RC website directories
* Added script to generate RC
* Added sample VOTE email

Modified:
    commons/proper/commons-site/trunk/src/site/xdoc/releases/prepare.xml

Modified: commons/proper/commons-site/trunk/src/site/xdoc/releases/prepare.xml
URL: http://svn.apache.org/viewvc/commons/proper/commons-site/trunk/src/site/xdoc/releases/prepare.xml?rev=930725&r1=930724&r2=930725&view=diff
==============================================================================
--- commons/proper/commons-site/trunk/src/site/xdoc/releases/prepare.xml (original)
+++ commons/proper/commons-site/trunk/src/site/xdoc/releases/prepare.xml Sun Apr  4 17:53:29
2010
@@ -117,7 +117,7 @@
     Check that the javadocs have the correct version number.
         </p>
         <p>
-    If the component uses Checkstyle, FindBugs or PMD tools, examine the reports and fix
any 
+    If the component uses checkstyle, findbugs or PMD tools, examine the reports and fix
all 
     problems.
         </p>
     </subsection>
@@ -132,104 +132,65 @@
       At a minimum, both source and binary distributions <strong>must</strong>
include the release notes, license and 
       notice files.
       </p>
-      <!-- TODO: add a paragraph on commons properties in the pom -->
       <p>
-      When using Ant, typically the Ant dist goal produces the source and binary distributions.
Included
-      files are specified in the goal or subgoals and should be verified similarly to above.
+      Update the version numbers in pom.xml and build.xml to the new release version, in
this example, 1.2.
+      For maven builds, make sure that the build properties are properly set. Review the
<code>properties</code>
+      section of the pom: 
+      <pre>
+      &lt;properties&gt;
+        &lt;commons.componentid&gt;foo&lt;/commons.componentid&gt;
+        &lt;commons.release.version&gt;1.2&lt;/commons.release.version&gt;
+        &lt;commons.binary.suffix&gt;&lt;/commons.binary.suffix&gt;
+        &lt;commons.jira.id&gt;FOO&lt;/commons.jira.id&gt;
+        &lt;commons.jira.pid&gt;007&lt;/commons.jira.pid&gt;
+        &lt;maven.compile.source&gt;1.3&lt;/maven.compile.source&gt;
+        &lt;maven.compile.target&gt;1.3&lt;/maven.compile.target&gt;
+        &lt;project.build.sourceEncoding&gt;UTF-8&lt;/project.build.sourceEncoding&gt;
+        &lt;project.reporting.outputEncoding&gt;UTF-8&lt;/project.reporting.outputEncoding&gt;
+      &lt;properties&gt; </pre>
       </p>
       <p>
-      Test the "ant dist" or "mvn assembly:assembly" goal and inspect the tars/zips and jars
produced. 
-      "ant dist" or "mvn site" should succeed from the unpacked source distribution.  Make
sure it does.
-      Check the jar manifests per the guidelines below.  Check the build using the minimum
supported JDK.
-      Check that "mvn site" generates the documentation correctly. Check that all links are
working.
-      Do not proceed with tagging or cutting RCs until you have a fully working build that
produces
-      a good set of distribution artifacts.
+      Make sure that the release version is set to the new release and that the compile and
source targets
+      are set correctly.  Generate and check in a new download page for the component:
+      <pre>
+      mvn commons:download-page
+      svn commit -m "Updated download page in preparation for 1.2 release." src/site/xdoc/download_foo.xml
</pre>
       </p>
-    </subsection>
-    <subsection name='Check Class File Format'>
       <p>
-      Unless appropriate options are set, code compiled with more modern JVMs 
-      may fail on older JVMs. The minimum target JVM for the project should be
-      documented. Check that compilation produces code that will execute correctly
-      on that JVM. 
-      </p>
-      <p> 
-      If using maven, the <code>maven.compile.source</code> and <code>maven.compile.target</code>

-      properties in the <code>pom.xml</code> file should be set correctly, if
the desired versions 
-      differ from the default values in the Commons parent POM. Maven will add entries to

-      the jar's manifest. 
+      When using Ant, typically the Ant dist goal produces the source and binary distributions.
Included
+      files are specified in the goal or subgoals and should be verified similarly to above.
       </p>
       <p>
-      If using ant, the <code>javac</code> task should have the <code>target</code>
and <code>source</code>
-      attributes set correctly.
+      Test the "Ant dist" or "mvn assembly:assembly" goal and inspect the tars/zips and jars
produced. 
+      Verify that 
+      <ol>
+      <li> "Ant dist" or "mvn site" succeeds from the unpacked source distribution.</li>
+      <li> The jar manifests include LICENSE and NOTICE files and the contents of these
files are correct.</li>
+      <li> The jar manifests contain <code>X-Compile-Source-JDK</code>
and <code>X-Compile-Target-JDK</code>
+           entries set to the correct values. </li>
+      <li> The jar manifests include correctly set OSGi bundle properties (ask for
help verifying these on
+           commons-dev if necessary). </li>
+      <li> The jar manifests include the following required properties, set to the
correct values:
+      <pre>
+  Extension-Name: org.apache.commons.foo
+  Specification-Title: Apache Commons Foo
+  Specification-Vendor: The Apache Software Foundation
+  Specification-Version: 1.2
+  Implementation-Vendor-Id: org.apache
+  Implementation-Title: org.apache.commons.foo
+  Implementation-Vendor: The Apache Software Foundation
+  Implementation-Version: 1.2 </pre></li>
+      <li> "mvn site" generates the documentation correctly and all links are working.</li>
+      </ol>
+      Do not proceed with tagging or cutting RCs until you have a fully working build that
produces
+      a good set of distribution artifacts.  If your component supports both Ant and Maven
builds, make
+      sure that the build succeeds using both on all supported JDK versions.  If you have
access to
+      multiple platforms, test the build(s) on as many as you can. 
       </p>
     </subsection>
   </section>
 
   <section name="Creating a Release Candidate">
-    <subsection name='Check The Jar Manifest'>
-        <a name="checkjarmanifest"></a>
-        <p><strong>Maven Build</strong></p>
-        <p>
-        Maven will create an appropriate MANIFEST.MF file automatically and, unless specifically
-        configured, any MANIFEST.MF file present within the project will simply be ignored.
-        </p>
-        <p>
-        The maven build has been modified to include two <strong><i>non standard</i></strong>
attributes
-        in the jar's manifest to indicate the <code>maven.compile.source</code>
and 
-        <code>maven.compile.target</code> properties used to create the jar.
This serves two purposes:
-          <ul>
-             <li>To provide comfort to users regarding JVM compatibility.</li>
-             <li>Enable releases to be checked more easily for JVM compatibility.</li>
-          </ul>
-        </p>
-        <p>
-        The entries created in the manifest will look something like the following:
-        <pre>
-      X-Compile-Source-JDK: 1.3
-      X-Compile-Target-JDK: 1.3
-        </pre>
-        </p>
-        <p>
-        Maven builds have these properties automatically inserted if the POM inherits
-        from the Commons parent POM (org.apache.commons:commons-parent:pom:4). All Commons
-        projects using Maven are vigorously encouraged to use the parent POM.
-        </p>
-        <p><strong>Ant Build</strong></p>
-        <p>
-        If you are using Ant to build the release, then the MANIFEST.MF file at foo/src/conf/MANIFEST.MF
-        should contain appropriate <code>@varname@</code> strings which are replaced
dynamically 
-        by an Ant copy task
-        using values defined in the ant build.xml file. If the component's MANIFEST.MF file
instead 
-        has hard-wires values then it should be fixed to use appropriate ant variables. Useful
reference
-        documents are:
-        </p>
-        <ul>
-          <li>
-            <a href='http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html'>Sun Manifest
Format</a>
-          </li>
-          <li>
-            <a href='http://java.sun.com/j2se/1.5.0/docs/guide/versioning/spec/versioning2.html'>
-              Sun Package Versioning Standards
-            </a>
-          </li>
-        </ul>
-        <p>
-        If your component does not currently include an manifest when building it's jars,
one should be
-        added.
-        Here is an example of a typical commons manifest:
-        <pre>
-	Extension-Name: org.apache.commons.foo
-	Specification-Title: Apache Commons Foo
-	Specification-Vendor: The Apache Software Foundation
-	Specification-Version: 1.2
-	Implementation-Vendor-Id: org.apache
-	Implementation-Title: org.apache.commons.foo
-	Implementation-Vendor: The Apache Software Foundation
-	Implementation-Version: 1.2
-        </pre>
-        </p>
-    </subsection>
 
     <subsection name='Resolve Bugs'>
         <p>
@@ -245,18 +206,31 @@
     <subsection name='Prepare Release Notes'>
         <p>
 	Each component should have a file RELEASE-NOTES.txt in the base directory of the component.
-	This file should be included within the distributions available for download.
-	The release notes should contain a description of all the changes since the previous release.
-	Any compatibility issues with the last release (whether binary or semantic)
-	should be highlighted. 
-	If there are no compatibilty issues, this too should be mentioned.
-	An introduction to the release may also be given, describing the component
-	and the release in general terms. 
-       <!-- TODO: include instructions on how to get the changes plugin to generate a
starter -->
+	This file should be updated for the release and checked in prior to tagging or rolling
+	the release candidate.  As noted above, this file should be included in both the source
+	and binary release distributions. The release notes should contain a description of all
+    the changes since the previous release. Any compatibility issues with the last release
+    (whether binary or semantic) should be highlighted.  If there are no compatibilty issues,
+    this too should be mentioned. An introduction to the release may also be given, describing
+    the component and the release in general terms. The release notes should contain the
minimum
+    target Java version for the component.
 		</p>
     <p>
-The release notes should contain the minimum target Java version for the component.
-    </p>
+	Components that use the maven changes plugin and changes.xml to track changes can generate
+	a "starter" release notes document by supplying a custom Velocity template to the maven
+	announcements plugin: 
+	<pre>
+    mvn changes:announcement-generate
+    mv target/announcement/foo-release-notes.vm RELEASE-NOTES.txt </pre></p>
+    <p>
+    For this to work, the following properties need to be included in the <code>configuration</code>
+    for the maven-changes-plugin in the pom:
+    <pre>
+    &lt;template>foo-release-notes.vm&lt;/template&lt;
+    &lt;templateDirectory&lt;templates&lt;/templateDirectory&gt; </pre>
</p>
+    <p>
+    and the Velocity template, <code>foo-release-notes.vm</code> needs to be
defined in
+    <code>src/main/resources/templates.</code></p>
 		<p>
 	The release notes should be a plain text file. Take care to ensure
 	that the format allows easy reading on a wide variety of platforms.
@@ -321,10 +295,6 @@ The release notes should contain the min
 	So while dates are reported correctly in "svn log" output, only revision numbers should
 	be used with the -r option. See issue #752 in the subversion issue tracker at tigris.org.
 	</p>
-	<p>
-	Those using Maven should make sure to configure the assembly descriptors in
-        src/assembly to include RELEASE-NOTES.txt in the distributions as described above.
-        </p>
     </subsection>
 
     <subsection name='Test Against Listed Dependencies'>    
@@ -340,10 +310,6 @@ The release notes should contain the min
 	</p>
     </subsection>
 
-    <subsection name='Ensure a good build.xml'>
-      <!-- TODO: test both ant and maven builds and drop stuff that does not work -->
-    </subsection>
-
     <subsection name='Check the Apache License'>
         <p>
         Check the <a href="http://www.apache.org/licenses/">Apache Licenses</a>
page for current information.
@@ -351,7 +317,7 @@ The release notes should contain the min
         Check that the jar contains a copy of the license in the META-INF directory.
         </p>
         <p>
-        Check that the years in the copyright statement in the license in each source file
are correct. 
+        Check that the years in the copyright statement in the NOTICE file are correct. 
         </p>
         <p>
         Developer documentation on how to apply the Apache License 
@@ -362,7 +328,8 @@ The release notes should contain the min
         Some of the important items from the aforementioned documents:
         </p>
         <p>
-        <b>Do I have to have a copy of the license header in each source file?</b>
+        <b>Do I have to have a copy of the license in each source file?</b> 
Maven builds can use the RAT plugin to
+        generate a license report.
         </p>
         <p>
         Only one full copy of the license is needed per distribution.  Each source
@@ -414,7 +381,7 @@ The release notes should contain the min
         and double check that everything is still fine.
         </p>
         <p>
-        Modify the build version number to correspond to the release version.  For example,

+        Make sure that the build version number corresponds to the release version.  For
example, 
         <code>commons-foo-1.2</code>.  What you are preparing at this point is
a candidate for release,
         which we will vote on and then push directly to the mirrors.  Clean build, run the
unit tests
         and check that the javadocs  have the correct version number.  Check in all changes.
@@ -425,8 +392,7 @@ The release notes should contain the min
 	<pre>
 	  svn update trunk
 	  svn cp trunk tags/foo-1.2-rc1
-	  svn commit -m "Tagging foo-1.2 RC1" tags/foo-1.2-rc1
-	</pre>
+	  svn commit -m "Tagging foo-1.2 RC1" tags/foo-1.2-rc1 </pre>
         <p>
         Note that the "svn update" step is necessary in order to ensure that the directory
being
         copied does not have a mix of files at various revisions; even if the files haven't
changed
@@ -436,25 +402,68 @@ The release notes should contain the min
         a clean copy is made.
 	</p>
 	<p>
-	Build distributions from a fresh checkout of that tag (as <a href='release.html'>per
full release</a>). 
+	Build distributions from a fresh checkout of the RC tag. 
 	Post the release candidate into the public folder <em>~/public_html</em> in
your home directory 
-        on <code>people.apache.org</code>. Note that the release candidate is
expected to have a name
+    on <code>people.apache.org</code>. Note that the release candidate is expected
to have a name
 	that includes RC so that there is no confusion later between release candidate distributions
 	and the real distribution that is eventually released.
-        </p>
+    </p>
     </subsection>
 
     <subsection name='Create the Release Candidate Website'>
-        <p>
-	As well as putting up the user distribution in your home directory on people.apache.org
for
-	others to download and verify, the new website should also be published there. If using
maven, 
-        run "mvn site" locally, tar or zip the site in target/ and scp and unpack the files
-        on people.apache.org.
+    <p>
+	As well as putting up the source and binary distributions in your home directory on people.apache.org
for
+	others to download and verify, the new website and maven artifacts should also be published
there. If using maven, 
+    run "mvn site" locally, tar or zip the site in target/ and scp and unpack the files
+    on people.apache.org.
 	</p>
 	<p>
-	The reports generated by maven (Clover, jCoverage, etc) are very useful things to inspect
in this
-	website.
-	</p>
+	The instructions for <a href="release.html">releasing to the mirrors</a> assume
the following directory
+	structure for the release candidate website, which you should set up in <code>public_html</code>
in your
+	home directory on people.apache.org, with "RC1" replaced by whatever the current RC number
is:
+	<pre>
+  ~/public_html/foo-1.2-RC1       (release notes, distribution tar/zips with sigs and hashes)
+  ~/public_html/foo-1.2-RC1/site  (output of "mvn site" run from the RC tag)
+  ~/public_html/foo-1.2-RC1/maven (maven pom, jars with sigs and hashes) </pre>
+	The following script creates a local directory <code>${release_path}</code>
with the appropriate contents.
+    This directory can then be renamed, tarred/zipped and copied to your public_html to be
unpacked there.  The
+	script variable <code>${repo_path}</code> needs to point to the local maven
repository root for the component,
+	for example: <pre>
+  version=1.2
+  repo_path=~/.m2/repository/org/apache/commons/commons-foo/${version}
+  release_path=~/foo-release </pre>
+  <pre>
+  # Generate the release artifacts and install them locally
+  mvn assembly:assembly
+  mvn -Prc -DcreateChecksum=true install
+  #
+  # Copy the zips/tarballs and release notes to release directory
+  rm -rf ${release_path}
+  mkdir ${release_path}
+  cp ${repo_path}/*.zip ${release_path}
+  cp ${repo_path}/*.zip.* ${release_path}
+  cp ${repo_path}/*.gz ${release_path}
+  cp ${repo_path}/*.gz.* ${release_path}
+  cp RELEASE-NOTES.txt ${release_path}
+  #
+  # Copy site
+  cp -R target/site ${release_path}
+  #
+  # Copy maven artifacts
+  cp -R ${repo_path} ${release_path}
+  #
+  # Rename maven, site directories
+  mv ${release_path}/${version} ${release_path}/maven
+  mv ${release_path}/site ${release_path}/docs
+  #
+  # Delete tars/zips from maven subdirectory
+  rm ${release_path}/maven/*.zip
+  rm ${release_path}/maven/*.zip*
+  rm ${release_path}/maven/*.gz
+  rm ${release_path}/maven/*.gz* </pre></p>
+    <p>
+    Be sure to check the signatures and hashes after copying and unpacking the files on people.apache.org.
+    </p>
 	<p>
 	Note that when verifying this candidate site you need to be careful of absolute
 	URLs; following these will lead to the currently published site, not to the 
@@ -464,40 +473,80 @@ The release notes should contain the min
   </section>
 
   <section name='Voting On Release'>
-    <subsection name='[VOTE] Release Foo 1.2'>
+    <subsection name='[VOTE] Release Foo 1.2 based on RC1'>
         <p>
         Once the release candidate has been created and uploaded, now it's time to propose
the release VOTE.
         </p>
         <p>
-        Post a <code>[VOTE] Release Foo 1.2</code> email to <strong>dev@commons.apache.org</strong>.
-        This should contain a link to the release candidate.
+        Post a <code>[VOTE] Release Foo 1.2 based on RC1</code> email to <strong>dev@commons.apache.org</strong>.
+        This should links to minimally the distributions, site and tag.  Here is an example
release VOTE message body:
+        <pre>
+  We have fixed quite a few bugs and added some significant enhancements since Foo 1.1 was
released,
+  so I would like to release Foo 1.2.
+
+  Foo 1.2 RC1 is available for review here:
+    http://people.apache.org/~luckyrm/foo-1.2-RC1/
+
+  Maven artifacts are here:
+    http://people.apache.org/~niallp/beanutils-1.8.3-rc1/m2/commons-beanutils/
+
+  Details of changes since 1.1 are in the release notes:
+    http://people.apache.org/~luckyrm/foo-1.2-RC1/RELEASE-NOTES.txt
+    http://people.apache.org/~luckyrm/foo-1.2-RC1/site/changes-report.html
+
+  I have tested this with JDK 1.3, 1.4, 1.5 and 1.6 using maven2.
+
+  The tag is here:
+    http://svn.apache.org/viewvc/commons/proper/foo/tags/FOO_1_2_RC1/
+
+  Site:
+    http://people.apache.org/~luckyrm/foo-1.2-RC1/site/
+  (note some *relative* links are broken and the 1.8.3 directories are
+  not yet created - these will be OK once the site is deployed)
+
+  Clirr Report (compared to 1.8.2):
+    http://people.apache.org/~luckyrm/foo-1.2-RC1/site/clirr-report.html
+
+  RAT Report:
+    http://people.apache.org/~luckyrm/foo-1.2-RC1/site/rat-report.html
+
+  Votes, please.  This vote will close in 72 hours, 0400 GMT 31-March 2010
+
+  [ ] +1 Release these artifacts
+  [ ] +0 OK, but...
+  [ ] -0 OK, but really should fix...
+  [ ] -1 I oppose this release because...
+
+  Thanks!
+
+  Lucky RM </pre>
         </p>
         <p>
         Votes from members of the Commons PMC are binding, however votes from other committers,
users and 
         contributors are welcomed.
-        If the <code>[VOTE]</code> is successful then continue. It is considered
good practice to allow
-        enough time for people to express their opinions.  
+        If the <code>[VOTE]</code> is successful then continue. Release VOTEs
should be left open for a
+        minimum of 72 hours so community members have ample opportunity to download, review
and test the
+        release candidate.  It is a good practice to, as above, specify the closing time
of the VOTE in
+        the VOTE message. 
         </p>
-        <!-- TODO: clean this up, adding 72 hour time, giving example and including what
links should
-             be in the VOTE message -->
 	<p>
-	If the vote fails, then fix the problem and create a
-	new release candidate (including creating another tag; tags are cheap!). Then call another
vote.
-	Creating a perfect release isn't easy, and it is quite common for the first few release
candidates
-	to fail, particularly on simple issues like missing license files.
+	If the vote fails, then fix the problem and create a new release candidate (including creating
another tag;
+	tags are cheap!). Then call another vote. Creating a perfect release isn't easy, and it
is quite common for
+    the first few release candidates to fail, particularly on simple issues like missing
license files. Don't
+    take negative feedback on RCs personally.  The release belongs to the community and we
are all accountable
+    for anything wrong or lacking in the code we release. That's why suggestions for improvement
are more often than not
+    accompanied by patches and/or commits to fix problems.  Always start a new VOTE thread
to vote on a new RC.
 	</p>
-        <!-- TDOD: include a sample RC-generating script - say scripts == good -->
         <p>
         Once a vote is successful, post a <code>[RESULT] Release Foo 1.2</code>
email to 
         <strong>dev@commons.apache.org</strong> as a reply to the original posting.
         This email should contain a summary of the voters/votes that were cast, eg
 	  <pre>
-	    The following people voted on release Foo 1.2:
+        The following people voted on release Foo 1.2:
         Bob +1
         Sue +1
         Sam +0
-        Sandy +1 (non-binding)
-	  </pre>
+        Sandy +1 (non-binding) </pre>
         </p>
         <p>
         Note that binding the VOTEs recorded need to be clearly designated in the RESULT.



Mime
View raw message