• Java-specific Release Management Issues (DRAFT)
  • Contents
• Release Guidelines
• Best Practice
  • Jars
  • Artifact Naming
  • Compression Formats
  • Source Package Build
  • Distributing Libraries
  • Dependencies
  • Maven
• Notes
  • Distributing Jars
  • Jar MANIFEST
  • Compatibility Checkers
  • Change Logs
  • On Java Versions
  • On Line Endings
  • On Signing Jars
  • Implementations Of Standards
    • JSRs
  • On Java Release Candidates
• Glossary
  • Jar MANIFEST

• META-INF
  • Must include LICENSE and NOTICE. Note this
  • Should include a standards compliant MANIFEST. Note this.

TODO: should include apache in the title (gives trademark protection against different jars with the same name)

Note (TODO link) that there are known compatibility issues when using certain tar programs. (TODO Saris verses GNU tar) It is recommend that project that use Ant or Maven as build tools, use these tools to create the archives since these implementations work well across a range of platforms. It is recommended that project which do not use these tools consider shipping the *nix package as a bz2 archive.

Build instructions should give supported version numbers for build tools (for example, maven and ant).

TODO: Discussion on the merits of distributing dependent jars. This should be a link to the notes section

As well as libraries, projects often have more subtle dependencies. Many languages (for example Java and Perl) have different versions. It is important that the versions of a language upon which a project will run are clearly documented. The release notes are a typical location for this information. Note that Java also includes the version used to build in the MANIFEST.

Apache Maven is a tool used by many podlings. TODO: improve preamble

It is best to use the groupId and artifactId that will be used upon graduation. The version should include incubating (or incubator) to ensure that the artifacts created comply with Incubator release policy.

For example

	<groupId>org.apache.wicket</groupid>
	<artifactId>wicket-parent</artifactId>
	<version>1.3-incubating-SNAPSHOT</version>

TODO: link to infrastructure

Jars are just another form of binary package. If they are likely to be distributed (for example, through the Apache Repository) then they must adhere to the same policy as other binary packages. In particular, LICENSE and NOTICE files must be distributed.

It is convenient to include these with the META-INF directory. This can be done easily either either with Ant or Maven. TODO: move examples here from jakarta commons releases.

TODO Lots of projects get this wrong and most tools, by default, produce substandard manifests. Offer some guidance on values TODO: Add how to create a specification compliant MANIFEST http://jakarta.apache.org/commons/releases/prepare.html#checkjarmanifest

Maven 1 produces a minimal MANIFEST. This should be augmented with the recommended by adding appropriate properties to the project.properties file.

Maven 2 produces a much better manifest provided that the POM is reasonably full. It does not, by default, include some recommended manifest entries. It is recommended that POM should be customized so that it includes the missing recommended entries.

Some tools used by Apache projects:

• Java
  • Clirr works on binaries
  • JDiff uses sources

Maven can be used to generate a change log as part of the project documentation.

Indicating supported versions for dependencies is important. The minimum (and - where appropriate - maximum) Java version need to be clearly documented in the release. This information should be included in a README or the RELEASE NOTES.

Users often expect the minimum version supported to be the one listed in the MANIFEST. There are also good reasons for releases to be compiled with the minimum version of Java supported by the release. This is the easiest way to ensure that the release will work as expected on that version. This will ensure that the version in the MANIFEST is as expected.

If the version in the MANIFEST cannot reflect the minimum support version (see below) then it is recommended that the flowing additional entries are added to MANIFEST.

The usual reason for need to use a more modern Java version is to support optional classes which require features present only in the new version.

The approach which requires the least configuration is to adopt a split compilation strategy. The release manager installs two separate Java versions. The build script supports optional parameterization allowing the optional code to be compiled with a second JSDK. It is recommended that the build scrip includes clear indications that a second JSDK has been detected.

The alternative is to correctly configure a more modern JSDK to compile code which will function correctly on another JRE. This means TODO: javac settings through Ant. This is not sufficient. Unfortunately the source also need to be compiled against the appropriate version of the Java API. TODO: check where the jar has to be exactly placed.

Binary packages build with Ant can use fixcrlf.

Java includes a standard mechanism for signing jars. Apache uses digital signatures to protect releases. TODO: reconsider this section.

Though there is no rule against issuing signed jars, project should educate themselves about the potentially negative consequences of doing so. Classloaders treat signed jars differently. In particular, packages are sealed against modification. Open source encourages modification. TODO: rephrase and check

TODO: importance of accurately reporting to the user the state of an implementation TODO: importance of complying with the reporting requirements set by the standard creator

JSRs

This section applies to any package that contains re-distributable artifacts which contain version information but in particular binary packages of Java contain jar files. A compliant MANIFEST meta data file within each of these files should contain the implementation version. These are good reasons to use the release version number as the implementation version. This allows the exact version to be determined from just the jar. Unfortunately, some applications expect the format to be entirely numeric (TODO: maven?)

This does mean that release candidates for binary packages of this type must either be rereleased with the version number as the only change or accept that artifacts will not be uniquely named. Uncertainty about exact jar versions has caused nasty dependency issues in the past.

Meta data, enumerating the contents of the Jar, associated with the Java Jar format.

TODO link to sun documentation