This document aims to answer general questions about Apache software releases. Some of this content is aimed at ASF release managers, some at users of Apache software and the rest may be of interest to both.

Contents

Release Questions

What Is A Release?

Releases are, by definition, anything that is published beyond the group that owns it. In our case, that means any publication outside the group of people on the product dev list. If the general public is being instructed to download a package, then that package has been released. Each PMC must obey the ASF requirements on approving any release. How you label the package is a secondary issue, described below.

During the process of developing software and preparing a release, various packages are made available to the developer community for testing purposes. Do not include any links on the project website that might encourage non-developers to download and use nightly builds, snapshots, release candidates, or any other similar package. The only people who are supposed to know about such packages are the people following the dev list (or searching its archives) and thus aware of the conditions placed on the package. If you find that the general public are downloading such test packages, then remove them.

Under no circumstances are unapproved builds a substitute for releases. If this policy seems inconvenient, then release more often. Proper release management is a key aspect of Apache software development.

The Apache Software Foundation produces open source software. All releases are in the form of the source materials needed to make changes to the software being released. In some cases, binary/bytecode packages are also produced as a convenience to users that might not have the appropriate tools to build a compiled version of the source. In all such cases, the binary/bytecode package must have the same version number as the source release and may only add binary/bytecode files that are the result of compiling that version of the source code release.

How Do The Types Of Apache Software Distribution Differ?

• Test Packages are not Apache releases. All releases require due process and official approval. Test packages are for testing ongoing development and should only be discussed on the project development lists.

  • Nightly Builds are simply built from the Subversion trunk, usually once a day. These packages are intended for regular testing of the build process and to give automated testers a common build for regression testing. They are not intended for use by the general public.

  • Release Candidates are packages that have been proposed for approval as a release but have not yet been approved by the project. These packages are intended for developers (and users who follow the development discussions) to test and report back to the project regarding their opinions on the package quality compared to prior releases. Many release candidates are possible prior to a release approval. Users that are not interested in development testing should wait until a release is formally approved.

• Releases are packages that have been approved for general public release, with varying degrees of caveat regarding their perceived quality or potential for change. Releases that are intended for everyday usage by non-developers are usually referred to as "stable" or "general availability (GA)" releases. Releases that are believed to be usable by testers and developers outside the project, but perhaps not yet stable in terms of features or functionality, are usually referred to as "beta" or "unstable". Releases that only represent a project milestone and are intended only for bleeding-edge developers working outside the project are called "alpha".

Where Can I Find ASF Releases?

All current Apache releases are distributed from the main www.apache.org site's "dist" subdirectory, where they are picked up by mirrors worldwide for disribution to the general public. These releases are automatically copied to the archives and remain present on archive.apache.org even after they have been removed from the current dist directories. So, if you are looking for an old Apache release that is no longer on the mirrors, or need to refer to a permanent location (such as for legal notices), then use a link to the archives.

Release Management Questions

What Must Every ASF Release Contain?

