This document aims to describe the Apache release publishing policy,
to answer questions related to this policy and give a basic primer on the subject.
Links should be provided to authoritative sources of deeper information.
The target audience are release managers.
Help Wanted!
Help to finish this document by contributing documentation patches!
If the information you seek isn't in this document,
then please submit a patch once the instructure folks have answered your question.
Tasks: Create the content for this document!
Note this is not normative
See also this.
Apache must be the primary source for all artifacts officially released by the ASF.
Do I Need Special Karma To Publish A Release?
No. New releases should be uploaded to people.apache.org.
All committers have karma for this machine. Releases are sync'd to
www.apache.org automatically. Note
that there may be some delay.
I've Just Published A Release: Why Isn't It Available From XYZ?
Apache uses mirroring both internally and externally. This process runs to a schedule. It may take
up to 24 hours for a newly published release to be sync'd to all mirrors.
Note: file deletions from www.apache.org are processed once per day,
whereas updated or new files are synchronised more frequently (every two hours at present)
Note: people.apache.org is mirrored to www.apache.org.
It may therefore take some hours before changes are sync'd.
What File Permissions Should Be Set On The Release?
The release should be group readable and writable. The group should be set to the appropriate group
for your project. The release should be world readable. In short: -rw-rw-r--.
How Can I An Archive Old Release?
All releases are sync'd automatically to the archives.
To archive a release, just remove the file from the main servers.
What's The Right Way To Make ASF Jars Available
Through the Maven Repository On Ibiblio?
The Ibiblio Maven repository is a mirror of the
ASF Repository. Artifacts should be
uploaded to that repository and then mirrored automatically
to the Ibiblio repository.
What Is The ASF Repository?
The ASF repository is the official distribution channel for raw artifacts (typically jars).
The repository is structured and contains meta-data describing the releases in forms that
can be read easily by both machines and humans.
The ASF repository is managed by the infrastructure repository special interest group.
Informal guidance can be found on the wiki.
Questions about the repository should be asked on repository@apache.org
list (the list is committers only so please subscribe using your apache.org address).
How Should A Artifact Be Published To The ASF Repository?
Some ways to so this:
- A step-by-step guide tp uploading by hand
- A guide to automation using Maven 1 TBD
- A guide to automation using Maven 2 TBD
Also read Guide To The ASF Repository
If you're not using Maven to publish the artifacts of your project, but want to do that manually
or via Ant, then you should follow these steps:
-
Duplicate the Maven repository directory structure.
Maven uses a special directory structure for placing the artifacts. For manual publishing it is
usually easiest when you re-create this structure in a local build directory and then simply upload
this build directory.
Basically you have four relevant directories:
distributions- This contains complete distributions. Most Apache projects don't use this directory, except some
of the larger ones, like Geronimo.
jars- This directory will contain the library/framework files.
licenses- The directory for the licenses. For Apache projects this will be the
Apache 2 license.
poms- The Maven descriptors. Since you're not using Maven if you read this, you possibly do not have
these descriptors. If this is the case, then see below for how
to create one.
In you build setup you would then create this structure and copy the relevant files into these
directories.
-
Create MD5 checksums for all artifacts to be published.
Most projects distribute three types of artifacts: library files (jars), the license, and the library
descriptors for Maven. For each of these files (not only the library files) you need to create a MD5
checksum. On the shell this can be done e.g. by
$ openssl md5 < xxx-m.n.jar > xxx-m.n.jar.md5
If you're using Ant, then you can integrate this into the build
process using a target like this:
<target name="md5-checksums">
<checksum forceOverwrite="yes"
fileext="md5">
<fileset dir="${dist}"
excludes="**/*.md5"/>
</checksum>
</target>
This basically creates a checksum for every file in the directory denoted by the ${dist}
variable.
-
Create SHA checksums for all artifacts to be published.
Similar to the MD5 checksums, you should also create SHA checksums for the files. This can be done in
quite the same way:
$ openssl sha < xxx-m.n.jar > xxx-m.n.jar.sha1
Again you can also use Ant to do the work:
<target name="sha-checksums">
<checksum forceOverwrite="yes"
algorithm="SHA"
fileext="sha1">
<fileset dir="${dist}"
excludes="**/*.sha1"/>
</checksum>
</target>
-
Sign the relevant artifacts.
The created library files (jars) also need to be signed with the project's or your PGP key. The
signing process is the same as for the normal release publishing process, except that you're not sign
the complete distribution but rather individual library files. Information about signing can be found
here.
Note that you only need to sign the files in the distributions and jars
directories. But within these two directories, you need to sign every file that is not a MD5 or SHA
checksum file.
-
Upload.
Since we already have the correct directory structure, this is easily done by issuing a command like:
$ scp -r . [username]@people.apache.org:/www/people.apache.org/repo/m1-ibiblio-rsync-repository/[projectname]/
in the directory containing the Maven directories.
Ant since version 1.6 has a corresponding task:
<target name="publish">
<scp todir="${username}:${password}@people.apache.org:/www/people.apache.org/repo/m1-ibiblio-rsync-repository/[projectname]/">
<fileset dir="${dist}"/>
</scp>
</target>
The username and password are not hardcoded, but rather you supply them when invoking Ant:
$ ant -Dusername=[username] -Dpassword=[password] publish
-
Ensure group ownership and access rights.
The last thing to do is to make sure that the files are owned by the unix group apcvs and that they
are writable by this group. When using scp or the corresponding Ant task, this is usually not a
problem as the files automatically get the correct umask permissions.
But in case you want to do this manually, simply login per ssh into people.apache.org and then do:
$ cd /www/people.apache.org/repo/m1-ibiblio-rsync-repository/[projectname]/
$ chgrp -R apcvs *
$ chmod -R g+w *
If you're not using Maven but rather publish your project's release manually, then it is possible that you don't
have a project descriptor. Since this file is required, this section gives a short guide to creating such a file
for your project. For more detailed information, especially if you consider using Maven to build (and publish) your
project you should check the Maven
documentation.