Apache Logo
The Apache Way Contribute ASF Sponsors

Apache Software Product Release Policy

This policy defines technical and legal requirements for all Apache project software releases. It complements the Release Distribution Policy, which describes the technical details of where releases are placed/mirrored, and the Release Process which describes the steps for a PMC member to create releases.

Audience: this is is aimed at ASF release managers and PMC members. Information for end-users and for distribution mirror operators is also available. This policy is required for all Apache projects, and is maintained by the Legal Affairs Committee.


Rationale And Release Definition

What Is An Apache Software Product Release / Distribution?

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?

Why Do We Need a Foundation-Wide Policy?

In the traditional open source development methodology practiced at volunteer liability-limiting organizations like Apache, it is necessary to draw clear distinctions between public resources that represent works "in-progress" and works suitable for consumption by the public at large. The purpose of a clear line is to inform our legal strategy of providing protection for formal participants involved in producing releases, as defined in the next section. In-progress assets are viewed as controlled distributions designed for self-identifying participants in project development, who are primarily following the project's development lists. Uncontrolled distributions, aka releases, are what this policy document is designed to cover.

Were we to avoid drawing this distinction, and instead encouraged users to interact directly with source control or nightly builds, it would be very difficult for the organization to offer legal protection to Apache committers and PMC members who have only exercised their own judgement in making software modifications without the benefit of an authorized business decision approving of the distribution of those artifacts as-is to the public at large. The bulk of Apache's policies and project governance structures are to facilitate the goals of this policy, so this document is well worth a careful study.

Deviations from this policy may have an adverse effect on the legal shield's effectiveness, or the insurance premiums Apache pays to protect officers and directors, so are strongly discouraged without prior, explicit board approval. Do note however that organizationally we prefer robust, reviewable decision-making over efficient decision-making, so if you are thinking of proposing an alternative process for the board to consider, be sure your targets reflect this.

Release Management Questions

Where do releases go?

A release isn't 'released' until the contents are in the project's distribution directory, which is a subdirectory of www.apache.org/dist/. In addition to the distribution directory, project that use Maven or a related build tool sometimes place their releases on repository.apache.org beside some convenience binaries. The distribution directory is required, while the repository system is an optional convenience.

The Release Distribution Policy defines how to upload to /dist.

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 only appropriately licensed code, and must not include non-approved licenses. More information can be found in the release licensing FAQ.

What are the ASF requirements on approving (voting) 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 meets the requirements of the ASF policy on releases.

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. (For time-critical security releases, the download pages script supports bypassing this requirement.)

It is important that people are informed about the availability of new releases. Announcements must contain a link to the relevant download page for the source. 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.

Is There A Guide To Best Practice/Process Steps?

The new Release Process guide is available.

Incubator podlings have a release management guide (draft). For another approach, see the Apache Subversion release guide.

Must releases be built on hardware owned and controlled by the committer?

Strictly speaking, releases must be verified on hardware owned and controlled by the committer. That means hardware the committer has physical possession and control of and exclusively full administrative/superuser access to. That's because only such hardware is qualified to hold a PGP private key, and the release should be verified on the machine the private key lives on or on a machine as trusted as that.

Practically speaking, when a release consists of anything beyond an archive (e.g., tarball or zip file) of a source control tag, the only practical way to validate that archive is to build it locally; manually inspecting generated files (especially binary files) is not feasible. So, basically, "Yes".

Note: This answer refers to the process used to produce a release artifact from a source control tag. It does not refer to testing that artifact for technical quality.

Release Distribution and Mirroring Questions

Where can we host test packages (nightly builds and release candidates)?

Test packages are for use by consenting developers and interested community members only, so they should not be hosted or linked on pages intended for end users. They should not be mirrored; only blessed GA releases should be mirrored.

Projects should use the /dev tree of the dist repository or the staging features of repository.apache.org to host release candidates posted for developer testing/voting (prior to being, potentially, formally blessed as a GA release). See FAQ below.

