You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@incubator.apache.org by jo...@apache.org on 2017/01/07 15:25:01 UTC
svn commit: r1777806 [2/2] - in /incubator/public/trunk/content:
facilities.xml guides/draft-simple-release-management.xml
guides/release-java.xml guides/release.xml guides/release_manifest.txt
guides/releasemanagement.xml
Modified: incubator/public/trunk/content/guides/releasemanagement.xml
URL: http://svn.apache.org/viewvc/incubator/public/trunk/content/guides/releasemanagement.xml?rev=1777806&r1=1777805&r2=1777806&view=diff
==============================================================================
--- incubator/public/trunk/content/guides/releasemanagement.xml [utf-8] (original)
+++ incubator/public/trunk/content/guides/releasemanagement.xml [utf-8] Sat Jan 7 15:25:01 2017
@@ -14,1856 +14,77 @@ limitations under the License.
-->
<!DOCTYPE document
-[
-<!ENTITY root-path '..'> <!-- The path to the incubator root -->
-]>
+ [
+ <!ENTITY root-path '..'> <!-- The path to the incubator root -->
+ ]>
<document>
- <properties>
- <atom url="http://mail-archives.apache.org/mod_mbox/incubator-general/?format=atom">general@incubator.apache.org Archives</atom>
- <title>Apache Incubator: Release Management (DRAFT)</title>
- </properties>
- <body>
- <section id='intro'><title>A Guide To Release Management During Incubation (DRAFT)</title>
- <section id='TOC'><title>Contents</title><toc/></section>
+ <properties>
+ <atom url="http://mail-archives.apache.org/mod_mbox/incubator-general/?format=atom">general@incubator.apache.org
+ Archives
+ </atom>
+ <title>Apache Incubator: Release Management</title>
+ </properties>
+ <body>
+ <section id='intro'>
+ <title>A Guide To Release Management During Incubation</title>
+ <section id='TOC'>
+ <title>Contents</title>
+ <toc/>
+ </section>
<section id="status">
- <title>Status - DRAFT</title>
- <p>
-This document is under active <a href='#help-wanted'>development</a>. This is a first
-draft intended to allow public review.
- </p>
- </section>
-
- <a id="organisation"></a> <!-- old anchor -->
- <a id="usage"></a> <!-- old anchor -->
- <a id="apache-releases"></a> <!-- old anchor -->
- <section id="abstract">
- <title>Abstract</title>
- <p>
-This <a href="/guides/index.html">guide</a> is descriptive, not normative. It has three main
-purposes.
- </p>
- <ol>
- <li>Summarize and provide <a href="#references">references</a> to normative release policy.</li>
- <li>Describe the process of creating an incubating release.</li>
- <li>Serve as a repository for non-binding best-practice guidelines.</li>
- </ol>
- <p>
-Releases are important:
- </p>
- <ul>
- <li>Publishing software has legal consequences. </li>
- <li>Most users interact with a project only through its releases. They are a public face
- of the project and are often the first chance to make a good impression.</li>
- <li>Poor quality releases reflect badly not only on the project but also the foundation as
- a whole. </li>
- </ul>
- <p>
-Incubating releases, despite the "incubating" label and <a
-href="http://incubator.apache.org/guides/branding.html#disclaimers">disclaimer</a>, are official
-Apache releases. (Legally, they are the product of the Incubator PMC acting on behalf of the
-Foundation.) As such, they are expected to adhere to all Foundation-wide release policies. While
-deviations are occasionally allowed, each exception must be documented and approved by the IPMC.
- </p>
-
- <p>TODO: Move the remaining paragraphs in this section elsewhere.</p>
- <p>
- Apache release policy is minimal (though its principles have some subtle consequences).
- However, most projects have a lot more ceremony,
- rules and traditions to ensure high quality releases. These often evolve
- over time. Often projects realise too late that these need to be documented.
- </p><p>
- Podlings can short circuit this process by starting out with written
- release documentation. It is strongly recommended that Podlings invest
- time looking at the best practices recommended in this document. By selection
- and modification, sections of this document can be used to quickly and easily
- bootstrap a release guide.
- </p>
- </section>
- </section>
-
- <!-- Old glossary links -->
- <a id='glossary'></a>
- <a id='glossary-artifact'></a>
- <a id='glossary-binary-package'></a>
- <a id='glossary-ceremony'></a>
- <a id='glossary-cla'></a>
- <a id='glossary-ccla'></a>
- <a id='glossary-guidelines'></a>
- <a id='glossary-ipmc'></a>
- <a id='glossary-license-header'></a>
- <a id='glossary-license'></a>
- <a id='glossary-package'></a>
- <a id='glossary-package-type'></a>
- <a id='glossary-pmc'></a>
- <a id='glossary-notice'></a>
- <a id='glossary-release-candidate'></a>
- <a id='glossary-release-manager'></a>
- <a id='glossary-source-package'></a>
- <section id='references'><title>References</title>
-
- <p>
-For normative release policy, consult the following resources:
- </p>
-
- <ul>
- <li><a href="http://www.apache.org/dev/release.html">ASF Release Policy</a></li>
- <li><a href="/incubation/Incubation_Policy.html#Releases">Incubator Release Policy</a></li>
- </ul>
-
- <p>
-Release Managers and PPMC members should also familiarize themselves with the following:
- </p>
-
- <ul>
- <li><a href='http://www.apache.org/dev/#releases'>Index of release-related developer resources</a></li>
- <li><a href='http://www.apache.org/dev/release-publishing.html'>ASF release process guide</a></li>
- <li><a href='http://www.apache.org/dev/licensing-howto.html'>How-to for assembling LICENSE
- and NOTICE</a></li>
- <li><a href='http://www.apache.org/legal/src-headers.html'>ASF Source Header and Copyright
- Notice Policy</a></li>
- <li><a href='http://www.apache.org/legal/resolved.html'>ASF Legal Previously Asked
- Questions</a></li>
- <li><a href='http://www.apache.org/dev/release-signing.html'>Release signing guide</a></li>
- <li><a href="http://www.apache.org/foundation/glossary.html">Glossary of Apache-Related Terms</a></li>
- </ul>
-
- <section id='subpages'><title>See Also</title>
- <p>
-This page spells out requirements and best practices which apply equally to <em>all</em>
-Incubator podlings. Additional information which applies only to specific podlings is
-available on auxiliary pages.
- </p>
- <section id='java-subpage'><title>Java-specific Release Management Issues</title>
- <p>
- The <a href="release-java.html">Java-specific Release Management Issues</a> page
- covers topics pertaining to Java, Maven, Ant, and so on.
- </p>
- </section>
- </section>
- </section>
-
- <section id='check-list'><title>Release Check List</title>
- <p>
-Each review item in this list is either required by Foundation-wide policy and would block a release by any Apache
-top-level project, or is required by Incubator <a
-href="http://incubator.apache.org/incubation/Incubation_Policy.html">policy</a>.
- </p>
-
- <dl>
-
- <dt>
-1.1 Checksums and PGP signatures are valid.
- </dt>
- <dd>
-See the <a
-href="http://www.apache.org/dev/release-signing.html#basic-facts">Release
-Signing</a> dev documentation.
- </dd>
-
- <dt>
-2.1 Build is successful including automated tests.
- </dt>
- <dd>
-The expanded source archive is expected to <a
-href="http://www.apache.org/dev/release.html#what-must-every-release-contain">
-build and pass tests</a>.
- </dd>
-
- <dt>
-3.1 DISCLAIMER is correct, filenames include "incubating".
- </dt>
- <dd>
-See the <a
-href="http://incubator.apache.org/guides/branding.html#disclaimers">Podling
-Branding Guide</a>.
- </dd>
-
- <dt>
-3.2 Top-level LICENSE and NOTICE are correct for each distribution.
- </dt>
- <dd>
-See the <a href="http://www.apache.org/dev/licensing-howto.html">Licensing
-How-To</a>, plus various pages under <a
-href="http://www.apache.org/legal">Legal Affairs</a>.
- </dd>
-
- <dt>
-3.3 All source files have license headers where appropriate.
- </dt>
- <dd>
-See the <a href="http://www.apache.org/legal/src-headers.html">ASF Source
-Header and Copyright Notice Policy</a>.
- </dd>
-
- <dt>
-3.4 The provenance of all source files is clear (ASF or software grants).
- </dt>
- <dd>
-See the <a
-href="http://incubator.apache.org/guides/mentor.html#initial-ip-clearance">IP
-clearance</a> section of the Mentor's guide, as well as the <a
-href="http://incubator.apache.org/incubation/Incubation_Policy.html#Releases">Releases</a>
-section of the Incubator's policy page.
- </dd>
-
- <dt>
-3.5 Dependencies licenses are ok as per http://apache.org/legal/
- </dt>
- <dd>
-See <a href="http://www.apache.org/legal/resolved.html">ASF Legal Previously
-Asked Questions</a>.
- </dd>
-
- <dt>
-3.6 Release consists of source code only, no binaries.
- </dt>
- <dd>
-Each Apache release <a
-href="http://www.apache.org/dev/release-publishing.html#valid">must contain a
-source package</a>. This package may not contain compiled components (such as
-"jar" files) because compiled components are not open source, even if they
-were built from open source.
- </dd>
-
- </dl>
-
- <p>
-A list of possible additional items is
-maintained on the <a href="http://wiki.apache.org/incubator/ReleaseChecklist">ReleaseChecklist</a> wiki page.
- </p>
-
- </section>
-
- <section id='guidelines'><title>Guidelines</title>
- <!--
- <p>
- TODO: may need to think about this title. The idea is to try to clearly separate guidelines
- about release processes and procedures from rules and guidelines.
- </p>
- <section id='process'><title>Release Process</title>
- <p>
-The minimal formal requirements for an official ASF release are (contrary to rumor) minimal.
-A successful binding VOTE by a project means that the artifact is an official ASF release.
-Releases approved by a podling must comply with the current ASF release policies.
-Those with binding votes must check that the release complies with these policies.
- </p>
- <p>
- In practice, most projects adopt more ceremony than this minimum for a number of important reasons.
- </p>
- <p>
-ASF releases are often widely distributed and long lived. This document is not normative.
-It should not be seen as a recipe for definitive ASF releases. It is
-strongly recommended that podlings create their own release guidelines. Hopefully the incubator documentation
-may help to shorten the process of creating good release guidelines for the podling by providing
-options, highlighting issues and providing templates.
- </p>
- <p>
-There is great variety amongst existing Apache project. Diversity is good.
- </p>
- <p>
-There is inevitably a conflict between the excellent advice to release often and the documentation
-required to create good releases.
- </p>
- <ul>
- <li>
- ASF releases are high visibility and long lived. A release manager may find that a
- poor quality release may be held up as an example for years to come.
- </li>
- <li>
- TODO: legal consequences
- </li>
- </ul>
- <p>
-A podling should have a release guide. A good starting point (once this document has been read)
-is release guides for existing projects:
- </p>
- <ul>
- <li><a href='http://httpd.apache.org/dev/release.html'>HTTPD</a></li>
- <li><a href='http://jakarta.apache.org/commons'>Jakarta Commons</a></li>
- <li><a href='http://struts.apache.org/releases.html'>Struts</a></li>
- </ul>
- <p>Please also check the <a href="http://www.apache.org/dev/release.html">Apache Release guidelines</a>
- in particular the <a href="http://www.apache.org/dev/release.html#license">license requirements</a>.
- Also you might find it useful to read some of the
- <a href="http://wiki.apache.org/general/ReleaseGuides">release guides</a> from other projects.
-</p>
- <p>
-Most projects find it difficult to issue quality releases without appointing a
-<a href='http://www.apache.org/foundation/glossary.html#ReleaseManager'>release manager</a>. Typically,
-release managers are elected by lazy consensus. Nominating oneself is not
-usually consider a <em>faux pas</em>.
-In the early stages of a release, they should take responsibility for organizations,
-in the middle stages of a release, for deciding which code will be included in the release,
-in the late stages for marshaling the VOTEs required for formal approval
-then finally for cutting the release.
-TODO: maybe be better in a time line
- </p>
- -->
- </section>
-
- <section id='release-distribution'><title>Distributing Releases</title>
- <p>
- Once a release has been approved by the
- <a href="&root-path;/incubation/Roles_and_Responsibilities.html#Incubator+Project+Management+Committee+%28PMC%29">Incubator PMC</a>,
- it needs to be uploaded to the servers for wider distribution. A description of this process and the policy
- governing it follows.
- </p>
-
- <div class="alert-message block-message warning">
- <p><strong>Attention!</strong>
- Sometimes you <a href="http://www.apache.org/dev/release#heads-up">need to talk to Infra</a> before
- distributing a release, esp. when your release artifacts are huge.
- </p>
- </div>
-
- <section id='glossary-incubator-dist'><title>Incubator Distribution Directory</title>
- <p>
-All Incubator authorised by the incubator are contained within the
-Incubator distribution directory:
- </p>
-<source>
-https://dist.apache.org/repos/dist/release/incubator
-</source>
- </section>
- <section id='glossary-podling-dist'><title>Podling Distribution Directory</title>
- <p>
-All releases created by a podling are contained within a sub-directory of the
-<a href='#glossary-incubator-dist'>Incubator distribution directory</a>.
-This is <code>www.apache.org/dist/incubator/{podling}</code> where <em>{podling}</em>
-is the name of the podling.
- </p>
- <p>
-For example, the podling distribution directory for podling <code>foo</code> is
- <code>https://dist.apache.org/repos/dist/release/incubator/foo</code>.
- </p>
- </section>
- <section id='distribution-policy-overview'><title>Policy Overview</title>
- <p>
- Distribution policy with regard to releases is simple:
- </p>
- <ul>
- <li>
- The Incubator
- <a href="&root-path;/incubation/Incubation_Policy.html#Releases">insists</a>
- that artifacts for <em>{podling}</em> are contained within
- <code>www.apache.org/dist/incubator/{podling}</code>.
- </li>
- <li>
- Infrastructure insists that releases are mirrored and that
- <a href='http://www.apache.org/dev/release-signing.html#keys-policy'>signatures+checksums</a>
- are uploaded for every artifact.
- </li>
- </ul>
- <p>
- All non-release software distributions (e.g. links to the subversion repository, automated builds, etc.)
- are reserved for folks participating in product development on the project's developer list.
- See <a href='http://www.apache.org/dev/release.html#release-typeso'>this description</a> for details
- on the policy.
- </p>
- <p>
- The rest is up to the community to decide and that's quite a lot.
- Documenting the release management processes is important and often neglected.
- It is
- <a href='#document-usage'>strongly
- recommended</a> that the rest of this section is used as the basis for a written release
- guide for the podling.
- </p>
- </section>
-
- <a id='distribution-permissions'></a> <!-- old anchor -->
- <section id='understanding-distribution'><title>Understanding Release Distribution</title>
- <section id='understanding-upload'><title>Uploading Artifacts</title>
- <p>
- Released artifacts are distributed at (<code>www.apache.org/dist</code>) for all Apache projects. New files
- can be added to this site via the svn repository at (<code>https://dist.apache.org/repos/dist/release</code>).
- Each project (including the Incubator) owns a directory within <code>/release</code>.
- </p>
- <p>
- The <a href='#glossary-podling-dist'>podling distribution directory</a>
- is contained within this <a href='#glossary-incubator-dist'>Incubator distribution directory</a>.
- The <a href='http://incubator.apache.org/incubation/Roles_and_Responsibilities.html#Incubator+Project+Management+Committee+%28PMC%29'>Incubator Project Management Committee (IPMC)</a>
- is responsible for all releases.
- Arrangement and management of releases within each podling distribution directory
- is delegated to the appropriate podling.
- </p><p>
- Release artifacts can be published to the podling distribution directory
- using subversion. If you do not see a subversion directory corresponding to your project,
- make an INFRA JIRA request. Additional information is available at the
- <a href="http://www.apache.org/dev/release-publishing.html#distribution_dist">Publishing Releases</a>
- page.
- </p>
- </section>
- <section id='understanding-mirroring'><title>Mirroring</title>
- <p>
- To avoid excessive use of bandwidth and to increase download speeds,
- official releases are made available through a
- <a href='http://www.apache.org/mirrors/'>global network</a> of
- <a href='http://www.apache.org/info/how-to-mirror.html'>volunteer mirrors</a>.
- Using these mirrors has some notable
- <a href='http://www.apache.org/dev/mirrors.html'>differences</a> from unmirrored
- downloads.
- In particular, a <a href='http://www.apache.org/dev/release-download-pages.html'>script</a>
- must be used to direct the download to an appropriate URL.
- </p><p>
- Users will download the mirrored release artifacts from machines outside Apache control.
- Users need to verify that the copy downloaded is identical to the original.
- Mirrored copies of checksums, <code>KEYS</code> and signature files
- (<code>.asc</code> and <code>.md5</code> files) will be present on the
- mirrors but must <strong>never</strong> be used for verification. So, all links
- from the podling website to signatures, sums and <code>KEYS</code> need to refer
- to the original documents on <code>www.apache.org</code>.
- See <a href='http://www.apache.org/dev/release-signing.html'>release signing guide</a> for more information.
- </p>
- </section>
- <section id='understanding-archiving'><title>Archiving</title>
- <p>
- All Apache releases form an important part of the history of a project.
- They are therefore archived with the aim of preserving them indefinitely
- for future reference.
- <p></p>
- <a href='http://archive.apache.org'>http://archive.apache.org</a>
- is the archive host. Releases are archived under
- <a href='http://archive.apache.org/dist'>http://archive.apache.org/dist</a>.
- Please remember that these archives are served from Apache bandwidth. Anyone
- who wants to obtain a large quantity of data from the archives should
- contact the
- <a href='http://www.apache.org/foundation/how-it-works.html#infrastructure'>Infrastructure Team</a>.
- </p><p>
- All artifacts within <code>www.apache.org/dist</code> will be automatically
- archived. When a new artifact is uploaded, it will be sync'd to the archive.
- The sync'ing is scheduled to operate several times a day. So it may be some
- hours before an added artifact is archived.
- </p><p>
- When an (archived) artifact is deleted from the live distribution, it will
- remain in the archives. See
- <a href='http://www.apache.org/dev/release.html#how-to-archive'>how to archive</a>.
- </p>
- </section>
- <section id='understanding-security'><title>Security</title>
- <section id='distribution-checksums-sigs'><title>Sums And Signatures</title>
- <p>
- Start by reading the <a href='http://www.apache.org/dev/release-signing.html'>guide</a>
- and <a href='http://www.apache.org/dev/release-signing.html#policy'>policy</a>.
- </p><p>
- Sums are a convenient and simple way for users to verify releases.
- Signatures play a critical role in ensuring security for releases.
- </p><p>
- If a release is signed by a key that is strongly connected to the
- <a href='http://www.apache.org/dev/release-signing.html#web-of-trust'>Apache web of trust</a>
- then it can be <a href='http://www.apache.org/dev/release-signing.html#web-of-trust'>verified</a>
- (by anyone with access to that web of trust) that a file has not been modified
- (by anyone without access to the corresponding private key). This allows the infrastructure
- team to check that releases have not been tampered with.
- </p><p>
- So, it is crucial that new release managers ensure:
- </p>
- <ul>
- <li>that the code signing private key is
- <a href='http://www.apache.org/dev/release-signing.html#private-key-protection'>kept safe</a>.</li>
- <li>that the <a href='http://www.apache.org/dev/release-signing.html#keys-policy'><code>KEYS</code></a>
- file contains the public key. (Storing public keys in a KEYS file is recommended but is
- not policy.)</li>
- </ul>
- <p>
- It is important that the key is
- <a href='http://www.apache.org/dev/release-signing.html#apache-wot'>linked</a>
- to the Apache <a href='http://www.apache.org/dev/release-signing.html#web-of-trust'>web of trust</a>.
- </p><p>
- Always upload the checksums and signatures at the same time as the artifact.
- This will ensure no false alarms from the infrastructure team.
- </p>
- </section>
- <section id='distribution-modifications'><title>Modifications</title>
- <p>
- Once an artifact has been uploaded, it must never be modified. Not only is there no
- guarantee that the modified artifact will be correctly archived or mirrored but
- a change to an existing artifact is the signature of an attack.
- </p><p>
- This applies only to release artifacts. It's expected that
- <code>README'</code>s, <code>NOTES</code>, <code>KEYS</code>, and so on
- may be updated.
- </p>
- </section>
- </section>
- </section>
- <section id='distribution-check-list'><title>Distribution Check List</title>
- <ul>
- <li>Directory is <code>www.apache.org/dist/incubator/<em>podling</em></code></li>
- <li>Group is <code>incubator</code></li>
- <li>All artifacts have matching checksums and signatures</li>
- <li>Old releases archived</li>
- <li>Links to <code>KEYS</code>, signature and checksum documents
- refer to the originals on <code>www.apache.org</code></li>
- </ul>
- </section>
- <section id='distribution-best-practice'><title>Best Practice</title>
- <section id='distribution-layout'><title>Layout</title>
- <p>
- A podling is free to choose a suitable layout for its released
- artifacts within the
- <a href='#glossary-podling-dist'>podling distribution directory</a> .
- It is recommended that standard layouts (commonly used by other projects)
- be studied and that the layout adopted is documented in the podling's
- release documentation. The descriptions which follow can be used as a
- useful basis for this documentation
- </p><p>
- The choice between different layouts is mostly subjective branding.
- The mirroring and archiving infrastructure should work well
- with most choices.
- </p>
- <section id='distribution-layout-plain'><title>Plain Artifacts</title>
- <p>
- All artifacts, checksums and signatures placed directly into the
- <a href='#glossary-podling-dist'>podling distribution directory</a>.
- No subdirectories are created.
- No <a href='#distribution-release-documentation'>release documentation</a>
- is placed within the distribution directory.
- </p>
- </section>
- <section id='distribution-layout-misc'><title>Miscellaneous Documents</title>
- <p>
- All files contained in <code>www.apache.org/dist</code> will be mirrored.
- So, in addition in archives other documents placed in the distribution
- directories will be available on the mirrors for casual browsing.
- </p><p>
- As is traditional in some communities, some like to add notices
- (such as <code>RELEASE_NOTES</code>, <code>README</code>
- and <code>CHANGES</code>) for each release. Note that from publicity
- perspective it may be effective to include this information on the
- download page as well as in the release itself.
- </p><p>
- The HTTPD runs with fancy indexing enabled. So, creating <code>HEADER.html</code> and
- <code>FOOTER.html</code> documents allows the text of the index page to be customised.
- </p>
- </section>
- <section id='distribution-layout-structured'><title>A Structured Layout</title>
- <p>
- Many projects use structured layouts. For example:
- </p>
- <ul>
- <li><a href='http://www.apache.org/dist/ant/'>Ant</a></li>
- <li><a href='http://www.apache.org/dist/httpd/'>HTTPD</a></li>
- </ul>
- <p>
- The common theme is that each type of artifact is grouped into a
- subdirectory. For example, binary packages into <code>binaries</code>
- and source packages into <code>source</code> (say).
- </p>
- <p>
- Often symbolic links are created from the root of the project distribution
- directory to the latest version of each release. This allows scripts or users to
- easily locate the latest release.
- </p>
- </section>
- </section>
- <section id='distribution-release-documentation'><title>Release Documentation</title>
- <p>
- Many project distribute notices for a release (such as <code>RELEASE_NOTES</code>,
- <code>README</code>, <code>CHANGES</code> and so on) in addition to the main
- compressed archives. This allows users to read them and decide whether they want
- to download the archive artifacts.
- </p><p>
- There are also some compelling arguments for making the documentation for a release
- available for browsing online. (Issuing documentation as compressed archives is just
- another type of distribution and the standard rules for artifacts apply.) This
- makes support of releases easier and helps users understand which release
- is most appropriate for them.
- </p><p>
- Some projects do exactly this.
- For example:
- </p>
- <ul>
- <li>HTTPD
- <ul>
- <li><a href='http://httpd.apache.org/docs/2.0/'>2.0</a></li>
- <li><a href='http://httpd.apache.org/docs/2.2/'>2.2</a></li>
- </ul>
- </li>
- <li><a href='http://commons.apache.org/digester/'>Commons Digester</a>
- <ul>
- <li><a href='http://commons.apache.org/digester/commons-digester-1.7/apidocs/'>1.7 API</a></li>
- <li><a href='http://commons.apache.org/digester/commons-digester-1.6/docs/api/'>1.6 API</a></li>
- </ul>
- </li>
- </ul>
- <p>
- Online documentation should be archived so that it can be easily recreated.
- Though using <code>www.apache.org/dist</code>
- for these files is convenient and ensures that they are archived, it should not
- be used for this purpose. Documentation typically consists of many relatively
- small files and so is inefficient to sync. Users will view it using http and so
- there is no advantage in these files being distributed to the mirrors. The cost
- of syncing to the mirrors should therefore be avoided.
- </p><p>
- The best approach is to commit the documentation for a release into subversion.
- Then check out into a directory in the website.
- Generally, checking generated documentation into source control is often
- considered bad practise. But it is very suitable for fixing the documentation
- for a particular release.
- </p><p>
- It would be possible to use the subversion URL directly. However, checking out
- into the website space is better from the perspective of server load and website
- mirroring. So that is recommended.
- </p>
- </section>
- <section id='archiving-old-releases'><title>Archiving Old Releases</title>
- <p>
- Old releases should be archived
- (<a href='http://www.apache.org/dev/release.html#how-to-archive'>by deletion</a>)
- <a href='http://www.apache.org/dev/release.html#when-to-archive'>promptly</a>.
- For podlings, typically all old releases should be archived when a new one
- becomes available.
- </p>
- <p>
- <code>.htaccess</code> files are sometimes used to redirect live urls to archived releases.
- Direct links to distributions on <code>www.apache.org</code> bypass the mirroring.
- They should therefore be discouraged. It is therefore best to save the effort and not
- offer redirects for archived (mirrored) releases.
- </p><p>
- If a redirect is used then for performance reasons, then a <code>.htaccess</code> in the root
- incubator directory should be used.
- </p>
- </section>
- <section id='distribution-mirroring'><title>Mirroring Scripts</title>
- <p>
- There are two options:
- </p>
- <ul>
- <li>Use the
- <a href='http://www.apache.org/dev/release-download-pages.html#closer'>generic mirror script</a></li>
- <li>Create a <a href='http://www.apache.org/dev/release-download-pages.html#custom'>
- custom script</a> for <a href='http://uima.apache.org/downloads.cgi'>example</a>.</li>
- </ul>
- <p>
- The generic script can be used immediately and requires the minimum of setup.
- Creating a custom script allows control over the look, feel and content of the
- download page but requires more initial effort.
- </p><p>
- A consequence of mirroring downloads is that the number of downloads cannot be
- monitored directly by using
- <a href='http://people.apache.org/~vgritsenko/stats/index.html'>hits</a> on the Apache site.
- When using a custom script, it may be possible to use a service like
- <a href='http://www.google.com/analytics/en-GB/index.html'>Google analytics</a>
- to gain a reasonable estimate.
- </p><p>
- It is important that users verify releases. Apache has no control
- over the integrity of releases on mirrors.
- </p><p>
- It is recommended that the download page is used to remind users that they
- need to verify releases and to give instructions on how they can do this.
- Links provided to checksums and signatures need to refer to the originals on
- <code>www.apache.org</code> and not the copies on the mirrors. More
- information can be found in the
- <a href='http://www.apache.org/dev/release-signing.html'>signing guide</a>.
- </p>
- </section>
- <section id='distribution-signing'><title>Signatures</title>
- <p>
- Understand the <a href='http://www.apache.org/dev/release-signing.html'>guide</a>.
- See <a href='#signing'>signing best practice</a>.
- </p>
- <p>
- Each podling should maintain its own
- <a href='http://www.apache.org/dev/release-signing.html#keys-policy'>KEYS</a>
- file directly in the <a href='#glossary-podling-dist'>podling distribution directory</a>.
- It is recommended that all committers add their keys to that file.
- </p>
- </section>
- <section id='distribution-defects'><title>Dealing With A Defect</title>
- <p>
- Once an artifact has been uploaded, it must never be modified. No matter how
- serious a defect is discovered, the right action is to roll a new
- one with a new number.
- </p><p>
- Very serious defects may necessitate the withdrawl of a release. This should be done
- by:
- </p>
- <ol>
- <li><a href='http://www.apache.org/dev/release-publishing.html#archive'>Archiving</a> the
- release (so that it is no accessible from <code>www.apache.org/dist</code>).
- It may be some hours before an artifact added is archived.
- Check that
- <code>archive.apache.org/dist</code> contains the archived release before deleting
- the original.
- If necessary, use a temporary <code>.htaccess</code> to prevent access during this period.
- </li>
- <li>Posting a suitable announcement (to the same lists that received the original)</li>
- <li>Adding a suitable notice to the download page</li>
- </ol>
- </section>
- </section>
- </section>
-
- <section id='rules'><title>Rules</title>
- <p>
-Every incubator release is also an Apache release. So Apache policy must be followed.
-Incubator policy is additional and builds on these rules.
- </p><p>
-Release managers for podlings
-need to read the <a href='http://www.apache.org/dev/index.html#releases'>release</a>
-and <a href='http://www.apache.org/legal'>legal</a>
-documentation on the main <a href='http://www.apache.org'>Apache site</a>.
- </p>
- <p>
-A few important topics are discussed below. These are a supplement and not a substitute
-for the Apache documentation.
- </p>
- <section id='signing'><title>Signing</title>
- <p>
- The release manager need to create a
- <a href='http://www.apache.org/dev/release-signing.html#sign-release'>signature</a>
- for every artifact released. It only takes a little time to create a key and the process
- is reasonably straight forward.
- </p>
- <p>
-However, it is recommended that enough time is taken to gain a basic understanding of the
-public key cryptography.
-Read the <a href='http://www.apache.org/dev/release-signing.html'>Apache Signing Guide</a>
-and at least some of the background material linked from it.
- </p>
- <p>
- See:
- </p>
- <ul>
- <li>
-<a href='http://www.apache.org/dev/release-signing.html'>Apache Signing Guide</a>
- </li>
- </ul>
- </section>
- <section id='naming'><title>Naming</title>
- <p>
-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.
- </p>
- <p>
-For example, one good name for product bar Apache Foo Project would be <code>apache-foo-bar</code>.
- </p>
- <p>
-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 <code>incubating</code> (though small variations
-for the sake of readability are usually acceptable).
- </p>
- <p>
-For example, for podling foo, both <code>apache-foo-incubating</code> and
-<code>foo-incubating</code> would be acceptable names.
- </p>
- <p>
- See also:
- </p>
- <ul>
- <li>
- <a href="&root-path;/incubator/Incubator_Policy.html">Incubator Policy</a>
- </li>
- <li>
- <a href='branding.html'>Incubator Branding Guide</a>
- </li>
- </ul>
- </section>
- <section id='release-legal-audit'><title>License Audit</title>
- <p>
-Incubator policy <a href="&root-path;/incubation/Incubation_Policy.html#Releases">requires</a> 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.
- </p>
- <p>
- 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
- <a href='http://www.apache.org/legal/3party.html'>Apache policy</a>.
- The release build also needs to be check
- to ensure that the LICENSE and NOTICE files are included in every released artifact.
- </p>
- <p>
- See:
- </p>
- <ul>
- <li><a href='http://www.apache.org/legal/src-headers.html'>Header for source files</a></li>
- <li><a href='http://www.apache.org/legal/3party.html'>Policy for dependencies</a></li>
- <li><a href='http://www.apache.org/dev/release.html'>Release policy and FAQ</a></li>
- </ul>
- </section>
- </section>
- <section id='release-guidelines'><title>Release Guidelines</title>
- <p>
-In addition to policy, the infrastructure, public relations and legal teams also document "guidelines" for projects:
-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.
- </p>
- <p>
-Guidelines change much more frequently than policy. Release managers should follow the appropriate
-lists. Subscribe to:
- </p>
- <ul>
- <li><em>legal-discuss</em> for matters related to licensing</li>
- <li><em>infrastructure-issues</em> for matters related to </li>
- </ul>
- </section>
- <section id='best-practice'><title>Best Practice</title>
- <section id='best-practice-preparation'><title>Preparation</title>
- <p>
-Preparation is the key to quality. The <a href='http://www.apache.org/foundation/glossary.html#ReleaseManager'>release
-manager</a> will need to organise and coordinate this but need not execute all.
- </p>
- <ul>
- <li>Analyze <a href='#best-practice-prepare-documentation'>bugs</a></li>
- <li>Check <a href='#best-practice-prepare-documentation'>documentation</a></li>
- </ul>
- </section>
- <section id='best-practice-bugs'><title>Bugs</title>
- <p>
-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.
- </p>
- <p>
-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.
- </p>
- </section>
- <section id='best-practice-prepare-documentation'><title>Preparing Documentation</title>
- <p>
-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.
- </p>
- </section>
- <section id='best-practice-naming'><title>Artifact Naming</title>
- <p>
- TODO: should include apache in the title (gives trademark protection against different jars
- with the same name)
- </p>
- </section>
- <section id='best-practice-types'><title>Package Types</title>
- <p>
- TODO: glossary - distribution type: based on the same tagged source built
- TODO: Common Types of distribution
- </p>
- <p>
- 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.
- </p>
- <p>
- All types of packages ship as <a href='best-practice-formats'>compressed artifacts</a>.
- This means multiple packages may be shipped as various compressed artifacts (eg tar.gz and .zip).
- </p>
- </section>
- <section id='best-practice-downstream'><title>Downstream Packagers</title>
- <p>
- 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
- </p>
- <p>
-TODO: write up gentoo wiki on good upstream. google for other distros.
- </p>
- </section>
- <section id='best-practice-source'><title>Source Package</title>
- <p>
- TODO: describe what a source package is; version control for source packages;
- add content to release documents; export not checkout
- </p>
- <p>
- 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:
- </p>
- <ul>
- <li>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.
- </li>
- <li>
-Source packages encourage developers to modify the code base. Recruiting
-new developers is vital for the long term health of an Apache project.
- </li>
- </ul>
- <p>
-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.
- </p>
- </section>
- <section id='best-practice-binary'><title>Binary Package</title>
- <p>
-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.
- </p>
- </section>
- <section id='best-practice-documentation'><title>Release Documentation</title>
- <p>
-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 <a href='#best-practice-types'>types of packages</a>
-including source packages.
-So the master documents should be checked into the base subversion directory.
- </p>
- <p>
-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 build tool 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.
- </p>
- <p>
-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.
- </p>
- <p>
- RELEASE_NOTES (TODO:link). Remember to include a description of the project.
- CHANGES (link) these may be contained in a separate document
- 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.
- </p>
- <p>
- 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)
- </p>
- </section>
- <section id='best-practice-license'><title>LICENSE and NOTICE</title>
- <p>
-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
-<a href='http://www.apache.org/legal/resolved.html'>3rd party licensing policy</a>.
- </p>
- <p>
-All the licenses on all the files to be included within a package
-should be included in the LICENSE document. This <a href='examples/LICENSE'>LICENSE</a>
-(courtesy of <a href='http://httpd.apache.org'>Apache HTTPD</a>) 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.
- </p>
+ <title>Status</title>
<p>
-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 <a href="http://www.apache.org/legal/src-headers.html#notice">
-this document</a> for the typical example.
+ This document is considered complete, and may be revised at a later point.
</p>
- </section>
- <section id='best-practice-audit'><title>Legal Audit</title>
- <p>
- 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.
- </p>
- </section>
- <section id='best-practice-formats'><title>Compression Formats</title>
- <p>
-<a href='best-practice-packages'>Packages</a> of all
-<a href='best-practice-types'>types</a> should be shipped in a compress format
-to minimize bandwidth requirements.
- </p><p>
-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
-<a href='notes-on-compression-formats'>this</a>).
-Ship zip for windows.
- </p><p>
-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, <code>zip</code> with <code>windows</code> and <code>tar.gz</code>
-with <code>UNIX</code> and <code>linux</code>.
-Users often expect this association.
-See <a href='notes-line-endings'>notes</a> on line endings for source packages.
- </p>
- <p>
-Different <a href='#best-practice-types'>package types</a> should unpack to
-directories with different names. This is more convenient for users since:
- </p>
- <ul>
- <li>users who download more than one type do not need to
- take action to ensure that unpacked packages do not overwrite each other</li>
- <li>it allows easy identification of different package types</li>
- </ul>
- <p>
-For project, <em>Apache Foo x.y.z</em> (say) with source and binary types, it is conventional
-for the main binary to unpack to <code>apache-foo-x.y.x</code> and the source to
-<code>apache-foo-x-y.z-src</code>. Other binary types should unpack to suitably suffixed
-directories (for example, <code>apache-foo-x.y.z-sdk</code>).
- </p>
- <p>
-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.
- </p>
- </section>
- <section id='best-practice-source-build'><title>Source Package Build</title>
- <p>
-This section applies only to compiled languages.
- </p>
- <p>
-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.
- </p>
- </section>
- <section id='best-practice-dependencies'><title>Dependencies</title>
- <p>
-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.
- </p>
- <p>
-dependencies should comply with the current apache policy. TODO: link
- </p>
- <p>
-TODO: dependencies also include the tools required to build and test the source.
-to dependencies are often included in BUILDING or README
- </p>
- <p>
-TODO: particularly important for languages. language should be approached
-as dependencies and documented. these should be listed in the README
-or RELEASE NOTEs.
- </p>
- <p>
-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.
- </p>
- </section>
- <section id='best-practice-distributing-libraries'><title>Distributing Libraries</title>
- <p>
-TODO: ASF policy compliance
-TODO: project policy - explicit policy should be written down
- </p>
- </section>
-
- <section id='best-practice-notice'><title>NOTICE files</title>
- <p>
-Read <a href='http://apache.org/legal/src-headers.html#notice'>this</a>.
-The <code>NOTICE</code> is important and serves several purposes.
-The contents should be included in all downstream redistributions.
- </p>
- <p>
-The <code>NOTICE</code> documents copyright notices and other required attributions.
-This must include:
- </p>
- <ul>
- <li>the
-<a href='http://apache.org/legal/src-headers.html#notice'>standard Apache attribution and copyright notice</a></li>
- <li>
-<a href='http://apache.org/legal/src-headers.html#header-existingcopyright'>inherited</a>
- copyright and attributions notices</li>
- <li>all attribution and copyright notices required by licenses for
- <a href='http://apache.org/legal/src-headers.html#3party'>third party documents</a></li>
- </ul>
- <p>
-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 <a
-href='http://www.apache.org/foundation/glossary.html#PMC'>PMC</a>. Apache holds the copyright
-to the collective work that is the release. The Apache copyright in the <code>NOTICE</code>
-pertains to the collective.
- </p>
- <p>
-It is strongly recommended that the <code>NOTICE</code> contains only these legally
-important contents. The <a href='#notes-disclaimer'>incubator disclaimer</a> is best placed in
-another document.
- </p>
- <p>
-The exact name may be optionally suffixed. For example, both <code>NOTICE</code>
-and <code>NOTICE.txt</code> are fine.
- </p>
- </section>
- <section id='best-practices-svn'><title>Subversion Best Practices</title>
- <p>
- TODO: svn is flexible. branches and tags with svn are not the same as with cvs.
- </p>
- <p>
-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.
- </p>
- <p>
-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.
- </p>
- <p>
-If <code>svn:externals</code> 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 <code>svn:externals</code>
-changes then the release will no longer be complete reproducible.
- </p>
- </section>
- <section id='best-practices-git-maven'><title>Git with Maven Best Practices</title>
- <p>
-First and important: configure the maven-release-plugin to operate 'locally'
-<a href="https://github.com/apache/deltaspike/blob/master/pom.xml#L123">https://github.com/apache/deltaspike/blob/master/pom.xml#L123</a>
- </p>
- <p>
-The important parts are:
- </p>
-<source>
-<pushChanges>false</pushChanges>
+ </section>
-<localCheckout>true</localCheckout>
-</source>
- <p>
-This will configure maven to NOT push you changes upstream to the repo mentioned in the SCM section, but only keep it local.
-And during the release:perform this will also pick up the tag from local.
-That means you need to push it to e.g. github yourself.
- </p>
- </section>
- <section id='best-practice-reproducability'><title>Reproducibility</title>
- <p>
-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.
- </p><p>
-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.
- </p><p>
-The requirements of the build should be fully documented. The versions of tools
-and platforms used to build the release should be noted.
- </p>
- <p>
-The following are examples of how existing ASF projects have documented their release
-process.
- </p>
- <ul>
- <li><a href="https://sling.apache.org/documentation/development/release-management.html">Apache Sling</a></li>
- <li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Building+the+Tomcat+Native+Connector+binaries+for+Windows">Apache Tomcat Native Connectors</a></li>
- <li><a href="https://deltaspike.apache.org/steps_for_a_release.html">Apache DeltaSpike</a></li>
- <li><a href="https://github.com/apache/wicket/blob/master/release.sh">Apache Wicket release script</a></li>
- <li><a href="https://s.apache.org/accumulo-build-script">Apache Accumulo build script</a></li>
- <li><a href="https://cwiki.apache.org/confluence/display/GEODE/Release+Steps">Apache Geode release process</a></li>
- </ul>
-
- </section>
- <section id='best-practice-release-as-advertising'><title>Release As Advertising</title>
- <p>
-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)
- </p>
- </section>
- <section id='best-practice-dependencies'><title>Dependencies</title>
- <p>
-As well as libraries, projects often have more subtle dependencies.
-Most languages have different versions, and it is important that the versions
-of a language upon which a project will build and run are clearly documented.
-The <a href='TODO:'>release notes</a>
-are a typical location for this information.
- </p>
- <p>
-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.
- </p>
- <p>
-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 <a href='TODO:'>paperwork</a>.
- </p>
- </section>
- <section id='announcements'><title>Announcements</title>
- <p>
-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
- </p>
- <p>
-Please ensure that release announcements include a brief description of the product near the start of the text.
-Although readers on the developer and user lists will presumably know what the product does,
-it's unlikely that other readers will have much idea.
-Don't force recipients to read the product website merely to find out whether the software is
-of interest to them.
- </p>
- <p>
-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.
- </p>
- <p>
-Announcements should be posted from the release manager's
-<code>apache.org</code> address.
- </p>
- </section>
- <section id='best-practice-incubator-release-vote'><title>Incubator Release Vote</title>
- <p>
-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.
- </p>
- <p>
-The release manager should post the call for the VOTE.
- </p>
- <ul>
- <li>Links to the release artifacts</li>
- <li>Links to the PPMC release vote thread</li>
- <li>Link to the tag from which the release is cut</li>
- </ul>
- </section>
- <section id='best-practice-mailing-lists'><title></title>
- <p>
-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.
- </p>
- <ul>
- <li>TODO: link General infrastructure list</li>
- <li>TODO: link Legal discuss list</li>
- </ul>
- <p>
-Release managers for incubating podlings should also subscribe to the TODO: link general list.
- </p>
- </section>
- <section id='best-practices-release-candidates'><title>Release Candidates</title>
- <p>
-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.
- </p>
- <p>
-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.
- </p>
- <p>
-Those projects which have release candidates will vote on a sample release candidate.
- </p>
- <p>
-Only formally-approved releases may be distributed from the main directories.
-There are a number of reasons for this:
- </p>
- <ul>
- <li>the URL indicates the status of the release</li>
- <li>the main directory is archived for historical purposes. To conserve space
- only official release should be archived.</li>
- <li>syncing too many short lived artifacts use bandwidth</li>
- </ul>
- <p>
-TODO: links to infra dev
- </p>
- <p>
-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.
- </p>
- </section>
- <section id='signing-releases'><title>Signatures</title>
- <p>
- TODO: links to release signing documentation
- </p>
- <p>
- 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.
- </p>
- <p>
- Novice signers should read the documentation and practice. Consider using an
- isolated installation to store the code signing key and to sign releases.
- </p>
- </section>
- </section>
- <section id='notes'><title>Notes</title>
- <section id='notes-on-licenses'><title>License Issues</title>
- <p>
- 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
- </p>
- </section>
- <section id='notes-disclaimer'><title>The Incubator Disclaimer</title>
- <p>
- 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
- </p>
- </section>
- <section id='best-practice-release-candidate'><title>Release Candidates</title>
- <p>
-There are two distinct approaches: <a href='http://www.apache.org/foundation/glossary.html#ReleaseCandidate'>release
-candidate</a> and TODO.
- </p>
- </section>
- <section id='best-practice-versioning'><title>Versioning</title>
- <p>
-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.
- </p>
- <p>
- TODO: notes on strategies.
- </p>
- <p>
- The most common system of versioning is based on <code>major.minor.point</code>
- 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.
- </p>
- <p>
- 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.
- </p><p>
- TODO: (move to a note) Notes on 0.x releases verses alpha and betas. It is better to use <code>0.x</code>
- 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.
- </p>
- </section>
- <section id='notes-numbering-between-releases'><title>Version Numbering Between Releases</title>
- <p>
-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.
- </p>
- <p>
-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).
- </p>
- <p>
-TODO: odd, even version numbers - research httpd, linux
- </p>
- <p>
-<code>SNAPSHOT</code> and <code>dev</code> are commonly used suffixes.
-Typically these are set to the next minor version number in sequence. For example,
-after cutting <code>apache-foo-1.5.6</code>, the version would be
-<code>1.6</code>.
- </p>
- </section>
- <section id='best-practice-unique-names'><title>Unique Artifact Names</title>
- <p>
- Every <a href='glossay-artifact'>artifact</a> 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 <em>apache</em> 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.
- </p>
- <p>
-For each product, each <a href='best-practice-types'>type of package</a> should be
-assigned a consistent and unique name. Conventionally, source packages use <code>src</code>
-and main binary packages no prefix. Typically each type of package is made available in a number of
-<a href='best-practice-formats'>compression formats</a>. These are conventionally distinguished
-by the usual file type suffix.
- </p>
- <p>
-So, the traditional format is apache-project-product-type-version.format.
- </p>
- </section>
- <section id='release-notes'><title>Release Notes</title>
- <p>
-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
- </p>
- <p>
-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.
- </p>
- <p>
-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.
- </p>
- <p>
-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.
- </p>
- <p>
-The content can often be edit for use in the announcement.
- </p>
- <p>
-TODO: move to best practice?
- </p>
- <p>
-TODO: contents
-include a short description of the project and links to the apache site
- </p>
- <p>
-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.
- </p>
- <p>
-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.
- </p>
- <p>
-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.
- </p>
- <p>
-Any changes which may effect a user who wishes to replace the last version with
-this should be highlighted. In particular, document:
- </p>
- <ul>
- <li>Deprecations</li>
- <li>Binary incompatibilities</li>
- <li>Semantic incompatibilities (TODO: glossary)</li>
- </ul>
- <p>
-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.
- </p>
- <p>
- 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.
- </p>
- <p>
-Remember that a user may have received the software indirectly. So, include
-some brief details about the project and an url.
- </p>
- <p>
-Release notes are important TODO: glossary guerrilla advertising for a project.
-They should provide:
- </p>
- <ul>
- <li>an introduction for those who don't know the project in
-detail</li>
- <li>briefly state the aims of the project</li>
- <li>briefly indicate the project's roadmap and how this release fits into it</li>
- <li>list ways to get involved with the project</li>
- <li>describe how to raise issues</li>
- </ul>
- <p>
-This may be included by reference to the main documentation
-but (for the benefit of those that don't read document) should be mentioned.
- </p>
- </section>
- <section id='notes-change-log'><title>Change Logs</title>
- <p>
-TODO: should this be in best practices
-TODO: add examples
- </p>
- <p>
-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 <code>ChangeLog</code>.
- </p>
- <p>
-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)
- </p>
- <p>
-The change log typically includes every feature added and every bug resolved since
-the last release.
- </p>
- </section>
- <section id='notes-signing-releases'><title>Signing Releases</title>
- <p>
-TODO: links to dev pages
-batch signing scripts in committers
- </p>
- <p>
-TODO: consider moving content into foundation docs
- </p>
- <p>
-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
- </p><p>
- What can be sometimes confusing is that though a signature is required,
- connection to the web of trust is only strongly encouraged not required.
- </p><p>
- A signature from a key which is well
- connected to the Apache web of trust gives greater security than a signature
- that is not.
- </p><p>
- 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.
- </p>
- </section>
- <section id='note-on-multiple-products'><title>On Multiple Products</title>
- <p>
-A project may release a number of distinct products created by the same community.
-TODO: differences between products and packages.
- </p>
- </section>
- <section id='notes-on-templates'><title>On Template Sources</title>
- <p>
- TODO: this is probably a best practice
- </p>
- <p>
-Source files should contain the license header whenever this is reasonable.
-Templates are source documents and so this principle applies to them as well.
- </p>
- <p>
-If these templates are used to generate documents which form part of the
-package then the documents generated should contain the license header.
- </p>
- <p>
-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.
- </p>
- </section>
- <section id='notes-on-export-regulations'><title>On Export Regulations</title>
- <p>
-TODO preamble TODO link to legal
- </p>
- </section>
- <section id='notes-on-compression-formats'><title></title>
- TODO: discuss merits tgz, bz, bz2
- TODO: problems with incompatibilities with different version of some utilities
- </section>
- <section id='notes-on-line-endings'><title>On Line Endings</title>
- <p>
-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
-<a href='#best-practice-formats'>compression format</a> (<code>CRLF</code>
-for the <code>zip</code> and <code>LF</code> for the <code>tar.gz</code>).
- </p>
- <p>
-Source packages can use <code>svn export --native-es</code>.
- </p>
- </section>
- <section id='notes-press-releases'><title>On Press Releases</title>
- <p>
-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.
- </p>
- <p>
-TODO: link to public relations committee
- </p>
- </section>
- <section id='notes-license-headers'><title>On License Headers</title>
- <p>
- TODO: links into legal documentation. discuss issues about which files need to apply.
- </p>
- <p>
- 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.
- </p>
- <p>
- TODO: to
- </p>
- <p>
-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.
- </p>
- <p>
-TODO: check with legal-discuss then move this content into the legal pages and link with commentary
- </p>
- <p>
-TODO: link into provenance
- </p>
- </section>
- <section id='code-provenance'><title>Code Provenance</title>
- <p>
-<a href='LINK'>License headers</a> 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.
- </p>
- <p>
-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, the issue should be noted in the commit message.
- </p>
- <p>
-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.
- </p>
- <p>
-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.
- </p>
- </section>
- <section id='note-standards'><title>Implementations Of Standards</title>
- <p>
-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
- </p>
- </section>
- <section id='note-license-and-notice'><title>Understanding Content For NOTICE and LICENSE</title>
- <p>
-
- </p>
- <p>
-The <a href='http://www.apache.org/licenses/LICENSE-2.0.txt'>Apache License, Version 2</a>
-clause 4d states:
- </p>
- <blockquote cite='http://www.apache.org/licenses/LICENSE-2.0.txt'>
- 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.
- </blockquote>
- <p>
-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.
- </p>
- <p>
- 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.
- </p>
- <p>
- For example (taken from <a href='http://jdbm.sourceforge.net'>JDBM</a>)
- this <a href='example/JDBM.LICENSE'>license</a>. The form of this license is similar to the
- <a href='http://www.apache.org/licenses/LICENSE-1.0.txt'>Apache License, Version 1.0</a>.
- Clause 5 states:
- </p>
- <blockquote cite='example/JDBM.LICENSE'>
- 5. Due credit should be given to the JDBM Project
- (http://jdbm.sourceforge.net/).
- </blockquote>
- <p>
- 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
- <em>This product includes software developed by The JDBM Project
- (http://jdbm.sourceforge.net/).</em>) should be appended to the NOTICE
- document.
- </p>
- <p>
-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.
- </p>
- </section>
- <section id='note-votes'><title>VOTEs</title>
- <p>
- TODO: add bill's excellent quote (apologies for the pun)
- </p>
- <p>
- Apache releases are high ceremony. A number of formal VOTEs binding upon Apache
- are required before an release of any type.
- </p>
- <p>
-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 <code>VOTE</code> directories by using this prefix.
- </p>
- <p>
-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
-<a href='http://mail-archives.apache.org/mod_mbox/incubator-general/200607.mbox/%3cf470f68e0607290244jed7d32al2a3e6b3db5fd863d@mail.gmail.com%3e'>
-example</a>.
- </p>
- <p>
-Stating the process for the VOTE (for example, minimum duration) in the preamble
-allows anyone who objects to the process to register this immediately.
- </p>
- <p>
-It is conventional to end a <code>VOTE</code> thread with a <code>RESULT</code>
-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
-<a href='http://mail-archives.apache.org/mod_mbox/incubator-general/200605.mbox/%3c5BDE9EBE-2645-4940-9CB9-C038E531B8A2@gmail.com%3e'>
-example</a>.
- </p>
- <p>
-Be careful to check the voters against the appropriate list. Binding votes are cast by people on the
-appropriate committee. The list of Incubator PMC members is
-<a href='https://people.apache.org/phonebook.html?pmc=incubator'>available</a>.
- </p>
- <p>
-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.
- </p>
[... 134 lines stripped ...]
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@incubator.apache.org
For additional commands, e-mail: cvs-help@incubator.apache.org