Google Git
Sign in
apache / incubator / 766f9906a15ef7548ed922f90c5412e569afbd64 / . / bob / guides / releasemanagement.html
blob: bd097cf49125a02b2748f87688051d727bddabf9 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" href="../style/bootstrap-1-3-0-min.css" type="text/css" />
<link rel="stylesheet" href="../style/style.css" type="text/css" />
<link rel="alternate" title="general@incubator.apache.org Archives" type="application/atom+xml" href="http://mail-archives.apache.org/mod_mbox/incubator-general/?format=atom" />
<title>Apache Incubator: Release Management (DRAFT) - Apache Incubator</title>
</head>
<body>
<div class="container">
<div class="row">
<div class="span12">
<a href="http://www.apache.org/"><img src="http://incubator.apache.org/images/asf_logo_wide_small.png" alt="The Apache Software Foundation" border="0" style="margin-top: 2px" width="62%"/></a>
</div>
<div class="span4">
<a href="http://incubator.apache.org/"><img src="../images/egg-logo2.png" alt="Apache Incubator" border="0"/></a>
</div>
</div>
<div class="row"><div class="span16"><hr noshade="noshade" size="1"/></div></div>
<div class="row">
<div class="span4">
<form action="http://www.google.com/search" method="get">
<input value="incubator.apache.org" name="sitesearch" type="hidden"/>
<input size="20" name="q" id="query" type="text" value="search..."
onclick="if(this.value == 'search...') {this.value = ''}"/>
<input name="Search" value="Go" type="submit"/>
</form>
<div class="menuheader">General</div>
<menu compact="compact">
<li><a href="../index.html">Welcome</a></li>
<li><a href="../incubation/Process_Description.html">Incubation Overview</a></li>
<li><a href="../incubation/Incubation_Policy.html">Incubation Policy</a></li>
<li><a href="../guides/index.html">Incubation Guides</a></li>
<li><a href="../incubation/Roles_and_Responsibilities.html">Roles and Responsibilities</a></li>
<li><a href="../faq.html">General FAQ</a></li>
<li><a href="http://wiki.apache.org/incubator">Incubator Wiki</a></li>
<li><a href="../whoweare.html">Who We Are</a></li>
<li><a href="../sitemap.html">Site Map</a></li>
</menu>
<div class="menuheader">Status</div>
<menu compact="compact">
<li><a href="../projects/index.html">Project List</a></li>
<li><a href="../clutch.html">Clutch Report</a></li>
<li><a href="../ip-clearance/index.html">IP Clearance</a></li>
<li><a href="../history/index.html">Incubator History</a></li>
</menu>
<div class="menuheader">Entry Guides</div>
<menu compact="compact">
<li><a href="../guides/proposal.html">Proposal Guide</a></li>
</menu>
<div class="menuheader">Podling Guides</div>
<menu compact="compact">
<li><a href="../guides/committer.html">Podling Committers</a></li>
<li><a href="../guides/ppmc.html">Podling PMC (PPMC)</a></li>
<li><a href="../guides/mentor.html">Podling Mentor</a></li>
<li><a href="../guides/releasemanagement.html">Podling Releases</a></li>
<li><a href="../guides/branding.html">Podling Branding/Publicity</a></li>
<li><a href="../guides/sites.html">Podling Websites</a></li>
<li><a href="../guides/graduation.html">Graduation</a></li>
<li><a href="../guides/retirement.html">Retirement</a></li>
</menu>
<div class="menuheader">Other Guides</div>
<menu compact="compact">
<li><a href="../guides/participation.html">Participation</a></li>
<li><a href="../faq.html">General FAQ</a></li>
<li><a href="../guides/pmc.html">Incubator PMC (IPMC)</a></li>
<li><a href="../guides/chair.html">IPMC Chair</a></li>
<li><a href="../guides/lists.html">Mailing Lists</a></li>
<li><a href="../guides/website.html">Incubator Website</a></li>
</menu>
<div class="menuheader">ASF</div>
<menu compact="compact">
<li><a href="http://www.apache.org/foundation/how-it-works.html">How Apache Works</a></li>
<li><a href="http://www.apache.org/dev/">Developer Documentation</a></li>
<li><a href="http://www.apache.org/foundation/">Foundation</a></li>
<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsor Apache</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
</menu>
<!-- start Ads Server -->
<iframe src="http://www.apache.org/ads/buttonbar.html"
style="border-width:0; float: left" frameborder="0" scrolling="no"
width="135" height="265"></iframe>
<!-- end Ads Server -->
</div>
<div class="span12">
<h2 id='intro'><img src="../images/redarrow.gif" />A Guide To Release Management During Incubation (DRAFT)</h2>
<div class="section-content">
<h3 id='TOC'>Contents</h3>
<div class="section-content">
<ul>
<li><a href='#intro'>
A Guide To Release Management During Incubation (DRAFT)
</a>
<ul>
<li><a href='#TOC'>
Contents
</a>
</li>
<li><a href='#status'>
Status - DRAFT
</a>
</li>
<li><a href='#abstract'>
Abstract
</a>
</li>
</ul>
</li>
<li><a href='#references'>
References
</a>
<ul>
<li><a href='#subpages'>
See Also
</a>
<ul>
<li><a href='#java-subpage'>
Java-specific Release Management Issues
</a>
</li>
</ul>
</li>
</ul>
</li>
<li><a href='#check-list'>
Release Check List
</a>
</li>
<li><a href='#guidelines'>
Guidelines
</a>
</li>
<li><a href='#release-distribution'>
Distributing Releases
</a>
<ul>
<li><a href='#glossary-incubator-dist'>
Incubator Distribution Directory
</a>
</li>
<li><a href='#glossary-podling-dist'>
Podling Distribution Directory
</a>
</li>
<li><a href='#distribution-policy-overview'>
Policy Overview
</a>
</li>
<li><a href='#understanding-distribution'>
Understanding Release Distribution
</a>
<ul>
<li><a href='#understanding-upload'>
Uploading Artifacts
</a>
</li>
<li><a href='#understanding-mirroring'>
Mirroring
</a>
</li>
<li><a href='#understanding-archiving'>
Archiving
</a>
</li>
<li><a href='#understanding-security'>
Security
</a>
<ul>
<li><a href='#distribution-checksums-sigs'>
Sums And Signatures
</a>
</li>
<li><a href='#distribution-modifications'>
Modifications
</a>
</li>
</ul>
</li>
</ul>
</li>
<li><a href='#distribution-check-list'>
Distribution Check List
</a>
</li>
<li><a href='#distribution-best-practice'>
Best Practice
</a>
<ul>
<li><a href='#distribution-layout'>
Layout
</a>
<ul>
<li><a href='#distribution-layout-plain'>
Plain Artifacts
</a>
</li>
<li><a href='#distribution-layout-misc'>
Miscellaneous Documents
</a>
</li>
<li><a href='#distribution-layout-structured'>
A Structured Layout
</a>
</li>
</ul>
</li>
<li><a href='#distribution-release-documentation'>
Release Documentation
</a>
</li>
<li><a href='#archiving-old-releases'>
Archiving Old Releases
</a>
</li>
<li><a href='#distribution-mirroring'>
Mirroring Scripts
</a>
</li>
<li><a href='#distribution-signing'>
Signatures
</a>
</li>
<li><a href='#distribution-defects'>
Dealing With A Defect
</a>
</li>
</ul>
</li>
</ul>
</li>
<li><a href='#rules'>
Rules
</a>
<ul>
<li><a href='#signing'>
Signing
</a>
</li>
<li><a href='#naming'>
Naming
</a>
</li>
<li><a href='#release-legal-audit'>
License Audit
</a>
</li>
</ul>
</li>
<li><a href='#release-guidelines'>
Release Guidelines
</a>
</li>
<li><a href='#best-practice'>
Best Practice
</a>
<ul>
<li><a href='#best-practice-preparation'>
Preparation
</a>
</li>
<li><a href='#best-practice-bugs'>
Bugs
</a>
</li>
<li><a href='#best-practice-prepare-documentation'>
Preparing Documentation
</a>
</li>
<li><a href='#best-practice-naming'>
Artifact Naming
</a>
</li>
<li><a href='#best-practice-types'>
Package Types
</a>
</li>
<li><a href='#best-practice-downstream'>
Downstream Packagers
</a>
</li>
<li><a href='#best-practice-source'>
Source Package
</a>
</li>
<li><a href='#best-practice-binary'>
Binary Package
</a>
</li>
<li><a href='#best-practice-documentation'>
Release Documentation
</a>
</li>
<li><a href='#best-practice-license'>
LICENSE and NOTICE
</a>
</li>
<li><a href='#best-practice-audit'>
Legal Audit
</a>
</li>
<li><a href='#best-practice-formats'>
Compression Formats
</a>
</li>
<li><a href='#best-practice-source-build'>
Source Package Build
</a>
</li>
<li><a href='#best-practice-dependencies'>
Dependencies
</a>
</li>
<li><a href='#best-practice-distributing-libraries'>
Distributing Libraries
</a>
</li>
<li><a href='#best-practice-notice'>
NOTICE files
</a>
</li>
<li><a href='#best-practices-svn'>
Subversion Best Practices
</a>
</li>
<li><a href='#best-practices-git-maven'>
Git with Maven Best Practices
</a>
</li>
<li><a href='#best-practice-reproducability'>
Reproducibility
</a>
</li>
<li><a href='#best-practice-release-as-advertising'>
Release As Advertising
</a>
</li>
<li><a href='#best-practice-dependencies'>
Dependencies
</a>
</li>
<li><a href='#announcements'>
Announcements
</a>
</li>
<li><a href='#best-practice-incubator-release-vote'>
Incubator Release Vote
</a>
</li>
<li><a href='#best-practice-mailing-lists'>
</a>
</li>
<li><a href='#best-practices-release-candidates'>
Release Candidates
</a>
</li>
<li><a href='#signing-releases'>
Signatures
</a>
</li>
</ul>
</li>
<li><a href='#notes'>
Notes
</a>
<ul>
<li><a href='#notes-on-licenses'>
License Issues
</a>
</li>
<li><a href='#notes-disclaimer'>
The Incubator Disclaimer
</a>
</li>
<li><a href='#best-practice-release-candidate'>
Release Candidates
</a>
</li>
<li><a href='#best-practice-versioning'>
Versioning
</a>
</li>
<li><a href='#notes-numbering-between-releases'>
Version Numbering Between Releases
</a>
</li>
<li><a href='#best-practice-unique-names'>
Unique Artifact Names
</a>
</li>
<li><a href='#release-notes'>
Release Notes
</a>
</li>
<li><a href='#notes-change-log'>
Change Logs
</a>
</li>
<li><a href='#notes-signing-releases'>
Signing Releases
</a>
</li>
<li><a href='#note-on-multiple-products'>
On Multiple Products
</a>
</li>
<li><a href='#notes-on-templates'>
On Template Sources
</a>
</li>
<li><a href='#notes-on-export-regulations'>
On Export Regulations
</a>
</li>
<li><a href='#notes-on-compression-formats'>
</a>
</li>
<li><a href='#notes-on-line-endings'>
On Line Endings
</a>
</li>
<li><a href='#notes-press-releases'>
On Press Releases
</a>
</li>
<li><a href='#notes-license-headers'>
On License Headers
</a>
</li>
<li><a href='#code-provenance'>
Code Provenance
</a>
</li>
<li><a href='#note-standards'>
Implementations Of Standards
</a>
</li>
<li><a href='#note-license-and-notice'>
Understanding Content For NOTICE and LICENSE
</a>
</li>
<li><a href='#note-votes'>
VOTEs
</a>
<ul>
<li><a href='#note-pmc-vote'>
</a>
</li>
</ul>
</li>
<li><a href='#notes-revote'>
On Managing VOTE Threads
</a>
</li>
<li><a href='#notes-on-gnu-tar'>
GNU Tar Known Incompatibilities
</a>
</li>
<li><a href='#notes-on-source-only-releases'>
On Source-Only Releases
</a>
</li>
<li><a href='#notes-on-binary-only-releases'>
On Binary-Only Releases
</a>
</li>
</ul>
</li>
</ul>
</div>
<h3 id='status'>Status - DRAFT</h3>
<div class="section-content">
<p>
This document is under active <a href="#help-wanted">development</a>. This is a first
draft intended to allow public review.
</p>
</div>
<a id="organisation" />
<a id="usage" />
<a id="apache-releases" />
<h3 id='abstract'>Abstract</h3>
<div class="section-content">
<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>
</div>
</div>
<h2 id='references'><img src="../images/redarrow.gif" />References</h2>
<div class="section-content">
<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>
<h3 id='subpages'>See Also</h3>
<div class="section-content">
<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>
<h4 id='java-subpage'>Java-specific Release Management Issues</h4>
<div class="section-content">
<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>
</div>
</div>
</div>
<h2 id='check-list'><img src="../images/redarrow.gif" />Release Check List</h2>
<div class="section-content">
<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>
</div>
<h2 id='guidelines'><img src="../images/redarrow.gif" />Guidelines</h2>
<div class="section-content">
</div>
<h2 id='release-distribution'><img src="../images/redarrow.gif" />Distributing Releases</h2>
<div class="section-content">
<p>
Once a release has been approved by the
<a href="../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>
<h3 id='glossary-incubator-dist'>Incubator Distribution Directory</h3>
<div class="section-content">
<p>
All Incubator authorised by the incubator are contained within the
Incubator distribution directory:
</p>
<div class="source"><code>
https://dist.apache.org/repos/dist/release/incubator
</code>
</div>
</div>
<h3 id='glossary-podling-dist'>Podling Distribution Directory</h3>
<div class="section-content">
<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>
</div>
<h3 id='distribution-policy-overview'>Policy Overview</h3>
<div class="section-content">
<p>
Distribution policy with regard to releases is simple:
</p>
<ul>
<li>
The Incubator
<a href="../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>
</div>
<a id="distribution-permissions" />
<h3 id='understanding-distribution'>Understanding Release Distribution</h3>
<div class="section-content">
<h4 id='understanding-upload'>Uploading Artifacts</h4>
<div class="section-content">
<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>
</div>
<h4 id='understanding-mirroring'>Mirroring</h4>
<div class="section-content">
<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>
</div>
<h4 id='understanding-archiving'>Archiving</h4>
<div class="section-content">
<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 />
<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>
</div>
<h4 id='understanding-security'>Security</h4>
<div class="section-content">
<h5 id='distribution-checksums-sigs'>Sums And Signatures</h5>
<div class="section-content">
<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>
</div>
<h5 id='distribution-modifications'>Modifications</h5>
<div class="section-content">
<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>
</div>
</div>
</div>
<h3 id='distribution-check-list'>Distribution Check List</h3>
<div class="section-content">
<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>
</div>
<h3 id='distribution-best-practice'>Best Practice</h3>
<div class="section-content">
<h4 id='distribution-layout'>Layout</h4>
<div class="section-content">
<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>
<h5 id='distribution-layout-plain'>Plain Artifacts</h5>
<div class="section-content">
<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>
</div>
<h5 id='distribution-layout-misc'>Miscellaneous Documents</h5>
<div class="section-content">
<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>
</div>
<h5 id='distribution-layout-structured'>A Structured Layout</h5>
<div class="section-content">
<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>
</div>
</div>
<h4 id='distribution-release-documentation'>Release Documentation</h4>
<div class="section-content">
<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>
</div>
<h4 id='archiving-old-releases'>Archiving Old Releases</h4>
<div class="section-content">
<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>
</div>
<h4 id='distribution-mirroring'>Mirroring Scripts</h4>
<div class="section-content">
<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>
</div>
<h4 id='distribution-signing'>Signatures</h4>
<div class="section-content">
<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>
</div>
<h4 id='distribution-defects'>Dealing With A Defect</h4>
<div class="section-content">
<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>
</div>
</div>
</div>
<h2 id='rules'><img src="../images/redarrow.gif" />Rules</h2>
<div class="section-content">
<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>
<h3 id='signing'>Signing</h3>
<div class="section-content">
<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>
</div>
<h3 id='naming'>Naming</h3>
<div class="section-content">
<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="../incubator/Incubator_Policy.html">Incubator Policy</a>
</li>
<li>
<a href="branding.html">Incubator Branding Guide</a>
</li>
</ul>
</div>
<h3 id='release-legal-audit'>License Audit</h3>
<div class="section-content">
<p>
Incubator policy <a href="../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>
</div>
</div>
<h2 id='release-guidelines'><img src="../images/redarrow.gif" />Release Guidelines</h2>
<div class="section-content">
<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>
</div>
<h2 id='best-practice'><img src="../images/redarrow.gif" />Best Practice</h2>
<div class="section-content">
<h3 id='best-practice-preparation'>Preparation</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-bugs'>Bugs</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-prepare-documentation'>Preparing Documentation</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-naming'>Artifact Naming</h3>
<div class="section-content">
<p>
TODO: should include apache in the title (gives trademark protection against different jars
with the same name)
</p>
</div>
<h3 id='best-practice-types'>Package Types</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-downstream'>Downstream Packagers</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-source'>Source Package</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-binary'>Binary Package</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-documentation'>Release Documentation</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-license'>LICENSE and NOTICE</h3>
<div class="section-content">
<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>
<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.
</p>
</div>
<h3 id='best-practice-audit'>Legal Audit</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-formats'>Compression Formats</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-source-build'>Source Package Build</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-dependencies'>Dependencies</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-distributing-libraries'>Distributing Libraries</h3>
<div class="section-content">
<p>
TODO: ASF policy compliance
TODO: project policy - explicit policy should be written down
</p>
</div>
<h3 id='best-practice-notice'>NOTICE files</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practices-svn'>Subversion Best Practices</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practices-git-maven'>Git with Maven Best Practices</h3>
<div class="section-content">
<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>
<div class="source"><code>
&lt;pushChanges&gt;false&lt;/pushChanges&gt;
&lt;localCheckout&gt;true&lt;/localCheckout&gt;
</code>
</div>
<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>
</div>
<h3 id='best-practice-reproducability'>Reproducibility</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-release-as-advertising'>Release As Advertising</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-dependencies'>Dependencies</h3>
<div class="section-content">
<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>
</div>
<h3 id='announcements'>Announcements</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-incubator-release-vote'>Incubator Release Vote</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-mailing-lists'></h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practices-release-candidates'>Release Candidates</h3>
<div class="section-content">
<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>
</div>
<h3 id='signing-releases'>Signatures</h3>
<div class="section-content">
<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>
</div>
</div>
<h2 id='notes'><img src="../images/redarrow.gif" />Notes</h2>
<div class="section-content">
<h3 id='notes-on-licenses'>License Issues</h3>
<div class="section-content">
<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>
</div>
<h3 id='notes-disclaimer'>The Incubator Disclaimer</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-release-candidate'>Release Candidates</h3>
<div class="section-content">
<p>
There are two distinct approaches: <a href="http://www.apache.org/foundation/glossary.html#ReleaseCandidate">release
candidate</a> and TODO.
</p>
</div>
<h3 id='best-practice-versioning'>Versioning</h3>
<div class="section-content">
<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>
</div>
<h3 id='notes-numbering-between-releases'>Version Numbering Between Releases</h3>
<div class="section-content">
<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>
</div>
<h3 id='best-practice-unique-names'>Unique Artifact Names</h3>
<div class="section-content">
<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>
</div>
<h3 id='release-notes'>Release Notes</h3>
<div class="section-content">
<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>
</div>
<h3 id='notes-change-log'>Change Logs</h3>
<div class="section-content">
<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>
</div>
<h3 id='notes-signing-releases'>Signing Releases</h3>
<div class="section-content">
<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>
</div>
<h3 id='note-on-multiple-products'>On Multiple Products</h3>
<div class="section-content">
<p>
A project may release a number of distinct products created by the same community.
TODO: differences between products and packages.
</p>
</div>
<h3 id='notes-on-templates'>On Template Sources</h3>
<div class="section-content">
<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>
</div>
<h3 id='notes-on-export-regulations'>On Export Regulations</h3>
<div class="section-content">
<p>
TODO preamble TODO link to legal
</p>
</div>
<h3 id='notes-on-compression-formats'></h3>
<div class="section-content">
</div>
<h3 id='notes-on-line-endings'>On Line Endings</h3>
<div class="section-content">
<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>
</div>
<h3 id='notes-press-releases'>On Press Releases</h3>
<div class="section-content">
<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>
</div>
<h3 id='notes-license-headers'>On License Headers</h3>
<div class="section-content">
<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>
</div>
<h3 id='code-provenance'>Code Provenance</h3>
<div class="section-content">
<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>
</div>
<h3 id='note-standards'>Implementations Of Standards</h3>
<div class="section-content">
<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>
</div>
<h3 id='note-license-and-notice'>Understanding Content For NOTICE and LICENSE</h3>
<div class="section-content">
<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>
</div>
<h3 id='note-votes'>VOTEs</h3>
<div class="section-content">
<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="http://people.apache.org/committers-by-project.html#incubator-pmc">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>
<p>
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 <code>[WAS</code> and the d subject.
For example, d subject <code>Re: Whatever</code> may be edited to
<code>New Foo [WAS Re:Whatever]</code>. 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.
</p>
<p>
TODO: move VOTE netiquette into either ppmc or lists and link from here
TODO: this has turned into best practice.
</p>
<h4 id='note-pmc-vote'></h4>
<div class="section-content">
<p>
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.)
</p>
<p>
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.
</p>
</div>
</div>
<h3 id='notes-revote'>On Managing VOTE Threads</h3>
<div class="section-content">
<p>
TODO: consider whether this would be better moved elsewhere
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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).
</p>
</div>
<h3 id='notes-on-gnu-tar'>GNU Tar Known Incompatibilities</h3>
<div class="section-content">
<p>
Typically, applications used to create <code>tar.gz</code> 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
</p>
</div>
<h3 id='notes-on-source-only-releases'>On Source-Only Releases</h3>
<div class="section-content">
<p>
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.
</p>
</div>
<h3 id='notes-on-binary-only-releases'>On Binary-Only Releases</h3>
<div class="section-content">
<p>
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.
</p>
</div>
</div>
</div>
</div>
<div class="row"><div class="span16"><hr noshade="noshade" size="1"/></div></div>
<div class="row">
<div class="span16 footer">
Copyright &#169; 2009-2016 The Apache Software Foundation<br />
Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/>
Apache Incubator, Apache, the Apache feather logo, and the Apache Incubator project logo are trademarks of The Apache Software Foundation.
</div>
</div>
</div>
</body>
</html>