Where can we host public (GA) releases?

Current releases must be served from the ASF mirroring system by placing them under http://www.apache.org/dist/. (How to upload releases to the dist/ tree is explained below.)

Project download pages must link to the mirrors and not to the main Apache Web site; see instructions for creating download pages for fuller details. The website documentation for the software must contain a link to the download page for the source.

Project websites (http://{project}.apache.org), VMs (http://{project}.zones.apache.org and http://{project}-vm.apache.org), and source control repositories (svn.apache.org and Git repositories) may not be used to distribute releases --- that is, releases should not be downloaded from them.

How are releases archived?

All releases must be archived on http://archive.apache.org/dist/.

An automated process adds releases to the archive about a day after they first appear on to http://www.apache.org/dist/. Once a release is placed under http://www.apache.org/dist/ it will automatically be copied over to http://archive.apache.org/dist/ and held there permanently, even after it is deleted from http://www.apache.org/dist/.

If you have (legacy?) releases that never got archived, ask infra to copy them to http://archive.apache.org/dist/.

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.

This is done by deleting the artifacts from https://dist.apache.org/repos/dist/release/<TLP name>/.

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 removed when 1.2.x is released. Note that all releases are automatically archived, see How Is An Old Release Moved To The Archives

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.

How do I upload a release ?

By committing your release tarballs to the appropriate subdirectory (i.e. TLP name) of the https://dist.apache.org/repos/dist/release/ 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).

The repository directory https://dist.apache.org/repos/dist/release/<TLP name>/ is for official releases only, i.e. archives (+ sigs, hashes) that have been approved by the PMC. For this reason, by default only PMC members can update the dist/release directory tree.

If the Release Manager is not a member of the PMC, they will need to ask a PMC member to do the actual release publication.

The PMC can also vote to let non-PMC-members update the dist/release area. To get this set up, please open a JIRA ticket at the INFRA JIRA referencing the PMC vote.

Where can I stage a release candidate?

There is also a development area under https://dist.apache.org/repos/dist/dev/<TLP name>/ which can be used for development releases. For example snapshots and release candidates can be stored here. One important item to note, is that this directory does not get published to the mirrors via svnpubsub. It is intended to act as a staging location in preparation for the release to become official.

All committers on a project can write to the dist/dev area for the project.

If used for release candidates, then following a successful vote, the appropriate files can be moved from the dev/ tree to the release/ tree in order to publish them.

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

Do I need to talk to Infrastructure before distributing a release?

Most projects can just distribute a release as described in the previous two questions. However, releases that are likely to strain the mirroring and download resources must be coordinated with infrastructure.

Releases of more than 1GB of artifacts require a heads-up to Infrastructure in advance.

Specific exemptions from other dist policies (such as what may or must or must not be distributed via the mirrors) also need to be coordinated with Infrastructure.

Which Directory For What Build?

Type Location
Nightly Builds .apache.org/builds
Current Releases www.apache.org/dist
Older Releases archive.apache.org/dist

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.

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 and Apache Legal pages for current information.

Which Files Must Contain An ASF License Text?

Every source file must contain the appropriate ASF License text or boilerplate notice.

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

In short, only one copy of the full 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 Apache 2.0 license allows for a NOTICE file that contains such attribution notices (including the Apache attribution notice). Details are available.

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?

See the Legal FAQ about NOTICE.

Only the mandatory information required by the product's software licenses may be placed into NOTICE; you must not put normal documentation there.

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 at
The Apache Software Foundation (http://www.apache.org/).

N.B. Unfortunately versions of this document prior to 2013-01-30 (r1440650) were incorrect, as they used the phrase: "developed by" instead of "developed at". The official wording was established in section 6C of the board minutes for May 24 2006

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

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 should be appended to the LICENSE file. The component license itself may also be appended, or it may be stored elsewhere in the artifact with a pointer to it from the LICENSE file, e.g. if the license is long.

See an example showing appended licences.

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.