i've been cutting a release (the first i've cut for quite a while) so i
thought it'd be a good idea to try to improve the release documentation.
i came up with some improvements to the preparation document. i've
deployed a sample here:
http://people.apache.org/~rdonkin/commons-site/releases/prepare.html and
attached the patch.
please check. if there are no problems, i'll commit them.
- robert
Index: xdocs/releases/prepare.xml
===================================================================
--- xdocs/releases/prepare.xml (revision 202275)
+++ xdocs/releases/prepare.xml (working copy)
@@ -23,6 +23,17 @@
</properties>
<body>
+ <section name='Introduction'>
+ <p>
+ This document contains a mixture of information, advice and examples.
+ It is intended to be a recommendation of best practices.
+ Official guildlines for Jakarta and ASF releases are found elsewhere.
+ </p>
+ <p>
+ The examples below assume that preparation is being made to release version <em>1.2</em>
+ of component <em>Foo</em>.
+ </p>
+ </section>
<section name='Build Environments'>
<p>
Commons components are expected to use Maven to build the project website. Components
@@ -41,28 +52,49 @@
<subsection name='Select a Release Manager'>
<p>
A commons committer (normally one of the development team) should post an email to the
- development list proposing that a release be made, and that they volunteer to be release
- manager. Normal voting procedures apply.
+ development list proposing that a release be made and nominating a release manager.
+ Typically, this should be the proposer. Normal voting procedures apply (lazy consensus).
</p>
<p>
A release plan should also be prepared, in which the tasks remaining to be done before
the release are listed. It may be useful to prepare draft release notes before proposing
the release, so that others can see what changes are expected for the new release.
+ Preparing the required documents before the release and presenting them for public review
+ (as part of the plan) gives a better chance that any problems can be corrected at an early
+ stage.
</p>
<p>
- The examples below assume that preparation is being made to release version <em>1.2</em>
- of component <em>Foo</em>.
+ Many release managers favour development of the plan on the
+ <a href='http://wiki.apache.org/jakarta-commons'>wiki</a>.
+ This format encourages collaboration between developers and reduces the overhead
+ of maintaining the plan.
</p>
+ <p>
+ For complex releases, release managers should consider calling a vote on the release plan
+ (by lazy consensus). This may help to coordinate the execution of the plan and to ensure
+ that all developers are aware of the state of the plan.
+ </p>
</subsection>
<subsection name='Consider a Release Branch'>
<p>
- Consider whether a release branch is needed before preparing for the new release. A branch/tag
- must be made before the release candidate build can be voted upon, but whether this is done
- early in the process or later is a judgement call. Making the branch early allows development
+ Consider whether a release branch is needed before preparing for the new release.
+ During the preparation for a release, the changes made to the code needs to be tightly
+ controlled. The release manager should take particular care in reviewing all changes.
+ If a release branch is not taken then the trunk code will need to be frozen for
+ critical periods and normal development work suspended for the duration.
+ If a release branch is taken then work will be required to merge any changes back
+ into the trunk.
+ Whether a release branch is needed or not is a judgement call but the more active
+ the component, the more justified a release branch would be.
+ </p>
+ <p>
+ If a release branch is used then the branch
+ should be taken before the release candidate is cut and voted upon. Whether this is done
+ early in the process or later is a judgement call. Taking the branch early allows development
to continue on the trunk. However it means that any updates made as part of the preparations
for the release will later need to be merged into the trunk code. In general, commons
- components are small enough (ie development rate is low enough) that the branch/tag can be
+ components are small enough (ie development rate is low enough) that the branch can be
made later in the process (as each release candidate is generated).
</p>
<p>
@@ -81,11 +113,81 @@
a clean copy is made.
</p>
<p>
+ Including details of the branch strategy in the release plan aids coordination.
+ </p>
+ <p>
The description below assumes a release is being prepared on the trunk. The process is nearly
identical when preparing from a release branch; only the directory in which the work is
performed is different.
</p>
</subsection>
+ <subsection name='Check Compatibility'>
+ <p>
+ Consult the <a href='versioning.html'>Commons Versioning Guidelines</a> and check
+ that the current level of compatibility is suitable for the proposed version number.
+ Check the current level of compatibility in the code. Tools like
+ <a href='http://clirr.sourceforge.net'>Clirr</a> and
+ <a href='http://www.jdiff.org'>JDiff</a> are very useful. Both support ant and maven.
+ </p>
+ </subsection>
+ <subsection name='Check Javadocs And Code Style'>
+ <p>
+ Ensure all new classes and methods have <code>@since</code> tags.
+ Compatibility reports produced in the last section may prove helpful.
+ </p>
+ <p>
+ Ensure no errors or warnings are reported by the javadoc tool.
+ Check that the javadocs have the correct version number.
+ </p>
+ <p>
+ If the component uses checkstyle or PMD tools, examine the reports and fix all
+ problems.
+ </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.target</code> property in the
+ <code>project.properties</code> file should be set correctly.
+ If using ant, the <code>javac</code> task should have the <code>target</code>
+ attribute set correctly.
+ </p>
+ </subsection>
+ <subsection name='Check Documentation'>
+ <p>
+ Check that the documentation has been generated correctly. Check that all links are working.
+ Those using maven can use the
+ <a href='http://maven.apache.org/reference/plugins/linkcheck'>LinkCheck plugin</a> report
+ to automate this check.
+ </p>
+ </subsection>
+ <subsection name='(Maven Only) Consider Naming Of Source Distribution'>
+ <p>
+ By default, maven uses the same directory name for both binary and source distributions
+ (commons-foo-1.2). Some find it more convenient to have the source distribution unpack
+ to commons-foo-1.2-src. This can be done easily by adding a snippet of script to the
+ maven.xml file.
+ </p>
+ <p>
+ For example:
+ </p>
+ <pre>
+<![CDATA[
+ <preGoal name="dist:build-src">
+ ...
+ <move todir="${maven.dist.src.assembly.dir}-src">
+ <fileset dir="${maven.dist.src.assembly.dir}"/>
+ </move>
+ ...
+ </preGoal>
+]]>
+ </pre>
+ </subsection>
</section>
<section name="Creating a Release Candidate">
@@ -101,6 +203,7 @@
using values defined in the ant build.xml file. If the component's MANIFEST.MF file instead
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>
@@ -111,6 +214,19 @@
</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: Jakarta Commons Foo
+ Specification-Vendor: The Apache Software Foundation
+ Specification-Version: 1.2
+ Implementation-Title: org.apache.commons.foo
+ Implementation-Vendor: The Apache Software Foundation
+ Implementation-Version: 1.2
+ </pre>
</p>
</subsection>
@@ -127,12 +243,24 @@
<subsection name='Prepare Release Notes'>
<p>
- Each component should have a file RELEASE-NOTES.txt in the base directory of the component
- which contains a description of all the changes since the previous release. This file should
- be included within the distributions available for download.
- </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.
+ </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.
+ Long lines may need to be broken manually to allow them to be easily
+ read easily without word wrap.
+ </p>
<p>
- Different components have their own ways of creating release notes. Here's the most common way:
+ Different components have their own ways of creating the change log.
+ Here's the most common way:
</p>
<p>
Get a list of all the commits since the last release by following these steps.
@@ -140,15 +268,15 @@
Assuming that, as part of the last release, a directory {project-base}/tags/foo-1.1
had been created:
<pre>
- cd {project-base}/tags
+ cd {project-base}/tags
- svn log --stop-on-copy foo-1.1
- # The last revision NNNN reported in the log output is the revision that was
- # copied to create the tag. If this is a true tag directory, then of course
- # there will only be one revision listed by the log command..
+ svn log --stop-on-copy foo-1.1
+ # The last revision NNNN reported in the log output is the revision that was
+ # copied to create the tag. If this is a true tag directory, then of course
+ # there will only be one revision listed by the log command..
- cd ..
- svn log -v -rNNNN:HEAD trunk > commits-since-last-release.txt
+ cd ..
+ svn log -v -rNNNN:HEAD trunk > commits-since-last-release.txt
</pre>
</p>
<p>
@@ -184,6 +312,27 @@
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 check that the distribution build adds the release notes
+ to the binary distributions. It may be necessary to add some scripting to the <code>maven.xml</code>.
+ For example:
+ </p>
+ <pre>
+<![CDATA[
+ <preGoal name="dist:build-bin">
+ <copy todir="${maven.dist.bin.assembly.dir}">
+ <fileset file='${basedir}/RELEASE-NOTES.txt'/>
+ ...
+ </copy>
+ </preGoal>
+ <preGoal name="dist:build-src">
+ <copy todir="${maven.dist.src.assembly.dir}">
+ <fileset file='${basedir}/RELEASE-NOTES.txt'/>
+ ...
+ </copy>
+ </preGoal>
+]]>
+ </pre>
</subsection>
<subsection name='Test Against Listed Dependencies'>
@@ -192,8 +341,8 @@
there is nothing to do here; Maven will automatically perform the tests using the
library versions specified in the project.xml file.
</p>
- <p>
- If you are using Ant to execute unit tests, then ensure the Ant build.xml file
+ <p>
+ If you are using Ant to execute unit tests, then ensure the Ant build.xml file
references the same library versions as are listed as dependencies in the project.xml
file then execute the unit tests.
</p>
@@ -209,8 +358,13 @@
<subsection name='Check the Apache License'>
<p>
Check the <a href="http://www.apache.org/licenses/";>Apache Licenses</a> page for current information.
+ Check that each distribution contains a copy of the license.
+ 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.
+ </p>
+ <p>
Developer documentation on how to apply the Apache License
can be found in <a href="http://www.apache.org/dev/apply-license.html";>Applying the Apache License, Version 2.0</a>
</p>
@@ -242,15 +396,66 @@
for an example that provides all of the notices applicable to the
httpd-2.0 distribution.
</p>
+ </subsection>
+
+ <subsection name='Check NOTICE.txt'>
<p>
- Also check that the years in the copyright statement in the license in each source file and
- in the component <code>LICENSE.txt</code> have been updated appropriately.
+ The component should contain a NOTICE.txt (next to the LICENSE.txt).
+ If this is not present, it must be created.
+ The basic content (excepting external attributes notes) should be:
</p>
+ <pre>
+ This product includes software developed by
+ The Apache Software Foundation (http://www.apache.org/).
+ </pre>
+ <p>
+ The NOTICE.txt must be distributed along with the LICENSE.txt.
+ Check that the distribution build correct adds this file
+ to the distributions.
+ Those using maven may need to add some scripting to the maven.xml.
+ For example:
+ </p>
+ <pre>
+<![CDATA[
+ <preGoal name="dist:build-bin">
+ <copy todir="${maven.dist.bin.assembly.dir}">
+ ...
+ <fileset file='${basedir}/NOTICE.txt'/>
+ </copy>
+ </preGoal>
+ <preGoal name="dist:build-src">
+ <copy todir="${maven.dist.src.assembly.dir}">
+ ...
+ <fileset file='${basedir}/NOTICE.txt'/>
+ </copy>
+ </preGoal>
+]]>
+ </pre>
+ <p>
+ Check that the jar contains a copy of the NOTICE.txt in the META-INF directory.
+ Those using maven may need to add NOTICE.txt to the build resources section
+ of the project.xml. For example:
+ </p>
+ <pre>
+<![CDATA[
+ <resources>
+ <resource>
+ <directory>${basedir}</directory>
+ <targetPath>META-INF</targetPath>
+ <includes>
+ <include>NOTICE.txt</include>
+ </includes>
+ </resource>
+ ...
+ </resources>
+]]>
+ </pre>
</subsection>
-
<subsection name='Create the Release Candidate'>
<p>
Once all the preparations agreed in the release plan has been completed, create a Release Candidate.
+ Before taking the tag from which the release candidate will be taken, run the distribution build
+ and double check that everything is still fine.
</p>
<p>
Modify the build version number to indicate that this build is a release candidate. For example,
@@ -258,14 +463,14 @@
have the correct version number.
</p>
<p>
- Now create a tag:
+ Now create the tag for the release candidate. For example (cutting the candidate from the trunk):
+ </p>
<pre>
svn update trunk
svn cp trunk tags/foo-1.2-rc1
svn commit tags/foo-1.2-rc1
</pre>
- </p>
- <p>
+ <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
since the last svn update this can cause "svn log -v" on the new directory to report files as
@@ -347,11 +552,15 @@
<subsection name='Final Preparations'>
<p>
- Update the version number in the project.xml (and possibly build.xml) so that it reflects
+ Update the version number in the project.xml (and possibly build.xml) so that it reflects
the release (rather than the release candidate). Clean build and test. Double check that
the version number is correct by examining the documentation.
</p>
<p>
+ Do <code>svn status</code> to check that all files have been committed.
+ Finally do <code>svn update</code> to check for any new commits.
+ </p>
+ <p>
Tag the release now:
<pre>
svn cp trunk tags/foo-1.2
@@ -360,6 +569,9 @@
<p>
You're now ready to <a href='release.html'>cut the release</a>.
</p>
+ <p>
+ Remember to update the main website when the candidate has been cut.
+ </p>
</subsection>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
