Steps to take to cut a release of a Tuscany module. This pages describes the general process rather than the content of any individual module or any specific release.

General Principles

A "Release" at Apache is the publication of a work under the terms of the Apache License. Releases are authorized by a PMC Chair under advisement from the PMC. What this means in practice is that the project decides to release some file (such as a distribution archive), the PMC votes on that file or set of files, and if the vote passes the files are "Released." A PMC member should only vote in favour of a release if they believe the content complies with the policies of the Foundation (for example, that there are not legal issues affecting the Foundation) and should vote against if they are aware of any issues.

A project community may choose to add additional constraints to what goes into a release. These are often around technical matters such as does the code have the expected features, does it build, does it work and so forth. There's nothing to stop a project releasing poor quality code, except the ridicule that may follow from one's peers or the deluge of email from the users.

Release Content

The content of our releases will typically consist of three types of artifacts:

A user should be able to unpack a source distribution and build any of the other binary releases in the same way a developer did when the release was cut. A source archive is often no more than an archive of the development tree associated with a tag.

Binary distributions provide something a user might download and install. This could be a runtime environment, or it could be a package containing various libraries and documentation.

Development resources are separate libraries published through some repository system such as Maven's or Eclipse's. They are directly accessible by some client environment (such as Maven or Eclipse) as plugins or dependencies and are published in a form that the client tool understands.

Release Process

There are four basic steps to the release process:

  1. Preparing to Release
  2. Cutting a Tag
  3. Producing Source Distribution
  4. Producing Binary Distribution

Preparing to Release

Write some code and see that it works. OK, now the easy bit is over, it's time to release it.

One of the purposes of the release vote is to confirm that the code being released is code that the Foundation's Policies allow it to release. The Foundation entrusts this review to the PMC members for the project. Things that should be checked include:

Dependency Review

In addition to a legal review of third-party code it is important to review the stability of the dependency. When working with Maven it is important to verify that the release does not depend on any unstable SNAPSHOT artifacts, whether they are produced by your project or a third party. This is not just library <dependencies> but also any external POMs or plugins.

Generating a PGP Key

Apache Releases are widely distributed over the Internet and often replicated though several mirror systems and as such it is important that users are able to verify the integrity of the distribution they receive. The usual way this is done at Apache is by signing the release with an external PGP signature file. The file is generated by the Release Manager before uploading the distribution. The corresponding public key should be recorded in the KEYS file in the project SVN and uploaded to one of the public keyservers.

Cutting a Tag

Cutting a Tag comprises of creating a directory in SVN that contains the source code for the release. This is most easily done if all of the source code for the release is contained in single SVN directory; if not, consider writing a script to make the copy.

The copy can refer to any SVN revision and does not have to reflect the trunk at the time the tag is made. Once the community agrees on the revision to use,  svn copy -r${rev}  can be used to copy that revision to the tag.

Once a local copy has been made any inter-module references to SNAPSHOT versions should be replaced with the version for the tag (remember any references to external SNAPSHOT versions should already have been resolved.

Any external files (for example, the STATUS file from the project) that may be needed for the release should be copied in.

Finally, the directory for the tag should be committed to SVN.

Producing Source Distribution

In an ideal world, a source distribution is just an archive of the code from the tag in SVN. It helpful the text in the source has the same line-ending style associated with the archive format (CRLF for .zip, LF for .tgz). This can be achieved with svn export:

ZIP Files for Windows Users

$ svn export --native-eol CRLF ${base}/${tag}
$ jar cMf ${archive}.zip -C ${tag} .
$ gpg --armor --detach-sig --output ${archive}.zip.asc ${archive}.zip

Compressed TAR for *nix Users

$ svn export --native-eol LF ${base}/${tag}
$ ( cd ${tag} ; tar czf ../${archive}.tgz . )
$ gpg --armor --detach-sig --output ${archive}.tgz.asc ${archive}.tgz

Producing Binary Distribution

Any binary distribution should be produced automatically by building a source distribution (or by checking its tag out from SVN). The entire process should be automatic with no user intervention required. How to do this should be clearly described in the BUILDING.txt file in the root of the source distribution.

All binary distributions generated should be signed and posted to a staging area ready for voting.

With a Maven build, development artifacts can be uploaded to the distribution repository using the deploy goal. The current version of Maven does not allow them to be signed prior to deployment so the signatures must be generated and uploaded manually.

Voting

Once the release artifacts have been generated then a vote can be called to authorize their release. This must be done before the artifacts are distributed from the ASF (for example, through the mirror systems or through replication to ibiblio).

To vote a thread should be sent to the development list with [VOTE] in the subject and links to all the (signed) artifacts being voted on. All PPMC votes count, with three +1 votes and more +1 than -1 votes needed to pass (there are no vetos). A PPMC member should review the release archives before voting on them.

As an Incubator Podling, PPMC votes are not sufficient to authorize a release by the ASF. If the PPMC vote passes, a vote will be initiated for the Incubator PMC itself to authorized the release. The goal is to make this is simple as possible by ensuring any review has already been done; however, Incubator PMC members will still perform their own review. If that vote passes then the release is done.