- 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.

- 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 properties + section of the pom: +

- 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: +

- - -

Maven Build

- 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. -

- The maven build has been modified to include two non standard attributes - in the jar's manifest to indicate the maven.compile.source and - maven.compile.target properties used to create the jar. This serves two purposes: -

To provide comfort to users regarding JVM compatibility.
Enable releases to be checked more easily for JVM compatibility.

- The entries created in the manifest will look something like the following: -

-      X-Compile-Source-JDK: 1.3
-      X-Compile-Target-JDK: 1.3
-

- 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. -

Ant Build

- 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 - 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: -

- Sun Manifest Format -
- - Sun Package Versioning Standards - -

- 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: -

-	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
-

@@ -245,18 +206,31 @@

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. - + 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.

-The release notes should contain the minimum target Java version for the component. -

+ 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: +

+    mvn changes:announcement-generate
+    mv target/announcement/foo-release-notes.vm RELEASE-NOTES.txt

+ For this to work, the following properties need to be included in the configuration + for the maven-changes-plugin in the pom: +

+    <template>foo-release-notes.vm</template<
+    <templateDirectory<templates</templateDirectory>

+ and the Velocity template, foo-release-notes.vm needs to be defined in + src/main/resources/templates.

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.

- 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. -

@@ -340,10 +310,6 @@ The release notes should contain the min

- - - -

Check the Apache Licenses 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.

- 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.

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:

- Do I have to have a copy of the license header in each source file? + Do I have to have a copy of the license in each source file? Maven builds can use the RAT plugin to + generate a license report.

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.

- 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, commons-foo-1.2. 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

 	  svn update trunk
 	  svn cp trunk tags/foo-1.2-rc1
-	  svn commit -m "Tagging foo-1.2 RC1" tags/foo-1.2-rc1
-

+ svn commit -m "Tagging foo-1.2 RC1" tags/foo-1.2-rc1

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.

- Build distributions from a fresh checkout of that tag (as per full release). + Build distributions from a fresh checkout of the RC tag. Post the release candidate into the public folder ~/public_html in your home directory - on people.apache.org. Note that the release candidate is expected to have a name + on people.apache.org. 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. -

- 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. +

+ 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.

- The reports generated by maven (Clover, jCoverage, etc) are very useful things to inspect in this - website. -

+ The instructions for releasing to the mirrors assume the following directory + structure for the release candidate website, which you should set up in public_html in your + home directory on people.apache.org, with "RC1" replaced by whatever the current RC number is: +

+  ~/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)

+ The following script creates a local directory ${release_path} 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 ${repo_path} needs to point to the local maven repository root for the component, + for example:

+  version=1.2
+  repo_path=~/.m2/repository/org/apache/commons/commons-foo/${version}
+  release_path=~/foo-release

+  # 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*

+ Be sure to check the signatures and hashes after copying and unpacking the files on people.apache.org. +

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

- +

Once the release candidate has been created and uploaded, now it's time to propose the release VOTE.

- Post a [VOTE] Release Foo 1.2 email to dev@commons.apache.org. - This should contain a link to the release candidate. + Post a [VOTE] Release Foo 1.2 based on RC1 email to dev@commons.apache.org. + This should links to minimally the distributions, site and tag. Here is an example release VOTE message body: +

+  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

Votes from members of the Commons PMC are binding, however votes from other committers, users and contributors are welcomed. - If the [VOTE] is successful then continue. It is considered good practice to allow - enough time for people to express their opinions. + If the [VOTE] 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.

- 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.

Once a vote is successful, post a [RESULT] Release Foo 1.2 email to dev@commons.apache.org as a reply to the original posting. This email should contain a summary of the voters/votes that were cast, eg

-	    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)
-

+ Sandy +1 (non-binding)

Note that binding the VOTEs recorded need to be clearly designated in the RESULT.