Author: rdonkin
Date: Wed Jun 29 13:28:03 2005
New Revision: 202421
URL: http://svn.apache.org/viewcvs?rev=202421&view=rev
Log:
Improved to release preparation documentation.
Modified:
jakarta/commons/proper/commons-build/trunk/xdocs/releases/prepare.xml
Modified: jakarta/commons/proper/commons-build/trunk/xdocs/releases/prepare.xml
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/commons-build/trunk/xdocs/releases/prepare.xml?rev=202421&r1=202420&r2=202421&view=diff
==============================================================================
--- jakarta/commons/proper/commons-build/trunk/xdocs/releases/prepare.xml
(original)
+++ jakarta/commons/proper/commons-build/trunk/xdocs/releases/prepare.xml Wed
Jun 29 13:28:03 2005
@@ -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 guidelines 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,50 @@
<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
+ (<a
href='http://www.apache.org/foundation/glossary.html#LazyConsensus'>lazy
consensus</a>).
</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>
+ 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>
- The examples below assume that preparation is being made to release
version <em>1.2</em>
- of component <em>Foo</em>.
+ 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 (i.e. development rate is low enough) that
the branch can be
made later in the process (as each release candidate is generated).
</p>
<p>
@@ -77,15 +110,85 @@
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
having been (R)eplaced. Alternatively, use "svn cp URL1 URL2" which will
copy files
- internally within the repository without using the local working copy;
this always ensures
+ internally within the repository without using the local working copy:
this always ensures
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
+ 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">
@@ -97,10 +200,12 @@
</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 @varname@ strings which are replaced
dynamically by an Ant copy task
+ 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
- hard-wires values then it should be fixed to use appropriate ant
variables. Useful reference
+ 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>
@@ -111,6 +216,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 +245,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 +270,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 +314,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 +343,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,6 +360,11 @@
<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
@@ -242,15 +398,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>
+ 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>
- 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 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 +465,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
@@ -321,7 +528,7 @@
</p>
<p>
As per the Commons Project charter, votes of committers on the
particular package in question
- (as listed in the <code>project.xml</code> file) are binding.
+ (as listed in the <code>project.xml</code> file) are binding.
If the <code>[VOTE]</code> is successful then continue. It is
considered good practice to allow
enough time for people to express their opinions.
</p>
@@ -338,20 +545,33 @@
of the voters/votes that were cast, eg
<pre>
The following people voted on release Foo 1.2:
- Bob +1
- Sue +1
- Sam +0
+ Bob +1
+ Sue +1
+ Sam +0
+ Sandy +1 (non-binding)
</pre>
</p>
+ <p>
+ Note that binding the VOTEs recorded need to clearly deliminated in
the RESULT.
+ This may be done by either stating only the binding votes (and
indicating that to be the case)
+ or by adding <code>(non-binding)</code> to those which are not.
+ It is best practice to indicate how each person.
+ This allows any mistakes to be caught and corrected early.
+ If you do vote, please check the results to ensure that your vote has
been correctly tallied.
+ </p>
</subsection>
<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
@@ -359,6 +579,9 @@
</p>
<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]
