The Jakarta Commons project differs from many other Jakarta hosted projects because it is comprised of multiple, independently released packages. Therefore, the release procedure for an individual package needs to be documented so that package authors follow consistent practices.

Individual packages (such as Collections) might vary from these practices because they are somewhat larger than the typical Commons package, but these steps should prove sufficient for the majority of cases.

The following steps are required to create and deploy a release version of a Commons library package. The example text consistently assumes that we are releasing version 1.2 of the foo package.

For components other than Collections:

1. Announce your proposed release of a particular package to the commons-dev@jakarta.apache.org mailing list, and ask for a vote. Per the Commons Project charter, votes of committers on the particular package in question (as listed in the STATUS.html file) are binding.
   
   
2. Log on to jakarta.apache.org (via SSH) and create a new subdirectory for the release you are about to create. For example:

   cd /www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/
   mkdir v1.2
   

3. Check out and thoroughly test the package code that you plan to release.
   
   
4. Update the project version number in the build.xml file for this project. If the foo project follows the usual build.xml conventions, there will be an Ant property named component.version that would be updated to 1.2. Check in any files you have modified.
   
   
5. Tag only the files in the subdirectory for this package with the package name (in caps) and version number for the package you are creating. For example,

   cd $JAKARTA_COMMONS_HOME/foo
   cvs tag FOO_1_2
   

6. Regenerate the binary distribution of the code by running the dist target. Review the generated documentation to ensure that it correctly reflects the functionality (and the version number) of this code.
   
   
7. Based on the contents of the dist subdirectory that was created by the previous step, create the binary distributions for this release. For example,

   cd $JAKARTA_COMMONS_HOME/foo
   mv dist commons-foo-1.2
   tar zcvf commons-foo-1.2.tar.gz commons-foo-1.2
   zip -r commons-foo-1.2.zip commons-foo-1.2
   mv commons-foo-1.2 dist
   

8. Upload the binary distribution files to the newly created directory on daedalus. For example (where "xyz" is your login),

   cd $JAKARTA_COMMONS_HOME/foo
   scp commons-foo-1.2.* \
    xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/
   

9. Log in to cvs.apache.org and create the source distributions, based on the tag specified earlier, and move these files to the distribution directory as well. For example (where "xyz" is your login),

   mkdir temp
   cd temp
   cvs -d /home/cvspublic export -r FOO_1_2 jakarta-commons
   mv jakarta-commons commons-foo-1.2-src
   tar zcvf commons-foo-1.2-src.tar.gz commons-foo-1.2-src
   zip -r commons-foo-1.2-src.zip commons-foo-1.2-src
   rm -rf commons-foo-1.2-src
   scp commons-foo-1.2-src.* \
     xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/
   

10. Follow standard procedures to update the Jakarta web site (stored in CVS repository jakarta-site2 to reflect the availability of the new release. Generally, you will be updating the following pages:
    • xdocs/site/binindex.xml - Create a link to the release directory under the Release Builds heading.
    • xdocs/site/sourceindex.xml - Create a link to the release directory under the Release Builds heading.
    • xdocs/site/news.xml - Create a news item that describes the new release, and includes hyperlinks to the release directory.
    
    
    
11. Announce the availability of the new package on (at least) the following mailing lists:
    • announcements@jakarta.apache.org
    • general@jakarta.apache.org
    • commons-dev@jakarta.apache.org
    
    
    

For Collections:

1. Follow steps 1-5 above.
2. Review the build.xml file to make sure that the "cvs.tag" property is set correctly. For example,

   <property name="cvs.tag" value="FOO_1_2"/>

3. Review the build.properties file to make sure that the "cvs.root" property is set correctly. For example,

   ## in build.properties where "xyz" is your login
   cvs.root=:pserver:xyz@localhost:/home/cvs
   

4. From the component directory, run ant clean dist dist-src.
5. Upload the binary distribution files to the newly created directory on daedalus. For example (where "xyz" is your login),

   cd $JAKARTA_COMMONS_HOME/foo/dist
   scp commons-foo-1.2* \
    xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/
   

6. Copy the release notes to daedalus. For example (where "xyz" is your login),

   cd $JAKARTA_COMMONS_HOME/foo/dist
   scp RELEASE-NOTES-1.2.html \
    xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/
   

7. Update the components.xml and the collections.xml (including the link to the STATUS.html) files. Run the ant command at the root of the jakarta-commons module, which will build HTML versions of those documents in the docs directory. Check in the generated docs.
8. Copy the API docs from the Collections build to the jakarta-commons/docs/collections/api directory in CVS. Be sure to remove Javadocs for any Collections that have been permanently deleted.
9. Log onto jakarta.apache.org and perform a CVS update to grab the new site documentation:

   cd /www/jakarta.apache.org/commons/
   cvs update
   

10. Follow steps 10-11 above.