These best practices help guide a PMC through the steps to create and publish an Apache software product release. It complements the formal Apache Release Policy, defining what must be in a software release, and Release Distribution Policy, which describes the technical details of where releases are placed/mirrored.
Every Apache Software Foundation project software release must meet requirements for content , process , and publication. These requirements ensure that Apache contributors and users benefit from appropriate legal protection the ASF provides, and reflect the Foundation's goals of open, collaborative software development.
This process is meant for Apache committers or PMC members who want to learn how to create and publish a release from an Apache project. This provides an overview of the process steps, the requirements, and some commonly-used tools, and it will provide you with links to other pages with more details.
An Apache release is a set of valid , signed , artifacts, voted on by the appropriate PMC and distributed on the ASF's official release infrastructure. All of the highlighted words in the previous sentence are critical, and are defined in the following sections.
In a nutshell, to make a release, an Apache project:
The common practice at Apache is for a single individual to take responsibility for the mechanics of a release. That individual is called the 'release manager.' Release managers take care of shepherding a release from an initial community consensus to make it to final distribution.
Release managers do the work of pushing out releases. However, release managers are not ultimately responsible. The PMC in general, and the PMC chair in particular (as an officer of the Foundation) is responsible for compliance with requirements.
Any committer may serve as the manager of a release.
A release starts when the project community agrees to make a release. However, no release manager can make a valid release unless the community has taken the necessary steps to prepare in advance. The source code and build process must comply with the legal and intellectual property requirements for a valid release, and the project must have the infrastructure in place to correctly sign the release artifacts.
The Apache Software Foundation exists to create open source software. Thus, the fundamental requirement for a release is that it consist of the necessary source code to build the project. Optionally, a release may also be accompanied by compiled binaries for the convenience of users.
All the source code of the project must be covered by the Apache License, version 2.0. The license or appropriate boilerplate text must be included in each source file. For the license to be valid, the code must have been contributed by an individual covered by an appropriate contributor license agreement, or have otherwise been licensed to the Foundation and passed through IP clearance. See this page for details on licensing and this FAQ for details on release requirements. When in doubt, contact the Foundation's Legal resources by filing a JIRA under the 'LEGAL' project. The Apache RAT tool can assist in checking for compliance.
Many projects have dependencies on non-Apache components. For an Apache release to be valid, it may only depend on non-Apache components that have compatible licenses. For more information on third party licenses allowed, see ASF Legal Previously Asked Questions.
The files that make up an Apache release are always accompanied by cryptographic signatures. This allows users to ensure that the files have not been tampered with since they were created. The mechanics of signing depend on the project's build technology. The Apache infrastructure group strongly recommends that projects set up automated infrastructure to sign the files to simplify the work. Generally, projects set up their build system so that the same process that creates the files for a release also signs them.
The process of setting up to sign the code is somewhat complicated, and it is described on the release signing page. If you plan to serve as a release manager, you should generate a key and publish it well in advance of creating a release.
A binding release vote of the PMC is the critical gating step in the release process. Without such a vote, the release is just a set of files prepared by an individual. After such a vote, it is a formal offering of the ASF, backed by the 'full faith and credit' of the Foundation.
The Apache infrastructure must be the primary source for all artifacts officially released by the ASF.
The Apache Infrastructure team maintains the Apache release distribution
infrastructure. This infrastructure has two parts: the mirrored directories
www.apache.org and the Maven repository on
See the Release Distribution Policy for specific technical requirements.
Each Apache TLP has a
release/TLP-name directory in the distribution
Subversion repository at https://dist.apache.org/repos/dist/.
Once a release vote passes, the release manager should
svn add the artifacts
(plus signature and hash files) into this location. Each project is responsible for
the structure of its directory. The contents of these directories are pushed to
svnpubsub. Note that only the most
recent version of each supported release line should be stored here; see
when to archive.
The contents of the
dist/release/ directories are published to the 3rd party mirrors using rsync.
The SVN directories under
https://dist.apache.org/repos/dist/ are not to be used to link to releases on download
pages or elsewhere.
Download pages must use the ASF mirror system, for details please see
A signature (
.asc) can become invalid because the signing key is revoked
All current signatures (those in
must be valid.
It is vital that hash, signature and KEYS files are only downloaded from ASF hosts. So the following files are excluded from synchronisation:
*.md5 *.MD5 *.sha1 *.sha *.sha256 *.sha512 *.asc *.sig KEYS KEYS.txt MD5SUM SHA*SUM
The download page should use HTTPS: rather than plain HTTP: for linking to KEYS, sigs and hashes.
In addition to the checksum files required in the Release Distribution Policy, an MD5SUM or SHA*SUM may be provided. MD5SUM and SHA*SUM must look like the output of md5sum(1): lines containing a checksum, followed by a filename ; use only plain filenames (no slashes).
Do not use any other file names for such files.
If the directory does not yet exist, please raise a JIRA for INFRA with the required info as per Providing needed information
See the Publishing Maven Releases guide.
Apache uses svnpubsub internally and rsync mirrroring externally.
Files committed to the
Subversion repository at https://dist.apache.org/repos/dist/ are automatically
copied, using svnpubsub, to
www.apache.org , and then the external mirrors pick up the files from
www.apache.org. It may take up to 24 hours or more for a newly published
release to be sync'd to all mirrors. Mirrors have their own schedules. Mirrors
are required to check at least once
a day, but most will check for updates 2 to 4 times per day.