Every ASF release must contain a source package, which must be sufficient for a user to build and test the release provided they have access to the appropriate platform and tools. The source package must be cryptographically signed by the Release Manager with a detached signature; and that package together with its signature must be tested prior to voting +1 for release. Folks who vote +1 for release may offer their own cryptographic signature to be concatenated with the detached signature file (at the Release Manager's discretion) prior to release.

Note that the PMC is responsible for all artifacts in their distribution directory, which is a subdirectory of www.apache.org/dist/ ; and all artifacts placed in their directory must be signed by a committer, preferably by a PMC member. It is also necessary for the PMC to ensure that the source package is sufficient to build any binary artifacts associated with the release.

Every ASF release must comply with ASF licensing policy. This requirement is of utmost importance and an audit should be performed before any full release is created. In particular, every artifact distributed must contain appropriate LICENSE and NOTICE files. More information can be found in the foundation website and in the release licensing FAQ.

What are the ASF requirements on approving a release?

Votes on whether a package is ready to be released use majority approval -- i.e. at least three PMC members must vote affirmatively for release, and there must be more positive than negative votes. Releases may not be vetoed. Before voting +1 PMC members are required to download the signed source code package, compile it as provided, and test the resulting executable on their own platform, along with also verifying that the package contains the required contents.

What Are The Key Points Of ASF Mirroring Policy?

Apache Committers,

If you are responsible for posting software for public download, please be sure to read and follow the policy listed at:

Apache Mirroring Information

Some key points in this policy:

1. Software should not be distributed from project websites. Current releases should be mirrored by placing them under www.apache.org/dist/.

2. Older releases should go under archive.apache.org/dist/. Once a release is placed under www.apache.org/dist/ it will automatically be copied over to archive.apache.org and held there permanently, even after it is deleted from www.apache.org. If you currently have older releases on your project website, you can manually copy them to archive.apache.org/dist/.

3. Do not point downloaders directly at the www.apache.org/dist/ directories. Point to the mirrors using one of the techniques discussed on the above web page.

If you need assistance in implementing URL redirection to direct downloaders to the new locations, or if you need any other help in implementing this policy, please contact the infrastructure@apache.org mailing list.

By following this policy, we will make the most efficient use of our resources and provide better service to our users.

How do I upload a release (current way)?

By using SSH to upload it to your project's download directory, for example:

laptop% scp ${tlp}-${product}-4.2.0.tar.gz{,.asc} ${availid}@people.apache.org:/www/www.apache.org/dist/$tlp/$product/

Please also ensure that the newly-uploaded files are writable by the $tlp unix group; use

availid@minotaur:~$ chmod -R g+w /www/www.apache.org/dist/$tlp/$product/

or set umask 002 in your login scripts otherwise.

Once uploaded, the files will be copied to the master mirror site within about an hour, after which the 24-hour waiting period for mirrors starts. After 24 hours, most mirrors should have picked up the new files, so you can update the download page and remove any old releases from dist/TLP.

The Windows equivalents to scp(1) are WinSCP and PuTTY's siblings pscp/psftp.

How do I upload a release (newer way)?

By committing your release tarballs to the appropriate subdirectory of the https://dist.apache.org/repos/dist/ repository. svnpubsub will push the files to the master mirror site immediately. The 24-hour wait for mirrors is still required though (as mirrors use an 1/N-daily rsync to catch up with the dist/ tree).

Commit mails to the dist/ repository go to your normal project mailing lists.

Note: Infra will require projects to transition to this method of managing their dist/ dir. To transition just open a Jira ticket and specify: (1) what mailing list commit mails should go to.

How Should Releases Be Announced?

Please ensure that you wait at least 24 hours after uploading a new release before updating the project download page and sending the announcement email(s). This is so that mirrors have sufficient time to catch up.

It is important that people are informed about the availability of new releases. At the very least, emails should be sent out announcing this to all appropriate mailing lists. Many top level projects have announcement lists for this purpose. There is also an ASF-wide announcement list which is suitable.

Please note that you can not post the ASF-wide announcement list without the usage of "apache.org" mail address. Also, please make sure that you have put 3-5 lines blurb for the project. (because most of the subscribers to announce.AT.apache.DOT.org list would not know what is XX-Project, generally speaking)

It is recommended that an SHA-1 OpenPGP compatible signature is added to the announcement mail. Please ensure that your public key has been already uploaded to famous pgp sites (e.g. http://pgp.mit.edu/). This key should either be the one used to sign the release or one that is cross-signed by that key.

Which Directory For What Build?

How Is An Old Release Moved To The Archives?

/www.apache.org/dist is automatically archived. Therefore, a copy of an official release will already exist in the archives. To move a release to the archives, just delete the copy in /www.apache.org/dist. Remember to update any links from the download page.

When Should An Old Release Be Archived?

/www.apache.org/dist should contain the latest release in each branch that is currently under development. When development ceases on a version branch, releases of that branch should be removed from /dist.

For example, if Apache Foo 1.2.x is a newer release in the same line as Foo 1.1.a, then 1.1.a should be moved to the archive when 1.2.x is released.

If Apache Foo 1.2 is a new branch, and development continues on 1.1 in parallel, then it is acceptable to serve both 1.1.a and 1.2.x from /dist.

Is There A Guide To Best Practice?

See the Incubator release management guide.

How do I release Maven Artifacts?

See the Publishing Maven Releases guide.

Release Licensing Questions

Please read Applying the Apache License, Version 2.0 and check the Apache Licenses page for current information.

Which Files Must Contain An ASF License Text?

Every source file must contain the appropriate ASF License text.

Is A Full Copy Of The License Required In Each Source File?

In short, only one copy of the license is needed per distribution. This full license file should be placed at the root of the distribution in a file named LICENSE. For software developed at the ASF, each source file need only contain the boilerplate notice.

Where Is The Right Place For Attribution Notices?

The new license allows for a NOTICE file that contains such attribution notices (including the Apache attribution notice). Read this.

Any attribution notices contained within existing source files should be moved into the file. The NOTICE file must included within the distributed next to the LICENSE file.

Ensure that the standard ASF attribution notice is contained in any new NOTICE file created.

What Content Is Appropriate For The NOTICE File?

Read this.

Only mandatory information required by the product's software licenses. Not suitable for normal documentation.

Is A NOTICE File Required For Pure ASF Code?

Yes! The NOTICE file must contain the standard ASF attribution, given below:

This product includes software developed by
The Apache Software Foundation (http://www.apache.org/).

If An Artifact Contains Code Under Several Licenses, Should It Contain Several License Files?

No - all license information should be contained in the LICENSE file.

When an artifact contains code under several licenses, the LICENSE file should contain details of all these licenses. For each component which is not Apache licensed, details of the component and the license under which the component is distributed should be appended to the LICENSE file.

Here is an example.

What Are The Requirements To Distribute Other Artifacts In Addition To The Source Package?

ASF releases typically contain additional material together with the source package. This material may include documentation concerning the release but must contain LICENSE and NOTICE files. As mentioned above, these artifacts must be signed by a committer with a detached signature if they are to be placed in the project's distribution directory.

Again, these artifacts may be distributed only if they contain LICENSE and NOTICE files. For example, the Java artifact format is based on a compressed directory structure and those projects wishing to distribute jars must place LICENSE and NOTICE files in the META-INF directory within the jar.

Nothing in this section is meant to supersede the requirements defined here and here that all releases be primarily based on a signed source package.

Questions About Release Statistics

Is There Any Way To Measure How Many Times XYZ Has Been Downloaded?

Not directly. Files are downloaded from the mirrors. Apache does not require mirrors to collect statistics about downloads.

Counting the hits on the download script should give a reasonable estimate. Various similar statistics are collected by Vadim Gritsenko.