Every incubator release is also an Apache release. So Apache policy must be followed.
Incubator policy is additional and builds on these rules.
Release managers for podlings
need to read the release
and legal
documentation on the main Apache site.
A few important topics are discussed below. These are a supplement and not a substitute
for the Apache documentation.
The release manager need to create a
signature
for every artifact released. It only takes a little time to create a key and the process
is reasonably straight forward.
However, it is recommended that enough time is taken to gain a basic understanding of the
public key cryptography.
Read the Apache Signing Guide
and at least some of the background material linked from it.
See:
Apache releases should contain the full name of the project responsible for the release. This ensures that
trademark law can be used against others issuing artifacts with the same name.
For example, one good name for product bar Apache Foo Project would be apache-foo-bar.
Once a podling graduations, it should adopt this naming convention.
Whilst in the incubator, practice is a little different.
The release name should contain the podling name and may contain apache.
Incubator policy insists that it must also contain incubating (though small variations
for the sake of readability are usually acceptable).
For example, for podling foo, both apache-foo-incubating and
foo-incubating would be acceptable names.
See also:
Incubator policy requires that
all incoming code is fully signed off before any release. This simply reinforces the Apache
requirements: all code must have appropriate licenses.
Potential liability for released code is greater than for unreleased code.
So, it is of particular importance that this is true of all released code.
The process of preparing a release should include an audit of the code to ensure
that all files have appropriate headers and that all dependencies complies with
Apache policy.
The release build also needs to be check
to ensure that the LICENSE and NOTICE files are included in every released artifact.
See:
Preparation is the key to quality. The release manager
will need to organise and coordinate this but need not execute all.
The list of open issues needs to be analyzed. The community needs to decide which
issues could be resolved for this release and how much energy the community
has to deal with these. Time may also become a factor: some issues which
cannot be resolved promptly may need to be postponed.
Issue tracking system can be used to help this process especially for complex projects
with many open issues. Each open issues should be analyzed and marked appropriately.
An accurate view of those bugs which are targeted for the upcoming release helps
to concentrate community effort. Consider asking reporters to donate unit tests.
Any documentation that the release contains should be proof-read and spell checked.
This is obviously something that needs to happen after the content is finalized.
So typically, the release manager needs to coordinate the documentation effort.
A release is a good time to concentrate energy on documentation.
TODO: should include apache in the title (gives trademark protection against different jars
with the same name)
TODO: glossary - distribution type: based on the same tagged source built
TODO: Common Types of distribution
The source package is canonical. Every release must revolve around a source package.
Compiled languages may also wish to create binary packages. These may be platform specific.
Some projects may issue builds (ie binary packages) which package the project for
particular containers.
All types of packages ship as compressed artifacts.
This means multiple packages may be shipped as various compressed artifacts (eg tar.gz and .zip).
TODO: glossary - downstream packager: takes an apache release and packages it for a particular platform.
TODO: best practice is to work with downstream packagers and link to their packages
rather than roll their own packages. Need to add notes that these are not official releases.
TODO: link to notes on working with downstream packagers
TODO: write up gentoo wiki on good upstream. google for other distros.
TODO: describe what a source package is; version control for source packages;
add content to release documents; export not checkout
Many would argue that for open source projects, the source package is the release:
binaries are just for convenience. There are some pragmatic (as well as philosophical)
reasons why a source package should be issued:
- Downstream packages usually prefer to work from an Apache source package.
Typically, they will patch the source both to apply fixes and to add elements
of their own build system. Being a good upstream encourages wider
distribution and use of the project.
-
Source packages encourage developers to modify the code base. Recruiting
new developers is vital for the long term health of an Apache project.
It is required that source packages are included in every release.
Many packagers (for example, FreeBSD and linux distributions) prefer or demand
to work from source releases. Archivists prefer source. Many large organizations
prefer to verify and then build their own versions from source. A source package
is easy to create but helps to reach these audiences.
A binary package is any package that is not an exported snapshot of the source.
Binary packages may include some source code. For some projects, this makes sense.
For others, it does not.
Users expect release documentation
to be present in the root directory of the package. If copies of these documents are required
elsewhere, it is recommended that the release process creates copies. These documents
should be present in all types of packages
including source packages.
So the master documents should be checked into the base subversion directory.
TODO: rewrite to be topic centric.
* project status. DISCLAIMER or STATUS
Incubating projects should ensure that either contain the STATUS document describing. TODO: check this
Collecting all this information may seem a little daunting especially for a starting project.
Not at all agile. One approach may be to ask developers to update documentation
as they make changes.
Another is to use a to (for example maven) to collect this information automatically.
A third is for the release manager to collect all the information required
when the release is made. The disadvantage of this method is that increases
the work required to create a release.
Typically, as a project matures, the user base rises and the rate of core development
(as opposed to work on modules) slows. The need to inform users of the changes made
increases as does the need for quantity release documentation. One approach
suitable for new projects is to aim to increase the quality of information supplied
with each release as adoption grows.
RELEASE_NOTES (TODO:link). Remember to include a description of the project.
CHANGES (link) these may be contained in a separate document
(TODO: maven) or included in the RELEASE NOTES. svn log can be used to collect changes.
This is a good opportunity to reinforce the need for good commit messages.
CHANGES should also include references to bugs fixed (TODO URLS, searches in JIRA or bugzilla).
Include a description of the build process either in a README or BUILDING document.
This should include details of the dependencies (both library and to) required to build and run
the product but may do so by reference
CHANGES should note any incompatibilities introduced since the last release.
Remember that the RELEASE_NOTES will be used as a basis for downstream packagers
(TODO add links to this in packagers section)
as well as users. Create a short paragraph explain what the product is. The proposal
short already include something suitable. Include this description in the RELEASE_NOTES
and in ANNOUNCEMENTSs (TODO add links to this in announcements section)
TODO: check this TODO: the STATUS document should be checked to ensure that it is up to date
before release. Incubator releases should do a legal audit
before releasing. The legal STATUS of the code base should be clean before it is released.
Apache projects may distribute artifacts and documents as part of a release
which are not Apache Licensed. All such artifacts must comply with Apache's
3rd party licensing policy.
All the licenses on all the files to be included within a package
should be included in the LICENSE document. This LICENSE
(courtesy of Apache HTTPD) is a
good example. The Apache License is at the top of the LICENSE document.
After that, the license for each non-Apache licensed component is included,
along with a clear explanation of which files that license applies to.
The NOTICE document is for additional copyright and attribution statements those
licenses may require. A typical NOTICE document at a minimum includes a copyright
and attribution statement for The Apache Software Foundation. Nothing else
belongs in the NOTICE document. See
this document for the typical example.
It is of particular importance that released code is clean.
It is good practice to check the provenance of any source documents
which do not have license headers. Check that dependencies (and in particular
those dependencies that ship in the packages) comply with Apache policy.
Legal policy and interpretation changes from time to time so it is worth investing
a little time reading again the legal release material.
Packages of all
types should be shipped in a compress format
to minimize bandwidth requirements.
Though utilities for all major compression formats are available for all major platforms,
not all platforms support all major compression formats by default.
Users find it convenient to download the package compressed in a familiar
format that is easy to decompress on their platform.
It is therefore recommended that each type of package is shipped in a variety of
compressed formats. Ship at least one of tar.gz, bz or bz2 for UNIX and linux (but note
this).
Ship zip for windows.
Some formats are strongly associated with particular platforms.
Even when the uncompressed contents have no functional differences,
this leads to conventional associations between particular compressed artifacts and
platforms.
For example, zip with windows and tar.gz
with UNIX and linux.
Users often expect this association.
See notes on line endings for source packages.
Different package types should unpack to
directories with different names. This is more convenient for users since:
- users who download more than one type do not need to
take action to ensure that unpacked packages do not overwrite each other
- it allows easy identification of different package types
For project, Apache Foo (say) with source and binary types, it is conventional for the main binary
to unpack to apache-foo and the source to apache-foo-src.
Other binary types should unpack to suitably suffixed directories (for example,
apache-foo-sdk).
Compressed archives should unpack into a contained directory (rather than straight
into the current directory). The directory into which the package unpacks should flow
the standard naming convention. apache-foo.tar.gz should unpack to the apache-foo
directory.
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.
This section applies only to compiled languages.
Source packages should contain easy instructions describing how to build the project.
The source package should build from instructions contained.
TODO: best practices for instructing users about building the project.
Build instructions should give supported version numbers for build tools (for example, maven and ant).
TODO: information about dependencies is a FAQ. releases should indicate dependencies
and which are optional and which required. if they are not shipped with the package,
information should be included about their official home. minimum (and max) supported versions.
dependencies should comply with the current apache policy. TODO: link
TODO: dependencies also include the tools required to build and test the source.
to dependencies are often included in BUILDING or README
TODO: particularly important for languages. language should be approached
as dependencies and documented. these should be listed in the README
or RELEASE NOTEs.
Any changes in dependencies (including dependencies added or removed
or changes in supported version) should be noted in the change log for this
release. (Where appropriate) check the that the application is built against
the correct versions. Note that this includes platform as well as library
dependencies.
TODO: ASF policy compliance
TODO: project policy - explicit policy should be written down
TODO: Discussion on the merits of distributing dependent jars. This should be a link to the notes section
Read this.
The NOTICE is important and serves several purposes.
The contents should be included in all downstream redistributions.
The NOTICE documents copyright notices and other required attributions.
This must include:
Every contributor retains the copyright to their contributions and grants Apache only a (generous)
license for the work. A release is an act of selection by the PMC. Apache holds the copyright
to the collective work that is the release. The Apache copyright in the NOTICE
pertains to the collective.
It is strongly recommended that the NOTICE contains only these legally
important contents. The incubator disclaimer is best placed in
another document.
The exact name may be optionally suffixed. For example, both NOTICE
and NOTICE.txt are fine.
TODO: svn is flexible. branches and tags with svn are not the same as with cvs.
All releases should be identified with a tag. It is occasionally necessary to rebuild
releases many years later, and having a tag easily allows this to be done.
Tagging is cheap and easy when using subversion.
So, every release should be tagged. Releases should be built from a tag,
or built from a stable branch (not trunk). If not built from a tag, the
approved release candidate should be tagged.
It is useful to adopt a consistent naming convention for tagging releases.
This allows release tags to be recognized easily. Typically the tag will be a
variation on the name of the release. For example, some projects use
ALL CAPS to indicate release tags in which can apache-foo-1.2 would be tagged
APACHE_FOO_1_2.
If svn:externals is used, check carefully that a tag is referenced.
This ensure that all the source for the release is fixed. If the target of a svn:externals
changes then the release will no longer be complete reproducible.
It is important that any release can be reproduced from the source at any time in the future.
Apache releases have long active lives and are permanently archived.
It may be necessary (for example, for legal reasons)
to provide a new release that is a slight alteration of a previous release.
Release managers owe it to those who come afterwards to use build processes
that are reproducible.
The build script should fully capture all the processes necessary to create the release.
Manual processing (other than creating compressed archives) is a sign that the build
is not mature enough for a full Apache release.
The requirements of the build should be fully documented. The versions of tools
and platforms used to build the release should be noted.
Releases are a primary form of communication with open source users and potential developers.
Its useful to think about releases in this way. TODO: what a release says about a projects
TODO: link into media relations and announcements (grassroots and mainstream, articles
on new features, freshmeat, downstream packagers)
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.
It is important to review all library dependencies as part of the release process
for compliance. Apache policy changes from time-to-time. A list should be
compiled of the project's dependencies, including those shipped as binary libraries
and those shipped as source together with the licenses for
those dependencies. These lists should be checked against the latest policy documents.
This list should also be used to check for compliance with US export regulations.
If any dependencies are cryptographic libraries then it may be necessary
to fill in some paperwork.
TODO: release managers should ensure that releases are announced.
TODO: links to release management FAQs
TODO: consider grassroots sites eg freshmeat.net
TODO: link note on press release
Announcements should be signed by the release manager with the key used to sign the
release. Note that this may mean creating a plain text signature on the machine used
to sign the release and then transferring this.
Announcements should be posted from the release manager's
apache.org address.
All releases by podlings must be approved by the TODO: link Incubator PMC. The conventional process
is for the podling to follow the usual Apache process (including TODO: link release vote)
and then call for a Incubator PMC VOTE on the TODO: link general incubator list.
The release manager should post the call for the VOTE.
- Links to the release artifacts
- Links to the PPMC release vote thread
- Link to the tag from which the release is cut
Release managers should subscribe to a number of Apache-wide mailing lists.
Decisions are taken on these mailing lists and issues resolved.
Documentation is updated later (if at all). It's important that release
managers ensure that they keep up to date.
- TODO: link General infrastructure list
- TODO: link Legal discuss list
Release managers for incubating podlings should also subscribe to the TODO: link general list.
A release candidate is a set of artifacts upon which a vote is held for a release.
The actual nature of the release candidate depends on the release system
adopted by a the project.
Those projects adopting a system of blessing a candidate will start by creating a
candidate which will then be promoted by a series of votes until it either fails
or reaches full release status. In this case, the same candidate may
be known as a release candidate, an alpha, a beta and then a full release.
Other projects may release alphas and/or betas or developer releases until the
project has agreed there is sufficient quality in place to make the code available
as a General Availibility (GA) release.
Those projects which have release candidates will vote on a sample release candidate.
Only formally-approved releases may be distributed from the main directories.
There are a number of reasons for this:
- the URL indicates the status of the release
- the main directory is archived for historical purposes. To conserve space
only official release should be archived.
- syncing too many short lived artifacts use bandwidth
TODO: links to infra dev
It is traditional that release managers use their Apache home space to make available
release candidates. TODO:link to dev instructions on using Apache web space.
Please remember to delete release candidates after voting concludes.
TODO: links to release signing documentation
Ensure that the code signing public key is uploaded to a network in good time.
It may take some days for keys to propagate to all servers in the network.
Novice signers should read the documentation and practice. Consider using an
isolated installation to store the code signing key and to sign releases.
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: content
It is important that the right legal contracts are in place for all source code at Apache
and that the right process has been followed. For the majority of the time, this
is easy: committers create original works which are licensed by Apache under
a CLA or CCLA
TODO: complete content
TODO: the incubator requires that users are informed that the by
including a standard disclaimer. may be include in README, RELEASE_NOTES
DISCLAIMER. It is recommended that it is not included in NOTICES
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.
There are two distinct approaches: release candidate and TODO.
There are several good versioning strategies used by projects at Apache. The version strategy
adopted is less important than adopting one that is clear and consistent and documenting it.
If there are strong opinions amongst developers on the right way to version then document this
strategy. If there are not then time can be saved by adopting an existing strategy with a good
fit. It is usually better to start by copying the documentation rather than using by reference.
Strategies sometimes change as do URLs. Project often (in time) find that they need to expand
or fine tune their versioning strategy and this is hard if another project's documentation is used.
A project should therefore use their own strategy.
TODO: notes on strategies.
The most common system of versioning is based on major.minor.point
where major, minor and point are all integers. Note that these are not decimals and
there is no necessity to raise a major version number after the minor version has
reached 9. The exact rules vary and it is recommended that a project agrees and documents
its own rules.
In addition to an official release with a particular version number, any number of
unofficial releases of various types may share the same number. These are usually
terms alphas, beta, release candidates, TODO: link to foundation release documents.
These release may be designated by adding an appropriate suffix to the release
number (for example, 3.11.15RC1). The exact form is not as important as
documenting the system adopted by the project and its consistent use. Users
should be able to predict the status of the release from the artifact and the documentation.
TODO: (move to a note) Notes on 0.x releases verses alpha and betas. It is better to use 0.x
releases than to create numerous alphas and betas for 1.0. Conventionally, 0.x releases
are aimed at early adopters only without a strong promise of easy upgrade or backwards
compatibility. 0.x is a good designation for a product that is not feature complete
but whose code is solid for those features which are implemented.
It is useful to use a system of versioning for development (non-release) version numbers that
allows artifacts built from a development code stream to be distinguished by their version
from releases. Choose any reasonable and appropriate system but documented it so that
users understand how to recognize the difference.
There are two major approaches to this problem. Some use a suffix to indicate a development
stream. Others use a property of the version number (conventionally odd or even).
TODO: odd, even version numbers - research httpd, linux
SNAPSHOT and dev are commonly used suffixes.
Typically these are set to the next minor version number in sequence. For example,
after cutting apache-foo-1.5.6, the version would be
1.6.
Every artifact distributed should have a name that is unique.
This allows each artifact to the recognized by its name and ensures that different artifacts do not
overwrite each other. Including apache in the name of the artifact not only gives
brand recognition but means influence can be exerted over errant downstream repackages
by trademark law. If this practice is adopted then the release manager merely has to ensure
that each artifact is uniquely named within the set of Apache artifacts. By including the name of
the project, each artifact only has to be unique within the artifacts release by the project. When
a project distributes several distinct products then the product name should also be included.
For each product, each type of package should be
assigned a consistent and unique name. Conventionally, source packages use src
and main binary packages no prefix. Typically each type of package is made available in a number of
compression formats. These are conventionally distinguished
by the usual file type suffix.
So, the traditional format is apache-project-product-type-version.format.
TODO: rewrite this is section distinguishing between the content and the presentation.
content may (and probably should) be replicated in many different places.
The content presented in the RELEASE_NOTES needs to be plain text etc
Release notes are a vital to for communication between an open source project
and its users. They are often the first documentation a user will read. First
impressions matter. Their content will often serve as the basis for TODO: link
announcements and other TODO: link grassroots publicity.
The content may be replicated in many places. Use the content as news on the
project website and as the basis for the download page. Use the content for
posting to TODO: link grassroots media. Use the content for postings to
announcement lists.
The release notes should be in a common and easily read format (plain text is best).
The release notes should easily located and so should be positioned in the base directory.
The content can often be edit for use in the announcement.
TODO: move to best practice?
TODO: contents
include a short description of the project and links to the apache site
Whenever possible, each type of package should ship with release notes.
The release notes document should therefore be committed to the source
repository so that it ships with the source package.
The first paragraph of the release notes should introduce the project and the release.
It is often useful to characterize the release (TODO examples). Spend time thinking
about the best organization. Important information should be prominent.
The exact contents of the release notes varies and it is not unusual for
this content to be distributed amongst several documents. This is fine:
these recommendations should be viewed as pertaining to the mass of
notes that accompany the release and do not need to be included
in any particular document.
Any changes which may effect a user who wishes to replace the last version with
this should be highlighted. In particular, document:
- Deprecations
- Binary incompatibilities
- Semantic incompatibilities (TODO: glossary)
It is recommended that (where possible) automated tests are used to verify
compatibility. Note that the discovery of incompatibilities at this stage
may require a change in version number or revision of function.
Release notes should be readable with minimal requirement. So, they should
be plain text with explicit line breaks at a reasonable number of characters
(80, say). Most projects now produce documentation that is formatted as
html. The development and supply of release notes in this format is fine
but release managers should create and supply a plain text version
by stripping out the formatting.
Remember that a user may have received the software indirectly. So, include
some brief details about the project and an url.
Release notes are important TODO: glossary guerrilla advertising for a project.
They should provide:
- an introduction for those who don't know the project in
detail
- briefly state the aims of the project
- briefly indicate the project's roadmap and how this release fits into it
- list ways to get involved with the project
- describe how to raise issues
This may be included by reference to the main documentation
but (for the benefit of those that don't read document) should be mentioned.
Some tools used by Apache projects:
TODO: should this be in best practices
TODO: add examples
A change log indicates the changes made to the project since the last release.
Some projects include a change log in the release notes documents.
Others use a separate document often called ChangeLog.
Maven can be used to generate a change log as part of the project documentation.
Change logs can be created in various ways. Some project ask committers to fill
in details each time they commit. Other rely on analyzing the commit messages
when the release is prepared. (To do this, go through the logs since the revision
of the last release. TODO example)
The change log typically includes every feature added and every bug resolved since
the last release.
TODO: links to dev pages
batch signing scripts in committers
TODO: consider moving content into foundation docs
OpenPGP compatible signatures must be generated to accompany releases.
Public key encryption is a deep and wide subject. However, the
knowledge required to safely create signatures for Apache releases can be
learnt in a short time. TODO: link to foundation docs
What can be sometimes confusing is that though a signature is required,
connection to the web of trust is only strongly encouraged not required.
A signature from a key which is well
connected to the Apache web of trust gives greater security than a signature
that is not.
However, the essential use of signatures at Apache is to allow
release managers themselves to check whether an artifact is identical
to the release they created. All that is required in this case is that the
release managers knows whether a signature is their own.
A project may release a number of distinct products created by the same community.
TODO: differences between products and packages.
TODO: this is probably a best practice
Source files should contain the license header whenever this is reasonable.
Templates are source documents and so this principle applies to them as well.
If these templates are used to generate documents which form part of the
package then the documents generated should contain the license header.
However, if this template is used by a user to generate output, usually
this output should be free of license restrictions. Most templating languages
allow comments which are not included in the output. If this is allowed
then the license header should be included in the template as a comment.
If not then consider adding a NOTE or a README to the directory rather
than a license header.
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.
TODO preamble TODO link to legal
It is convenient for users and more consistent if line endings for appropriate files
(text, xml, html and so on) reflect the platform usually associated with the
compression format (CRLF
for the zip and LF for the tar.gz).
Source packages can use svn export --native-es. Binary packages
build with Ant can use
fixcrlf.
It is rare for Apache projects to issue mainstream press releases
and it is very rare for releases to justify this. If there is likely to be mainstream
press interest in a release then please talk to the public relations committee.
TODO: link to public relations committee
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: links into legal documentation. discuss issues about which files need to apply.
All source capable of copyright should contain license header.
Easiest way to comply is to ensure that every human readable file has the header.
Note that source includes not just the source code compiled into the final product
but also all other resources such as style sheets, test code and resources, build files
and documentation source. When in doubt, add a header.
TODO: to
The issue of licenses on generated documentation is a little controversial. Copyright may not subsist
in a document which is generated by an transformation from an original. In which case, the license header
may be unnecessary. License headers should always be present in the original. Where it is
reasonable to do so, the templates should also add the license header to the generated documents.
TODO: check with legal-discuss then move this content into the legal pages and link with commentary
TODO: link into provenance
License headers may seem trivial and to some extent that is true.
The important issue is code provenance. All code contributions must be tracked and the
provenance of the code traceable.
Commit comments are an important to. When source
which is not originally created for the project is committed, the message should contain
details about the provenance of that source. When a patch is applied from an
issue tracking system
system, the issue should be noted in the commit message.
Releases are important. Released code is distributed widely. It is important that the provenance
for all released code is known and is appropriate. License headers are a way of documenting
provenance. Any source which is created for Apache should have the standard boilerplate text.
Other source should have the headers (copyright and license) retained. Before a release,
source which has not been originally created for (or donated to) Apache should be checked
against the current Apache policy.
Any source which does not have a license header must be considered suspect
and its provenance checked. There are several classes of source which do not require
license headers. It is useful to adopt a policy of documentation in this case perhaps
by including a short header if the file is generated (say) or by creating a README
in the directory containing license information. This makes code auditing much easier.
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
TODO: write up http://marc.theaimsgroup.com/?l=incubator-general&m=116577422312412&w=2
TODO: then check with Geir
The Apache License, Version 2
clause 4d states:
If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the flowing places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
Many other similar licenses contain such a clause or something similar
to it. So, if the release redistributes any source or artifacts
covered by licenses with these clauses, the contents of each
NOTICE must be present in the NOTICE distributed with the release.
The contents of the NOTICE are information. The LICENSE document
should contain the actual licenses under which each part of
the release is distributed but not any notices which the licenses
require.
For example (taken from JDBM)
this license. The form of this license is similar to the
Apache License, Version 1.0.
Clause 5 states:
5. Due credit should be given to the JDBM Project
(http://jdbm.sourceforge.net/).
The license itself should be appended to the LICENSE document with a header
indicating . A suitable note giving credit to the JDBM project (for example
This product includes software developed by The JDBM Project
(http://jdbm.sourceforge.net/).) should be appended to the NOTICE
document.
The contents of the NOTICE document should be included by all downstream distributors
and packagers. So, this is the right place for all required credits and attribution
notices required by any of the contents of the package (whether legally or ethically).
It is better to include any other types of explanations and notes
in the RELEASE-NOTES or in a README.
TODO: add bill's excellent quote (apologies for the pun)
Apache releases are high ceremony. A number of formal VOTEs binding upon Apache
are required before an release of any type.
When proposing a formal VOTE, it is useful to adopt a conventional form. VOTE threads
are conventionally prefixed by a [VOTE] subject. This helps everyone recognize that
this is a formal decision and to prioritize their reply. Many people filter their emails
into separate VOTE directories by using this prefix.
It is useful to separate a preamble giving context and background (which should be cut from replies) from the possible
VOTEs. This makes it easy and quick for people to post their VOTEs. When adopting this format,
it's usual to include the proposer's vote after the preamble.
For
example.
Stating the process for the VOTE (for example, minimum duration) in the preamble
allows anyone who objects to the process to register this immediately.
It is conventional to end a VOTE thread with a RESULT
post tallying the votes cast. To preserve the thread, this should be done by replying to the
original VOTE post and adding a [RESULT] prefix. The subject may be retained as is or
edited to indicate the result. For
example.
Be careful to check the voters against the appropriate list. Binding votes are cast by people on the
appropriate committee. The list of Incubator PMCers is
available TODO: link online. Note that
sometimes the online lists are out of date. TODO: link to foundation site.
The result post should list each voter and the vote cast. Non binding votes may be listed. If they are
then each binding vote should be indicated. If they are not then the post should state that only binding
votes have been included.
Each voter can (and should) verify that their vote has been correctly tallied. TODO link to problem thread.
When posting replies to a VOTE thread take particular care to change the subject.
When changing the subject it is conventional to reply to the relevant post and then edit the subject
adding the new subject flowed by [WAS and the d subject.
For example, d subject Re: Whatever may be edited to
New Foo [WAS Re:Whatever]. This ensures that the thread linkage between the topics
is retained but also makes it clear that the post now relates to a new subject.
TODO: move VOTE netiquette into either ppmc or lists and link from here
TODO: this has turned into best practice.
Each release requires a positive vote binding on Apache. This means
a . There is usually no need for this vote to be private. (A rare exception might
be a -1 due to a nearly discovered security issue, for example.)
In the case of podlings, a 3 binding +1s are required by members of the Incubator
PMC. To increase the chances of a prompt approval, mentors need to cast their
votes on the general list.
TODO: consider whether this would be better moved elsewhere
VOTEs on low volume mailing lists with small numbers of interested parties
usually require no management. VOTE threads on high volume mailing lists
or mailing lists with large numbers of active contributors require netiquette
and active management to avoid confusion. It is not uncommon for those
unfamiliar with these environments to find difficulties.
Long VOTE threads are hard to tally. Each opinion needs to be noted and acknowledged.
This allows people to check their votes and easily correct mistakes in the count.
It is vital in a long VOTE to ensure that debate is restricted on the VOTE thread.
If it looks likely that there is a risk that a VOTE will turn into a debate,
it is wise to allow people to discuss the issues first.
It is important that off topic or divergent posts are moved to separate threads with
other subjects.
It is usually cleaner to abandon a VOTE thread that goes astray or when the proposal
needs to be altered - for example, then issues are found in a release candidate.
Start a new VOTE thread with the revised proposal (in the case of the example, a new
release candidate).
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.
Typically, applications used to create tar.gz files are based on
GNU tar. Unfortunately, the tar which ships with some versions of Saris and some
(der) versions of MacOSX is not always compatible with the output of GNU tar.
TODO: check information and expand
A source-only release contains only the source package. Though users often prefer
binary packages, source-only releases can be useful early in the life of a project.
They require much less ceremony and encourage developers to get involved by finding
and fixing bugs. Occasionally, projects whose primary user base typically obtains
the software via a downstream repackage may prefer to release source only.
Releases containing only binary packages are not performed at The Apache Software Foundation.
The Apache Software Foundation distributes open source software to the public.
Open source development is characterized by the accessibility of the source. Binary-only packages
discourage developers from interacting with the source. Every successful Apache
project needs to recruit new developers to carry the project forward.
A Contributor License Agreement (CLA) is a contract between a contributor
and Apache granting Apache rights to code contributed. Every committer
must have a signed CLA on file.
See
A Corporate Contributor License Agreement (CCLA) is a contract between a corporation
and Apache granting Apache rights to code contributed by its employees. Some legal
jurisdications do not allow software developers rights to code created even in their own
time on their own machines. This applies to most US developers. A CCLA protected Apache
and .
See
A file that is actually made available for download. Note this does NOT imply
the file is intended for wide-scale distribution to the general public. Such
distributions are reserved for formally-approved releases. For instance artifacts
included in release candidates, periodic builds, and even the code repository itself,
are only intended for people participating in project development.
TODO (include link to infra documentation)
Document containing the licenses for the package.
Document containing additional required copyright and attribute information.
Process and procedure associated with - but not necessary to - a particular end.
TODO: link to foundation docs
Meta data, enumerating the contents of the Jar, associated with the Java Jar format.
TODO link to sun documentation
Text referring to the license for a file (as opposed to the license text).
TODO (include link to legal documentation)
Committer responsible for shepherding the release. This role is rather time consuming
and often involves tedious tasks, but it is essential that the release manager keep
on top of everything. Release managers may be elected for a release by the project
by formal vote, or by invoking lazy consensus, but such votes are not really necessary.
A procedural description of the role as it functions within the incubator follows.
Once a release manager has stepped forward, the first thing they should do is to
consult and correct the project's release
documentation. Once that has been addressed, the candidate artifacts should be
prepared and a formal vote on those artifacts must be conducted by the release manager
on the project's development list. All votes are welcome, but only those votes by the
project's PPMC members (or IPMC
members) count towards the final tally. The voting period should be no less than 72
hours, and at the end of the voting the release manager should post a final tally to the list.
The vote passes if there are at least 3 +1's from the PPMC/IPMC members and more
+1's than -1's. This is what is meant by majority consensus. If you've gotten
this far, congratulations, you're nearly ready to upload and announce the release.
It is Apache policy that all releases be formally approved by the responsible PMC.
In the case of the incubator, the IPMC must approve all releases. That means there
is an additional bit of voting that the release manager must now oversee on
general@incubator in order to gain that approval. The release manager must inform
general@incubator that the vote has passed on the project's development list, and
should indicate any IPMC votes gained during that process. A new vote on the
release candidate artifacts must now be held on general@incubator to seek majority
consensus from the IPMC. Previous IPMC votes issued on the project's development
list count towards that goal.
Once the 72-hour minimum voting period has ended on general@incubator, the release
manager should tally the votes and declare a result. If majority consensus has
been achieved with respect to IPMC votes, the release manager may proceed with the
release. Read the remainder of this document for details on the remaining steps
regarding uploading artifacts to the podling's distribution directory, dealing with
maven central if appropriate, and announcing the release to the public.
TODO (include link to infra documentation)
TODO say something about the technical release manager (who
cuts the release) and the social one (who organizes it).
Collection of artifacts to be tested and voted on in order to release them. Sometimes
folks use this term to refer only to a candidate source package.
A file created from a project's source code with the intent to distribute. Note
this is not to be confused with the notion of a
Java package,
or however else the word "package" may be used by any specific programming language community.
Here we use it in the generic sense to refer to software packages.
Artifact is a generic term for a package, or more generally a file of any kind.
Packages are typically either source packages or binary packages (i.e. builds).
Sometimes separate documentation packages are released alongside the source package.
A source package is typically a compressed archive file containing a
simple export from the repository, optionally with some preconfiguration
scripts run on it.
Binary packages are typically platform-specific builds of the source package.
There is only one canonical source package but there may be several binary packages.
The actual execution of the release. Typically consists of building the packages
from the repository tag, along with any other associated artifacts, and signing them.
TODO: link to infra
Guidelines are documented recommendations which have not yet been blessed as policy.
There are usually good reasons why project should follow the guidelines given
even if these may be initially obvious.
Documents a particular release of a product rather than the product itself.
Note that release documentation also occasionally refers to the instructions for the
release manager to follow during the process of creating a release.
An application that store manages issues reported in Apache products. TODO: links
The committee charged by the board
with the management of the Apache Incubator Project.
See also:
The group of committers charged with development and direction of a podling. Not a formally recognized
Apache committee- that only happens once the podling graduates. The active Podling PMC members form
the seed for a formal PMC if the project graduates to a top-level Apache project; otherwise the active
Podling PMC members join a pre-existing PMC to continue development as a subproject of that PMC.
A committee charged by the board
with the management of an Apache Project.
See also:
All Incubator authorised by the incubator are contained within the
Incubator distribution directory:
www.apache.org/dist/incubator
All releases created by a podling are contained within a sub-directory of the
Incubator distribution directory.
This is www.apache.org/dist/incubator/{podling} where {podling}
is the name of the podling.
For example, the podling distribution directory for podling foo is
www.apache.org/dist/incubator/foo.
See also:
