Author: psteitz
Date: Sun Mar 28 22:17:30 2010
New Revision: 928503
URL: http://svn.apache.org/viewvc?rev=928503&view=rev
Log:
First pass edits to eliminate obsolete m1 references and start to improve m2
docs.
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=928503&r1=928502&r2=928503&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
Mar 28 22:17:30 2010
@@ -40,7 +40,7 @@
Commons components are expected to use Maven to build the project website.
Components
may choose to use either Maven or Ant to build the actual jar files to be
distributed,
although it is recommended that Maven be used for this. Both approaches
are covered
- below.
+ below. The version of maven used is assumed to be Maven 2 throughout.
</p>
<p>
This document assumes that the release is being prepared on a linux/unix
system, and
@@ -66,7 +66,7 @@
stage.
</p>
<p>
- Many release managers favour development of the plan on the
+ Many release managers favor development of the plan on the
<a href='http://wiki.apache.org/commons'>wiki</a>.
This format encourages collaboration between developers and reduces the
overhead
of maintaining the plan.
@@ -105,7 +105,7 @@
cd to the project's base directory in your subversion working copy.
svn update trunk
svn cp trunk branches/foo-1.2-work
- svn commit branches/foo-1.2-work
+ svn commit -m "Creating foo-1.2-work branch" branches/foo-1.2-work
</pre>
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
@@ -129,7 +129,7 @@
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.
+ <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'>
@@ -154,60 +154,30 @@
on that JVM.
</p>
<p>
- If using Maven 1, 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>
+ If using maven, the <code>maven.compile.target</code> property in the
+ <code>pom.xml</code> file should be set correctly.
+ If using ant, the <code>javac</code> task should have the
<code>target</code>
attribute set correctly.
</p>
<p>
- The Maven 1 build now adds entries to the jar's manifest to show the values
+ The maven build now adds entries to the jar's manifest to show the values
of the <code>maven.compile.source</code> and
<code>maven.compile.target</code>
properties used to generate the jar. For more details on this see sections
<a href="#checkjarmanifest">Check The Jar Manifest</a> and
<a href="#classfileformat">Class File Format</a> for more details.
</p>
<p>
- For Maven 2 builds, the Commons parent POM specifies default values for
+ For Maven builds, the Commons parent POM specifies default values for
<code>maven.compile.source</code> and <code>maven.compile.target</code>.
These
- values should be overridden in the project's POM if they're not
appropriate for it.
+ values must be overridden in the project's POM if they're not appropriate
for it.
</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/maven-1.x/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 the following
line to the
- component's project.properties file:
- </p>
- <p>
- <pre>
-
maven.dist.src.assembly.dir=${maven.dist.assembly.dir}/src/${maven.final.name}-src
- </pre>
- </p>
- <p>
- Maven 2 builds use assembly descriptors, which by default live in
<code>src/assembly</code>.
- By convention, <code>src.xml</code> is for source distributions and
<code>bin.xml</code>
- is for binary distributions. You can specify the
<code>baseDirectory</code> property
- in <code>src.xml</code> to include -src:
- <pre>
-<![CDATA[
-<assembly>
- ...
- <baseDirectory>${project.artifactId}-${project.version}-src</baseDirectory>
- ...
-</assembly>
-]]>
- </pre>
</p>
</subsection>
+ <!-- TODO: add a subsection on commons properties in the pom and assembly
descriptors -->
</section>
<section name="Creating a Release Candidate">
@@ -219,7 +189,7 @@
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
+ 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>
@@ -235,26 +205,17 @@
</pre>
</p>
<p>
- These entries are created by specifying appropriate entries in the
<code>project.properties</code>
- file:
- <pre>
-
maven.jar.manifest.attributes.list=X-Compile-Source-JDK,X-Compile-Target-JDK
- maven.jar.manifest.attribute.X-Compile-Source-JDK=${maven.compile.source}
- maven.jar.manifest.attribute.X-Compile-Target-JDK=${maven.compile.target}
- </pre>
- </p>
- <p>
- Maven 2 builds have these properties automatically inserted if the POM
inherits
+ 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 2 are vigorously encouraged to use the parent POM.
+ 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
+ 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>
@@ -305,6 +266,7 @@
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 -->
</p>
<p>
The release notes should contain the minimum target Java version for the
component.
@@ -317,7 +279,11 @@ The release notes should contain the min
</p>
<p>
Different components have their own ways of creating the change log.
- Here's the most common way:
+ The most common, and recommended, way, is to record all significant
+ changes in JIRA tickets and include entries in the maven change-log
+ file, <code>changes.xml</code>.
+ Here's a way to get the information directly from svn if no change log
+ has been maintained for the component:
</p>
<p>
Get a list of all the commits since the last release by following
these steps.
@@ -370,29 +336,8 @@ The release notes should contain the min
be used with the -r option. See issue #752 in the subversion issue
tracker at tigris.org.
</p>
<p>
- Those using Maven 1 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>
- <p>
- Maven 2 users should make sure to configure this in the assembly
descriptors in
- src/assembly as described above.
+ 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>
@@ -410,10 +355,7 @@ The release notes should contain the min
</subsection>
<subsection name='Ensure a good build.xml'>
- <p>
- If using Maven, and a hand-built Ant build.xml file does not exist in
the project, then
- ensure that 'maven ant' (for Maven 1) or 'mvn ant:ant' (for Maven 2)
has been run so a usable build.xml file exists.
- </p>
+ <!-- TODO: test both ant and maven builds and drop stuff that does not
work -->
</subsection>
<subsection name='Check the Apache License'>
@@ -466,6 +408,9 @@ The release notes should contain the min
The basic content (excepting external attributes notes) should be:
</p>
<pre>
+ Apache Commons {Foo}
+ Copyright {earliest}-{latest} The Apache Software Foundation
+
This product includes software developed by
The Apache Software Foundation (http://www.apache.org/).
</pre>
@@ -473,46 +418,6 @@ The release notes should contain the min
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>
- <p>
- Maven 2 builds have this automatically taken care of by the Commons
parent POM.
</p>
</subsection>
<subsection name='Create the Release Candidate'>
@@ -522,9 +427,10 @@ The release notes should contain the min
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,
- <code>commons-foo-1.2RC1</code>. Clean build, run the unit tests and
check that the javadocs
- have the correct version number.
+ Modify the build version number to correspond 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.
</p>
<p>
Now create the tag for the release candidate. For example (cutting the
candidate from the trunk):
@@ -532,7 +438,7 @@ The release notes should contain the min
<pre>
svn update trunk
svn cp trunk tags/foo-1.2-rc1
- svn commit tags/foo-1.2-rc1
+ 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
@@ -543,7 +449,7 @@ The release notes should contain the min
a clean copy is made.
</p>
<p>
- Build distributions from that tag (as <a href='release.html'>per full
release</a>).
+ Build distributions from a fresh checkout of that tag (as <a
href='release.html'>per full release</a>).
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
that includes RC so that there is no confusion later between release
candidate distributions
@@ -554,52 +460,12 @@ The release notes should contain the min
<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.
+ 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>
<p>
- For Maven 1 builds, temporarily edit the project.xml file tag
<siteDirectory> to point to something like:
- <pre>
- <siteDirectory>public_html/foo-1.2rc1/site</siteDirectory>
- </pre>
- then run
- <pre>
- maven site:generate
- maven -Dmaven.username=yourapacheid site:deploy
- </pre>
- </p>
- <p>
- Maven 2 builds should temporarily add a site location to the
<distributionManagement>:
- <pre>
-<![CDATA[
- <distributionManagement>
- <id>stagingSite</id>
-
<url>scp://people.apache.org/home/<apacheuser>/public_html/foo-1.2rc1/site</url>
- </distributionManagement>
-]]>
- </pre>
- and then run
- <pre>
- mvn site:stage-deploy
- </pre>
- To save time entering your username and password, you can edit your
- <code>~/.m2/settings.xml</code> to specify them:
- <pre>
-<![CDATA[
- <settings>
- <servers>
- <server>
- <id>stagingSite</id>
- <username>...</username>
- <password>...</password>
- </server>
- <server>
- </servers>
- </settings>
-]]>
- </pre>
- </p>
- <p>
- The reports generated by Maven (Clover, jCoverage, etc) are very useful
things to inspect in this
+ The reports generated by maven (Clover, jCoverage, etc) are very useful
things to inspect in this
website.
</p>
<p>
@@ -623,14 +489,17 @@ The release notes should contain the min
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.
+ enough time for people to express their opinions.
</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, update the version number
(RC2, RC3, ...) and create a
+ 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.
</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.
@@ -644,7 +513,7 @@ The release notes should contain the min
</pre>
</p>
<p>
- Note that binding the VOTEs recorded need to clearly deliminated in
the RESULT.
+ Note that binding the VOTEs recorded need to be clearly designated 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.
@@ -652,30 +521,6 @@ The release notes should contain the min
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
- 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
- </pre>
- </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>
<section name='Things To Look For When Inspecting A Release Candidate'>
@@ -685,7 +530,7 @@ The release notes should contain the min
<subsection name="API Changes">
<p>
- Accidental non-compatible API changes in a minor release. The jdiff
report
+ Accidental non-compatible API changes in a minor release. The clirr
report
generated by Maven is very useful in spotting these.
</p>
</subsection>
@@ -697,18 +542,6 @@ The release notes should contain the min
</ul>
</subsection>
- <subsection name="project.xml (aka POM)">
- <p>
- project.xml, used by Maven to generate that site, has some data which
may have become stale.
- Make sure it isn't before releasing. Look at the dependencies report,
todo report,
- and other reports.
- </p>
- <ul>
- <li>Ensure dependencies are correct</li>
- <li>Ensure completed tasks are removed from todo list</li>
- </ul>
- </subsection>
-
<subsection name="Code Style">
<p>
Many projects enforce coding styles using the CheckStyle or PMD tools. If
your
@@ -723,14 +556,14 @@ The release notes should contain the min
format has changed a number of times over the years, and code compiled
with
a modern JVM may fail to load in an older JVM with the error message
"invalid class file format" unless the code is compiled with appropriate
- options set. If you are using Maven, then ensure that project.properties
+ options set. If you are using Maven, then ensure that your pom
has maven.compile.target set to the minimum JVM version your binary is
intented to support. If you are using Ant, then ensure that the javac
task
has xml attribute "target" is set to the appropriate JVM version.
</p>
<p><strong>Maven Build</strong></p>
<p>
- The Maven build has been modified to include two <strong><i>non
standard</i></strong> attributes
+ 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>
@@ -755,93 +588,8 @@ The release notes should contain the min
included jars.
</p>
<p>
- Maven 2 builds default to including this, so no further effort is required
- for those projects. To make sure that this file is included in Maven
1-generated <i>jars</i>,
- include the following in the build section of your project.xml (or just
add the
- resource defined below to the build resources you already have).
- </p>
- <pre>
-<![CDATA[
-<resources>
- <resource>
- <directory>${basedir}</directory>
- <includes>
- <include>NOTICE.txt</include>
- </includes>
- <targetPath>META-INF</targetPath>
- </resource>
-</resources>
-]]>
- </pre>
- <p>
- To make sure that this file is included in the top-level directory of
source and binary
- distribution files (zips and tars), define preGoals for Maven's dist goal
that copy
- NOTICE.txt to the source and binary assembly directories that it uses to
package the
- release. To do this, add the snippet below to maven.xml.
- </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>
- If you use Maven 2, you should also build source and javadocs jars
according to Maven 2
- standards. You can use the following antrun-plugin configuration to
accomplish this:
- <pre>
-<![CDATA[
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-antrun-plugin</artifactId>
- <executions>
- <execution>
- <goals>
- <goal>run</goal>
- </goals>
- <phase>package</phase>
- <configuration>
- <tasks>
- <copy todir="${project.build.directory}/site/api-release">
- <fileset dir="${project.build.directory}/site/apidocs"/>
- </copy>
- <zip
destfile="${project.build.directory}/${artifactId}-${version}-javadoc.jar.new">
- <zipfileset
src="${project.build.directory}/${artifactId}-${version}-javadoc.jar"/>
- <zipfileset dir="." prefix="META-INF">
- <include name="LICENSE.txt"/>
- <include name="NOTICE.txt"/>
- </zipfileset>
- </zip>
- <move
file="${project.build.directory}/${artifactId}-${version}-javadoc.jar.new"
-
tofile="${project.build.directory}/${artifactId}-${version}-javadoc.jar"/>
- <zip
destfile="${project.build.directory}/${artifactId}-${version}-sources.jar.new">
- <zipfileset
src="${project.build.directory}/${artifactId}-${version}-sources.jar"/>
- <zipfileset dir="." prefix="META-INF">
- <include name="LICENSE.txt"/>
- <include name="NOTICE.txt"/>
- </zipfileset>
- </zip>
- <move
file="${project.build.directory}/${artifactId}-${version}-sources.jar.new"
-
tofile="${project.build.directory}/${artifactId}-${version}-sources.jar"/>
- </tasks>
- </configuration>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-]]>
- </pre>
- It is a good idea to bind this to a particular profile, such as "release",
so that it
- doesn't run in the default lifecycle and thus in every build.
+ Maven builds default to including this, so no further effort is required
+ for those projects.
</p>
</subsection>
</section>
