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>
+ <properties>
+ <commons.componentid>foo</commons.componentid>
+ <commons.release.version>1.2</commons.release.version>
+ <commons.binary.suffix></commons.binary.suffix>
+ <commons.jira.id>FOO</commons.jira.id>
+ <commons.jira.pid>007</commons.jira.pid>
+ <maven.compile.source>1.3</maven.compile.source>
+ <maven.compile.target>1.3</maven.compile.target>
+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
+ <properties> </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>
+ <template>foo-release-notes.vm</template<
+ <templateDirectory<templates</templateDirectory> </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>[email protected]</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>[email protected]</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>[email protected]</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.
