commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject svn commit: r928503 - /commons/proper/commons-site/trunk/src/site/xdoc/releases/prepare.xml
Date Sun, 28 Mar 2010 22:17:31 GMT
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 &lt;siteDirectory&gt;
to point to something like:
-	<pre>
-	  &lt;siteDirectory&gt;public_html/foo-1.2rc1/site&lt;/siteDirectory&gt;
-	</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 &lt;distributionManagement&gt;:
-        <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>dev@commons.apache.org</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>



Mime
View raw message