incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anto...@apache.org
Subject svn commit: r468235 [2/3] - /incubator/public/trunk/site-publish/guides/releasemanagement.html
Date Fri, 27 Oct 2006 02:14:14 GMT

Modified: incubator/public/trunk/site-publish/guides/releasemanagement.html
URL: http://svn.apache.org/viewvc/incubator/public/trunk/site-publish/guides/releasemanagement.html?view=diff&rev=468235&r1=468234&r2=468235
==============================================================================
--- incubator/public/trunk/site-publish/guides/releasemanagement.html (original)
+++ incubator/public/trunk/site-publish/guides/releasemanagement.html Thu Oct 26 19:14:14 2006
@@ -1,1562 +1,1562 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!--
-Copyright 1999-2006 The Apache Software Foundation
-Licensed 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>
- <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
-  <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>        
-  <table border="0" width="100%" cellspacing="0">
-   <tr><!-- SITE BANNER AND PROJECT IMAGE -->
-    <td align="left" valign="top">
-<a href="http://www.apache.org/"><img src="/images/asf_logo_wide.gif" alt="The Apache Software Foundation" border="0"/></a>
-</td>
-<td align="right">
-<a href="http://incubator.apache.org/"><img src="../images/apache-incubator-logo.png" alt="Apache Incubator" border="0"/></a>
-</td>
-   </tr>
-  </table>
-  <table border="0" width="100%" cellspacing="4">
-   <tr><td colspan="3"><hr noshade="noshade" size="1"/></td></tr>
-   <tr>
-    <!-- LEFT SIDE NAVIGATION -->
-    <td valign="top" nowrap="nowrap" class="navleft">
-           <div class="menuheader"><a 
-href="http://www.apache.org/foundation/glossary.html#Podling">Podlings (What's that?)</a></div> 
-    <menu compact="compact">
-          <li><a href="/incubation/Incubation_Policy.html">How? (Policy)</a></li> 
-          <li><a href="/incubation/Roles_and_Responsibilities.html">Who? (Roles)</a></li> 
-          <li><a href="/incubation/Process_Description.html">When? (Process)</a></li> 
-            </menu>
-      <div class="menuheader"><a 
-href="/guides/index.html">Entry Guides</a></div> 
-    <menu compact="compact">
-          <li><a href="/guides/proposal.html">Proposal Guide</a></li> 
-            </menu>
-      <div class="menuheader"><a 
-href="/guides/index.html">Podling Guides</a></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/projects.html">Podling Mentor</a></li> 
-          <li><a href="/guides/releasemanagement.html">Podling Releases</a></li> 
-          <li><a href="/guides/branding.html">Podling Branding</a></li> 
-          <li><a href="/guides/sites.html">Podling Websites</a></li> 
-            </menu>
-      <div class="menuheader"><a 
-href="/ip-clearance/index.html">IP Clearance</a></div> 
-    <menu compact="compact">
-            </menu>
-      <div class="menuheader"><a 
-href="/whoweare.html">Who We Are</a></div> 
-    <menu compact="compact">
-            </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">PMC</a> (<a href="/guides/chair.html">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"><a 
-href="http://wiki.apache.org/incubator">Wiki</a></div> 
-    <menu compact="compact">
-            </menu>
-
-     <!--#include virtual="/ads/bannerbar.html" -->    </td>
-    <!-- CONTENT -->
-    <td align="left" valign="top" class="content">
-                <h2><img src="/images/redarrow.gif" />
-   <a name="intro">A Guide To Release Management During Incubation (DRAFT)</a>
-</h2>
-<div class="section-content">
-<h3>
-   <a name="status">Status - DRAFT</a>
-</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>
-<h3>
-   <a name="abstract">Abstract</a>
-</h3>
-<div class="section-content">
-<p>
-This document is descriptive, not normative. It aims to guide podlings through the process of release management.
-            </p>
-<p>
-It contains advice on best practice, links to Apache release management 
-<a href="http://www.apache.org/dev/index.html#releases">policy and practice</a> 
-with commentary and discusses incubation release management  
-<a href="/incubation/Incubation_Policy.html#Releases">policy</a>. 
-            </p>
-</div>
-<h3>
-   Apache Releases
-</h3>
-<div class="section-content">
-<p>
-Releases are important:
-		</p>
-<ul>
-	          <li>Publishing software has legal consequences. </li>
-	          <li>Most users interact with a project only through it's releases. 
-	          They are a public face of the project and are often the first chance 
-	          to make a good impression.</li>
-        </ul>
-<p>
-Releases at Apache involve more ceremony than many other processes. Poor quality releases impact
-not only on the project but also the foundation as a whole. 
-        </p>
-</div>
-<h3>
-   Organisation
-</h3>
-<div class="section-content">
-<p>
-			TODO: describe organisation of this document.
-			</p>
-</div>
-<h3>
-   <a name="help">Help Wanted!</a>
-</h3>
-<div class="section-content">
-<p>
-Help to finish this document by contributing documentation patches to the incubator general list!
-If the information you seek isn't in this document, 
-then please submit a patch once the incubator folks have answered your question.
-    </p>
-<p>
-<strong>Best Practice Needs You!</strong> This document aims to collect best practice amongst
-Apache projects, not to disseminate some wisdom from on high. If you know some good release practice
-that isn't included then please ask for karma or submit a patch. Different options or opinions 
-are encouraged.
-    </p>
-</div>
-</div>
-           <h2><img src="/images/redarrow.gif" />
-   <a name="guidelines">Guidelines</a>
-</h2>
-<div class="section-content">
-<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>
-<h3>
-   <a name="process">Release Process</a>
-</h3>
-<div class="section-content">
-<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.
-Release approved by project 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 project adopt more ceremony than this minimum for a number of important reasons. 
- 			</p>
-<p>
- ASF releases are often widely distributed and long lived. Expect to be publically held to account 
- for a substandard release for a long time to come. 
-    		</p>
-<p>
-As a project matures and its reputation grows, the consequences of a poor quality release increase.
-It is therefore typical for mature projects to use release candidates, beta, alphas and so on. 
-This ceremony is usually not necessary for neonate projects but may need to be adopted in time.
-			</p>
-<p>
-			TODO: release models - describe process models for more complex projects.
-			</p>
-</div>
-<h3>
-   <a name="policies">ASF Release Policy</a>
-</h3>
-<div class="section-content">
-<p>
-Policy is set by the board and by board committees (legal, infra, prc). 
-    		</p>
-<p>
-it is simple but subtle (it's rare for components to create complient releases first time).
-
-    		</p>
-</div>
-<p>
-It is strong recommended that a project creates it's own release guidelines. The actual 
-<a href="#rules">minimum</a> required by the ASF is reasonable small but subtle. However,
-the traditional standards for ASF releases are quite high. 
-        </p>
-<p>
-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="glossay-release-manager">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 organisations,
-in the middle stages of a release, for deciding which code will be included in the release,
-in the late stages for marshalling the VOTEs required for formal approval
-then finally for <a href="#glossay-cutting-release">cutting the release</a>.
-TODO: maybe be better in a time line
-        </p>
-</div>
-           <h2><img src="/images/redarrow.gif" />
-   <a name="check-list">Check List</a>
-</h2>
-<div class="section-content">
-<p>
-<strong>Note</strong> this is not intended to replace an understanding of the release process.
-        </p>
-<ul>
-            <li><a href="#glossary-distributions">Distributions</a>
-                <ul>
-                    <li>Check compressed distributions <a href="#best-practice-formats">unpack correctly</a></li>
-                    <li>Check documentation is readable</li>
-                    <li>Check <a href="best-practice-distributing-libraries">distributed libraries</a>
-                    	<ul>
-	                    	<li>Check licenses for libraries are distributed together with any applicable 
-	                    	<a href="best-practice-notice">NOTICEs</a> TODO: link</li>
-                    		<li>Check that licenses comply with incubator policy TODO: link</li>
-                    		<li>Check that licenses comply with project policy TODO: link</li> 
-                    		<li>Check that LICENSE and NOTICE documents contain required sections</li>
-                    		<li>Check that any cryptographic dependencies satisfy export regulations</li>
-                    	</ul>
-                    </li>
-                    <li>Check copyright notices:
-                    	<ul>
-	                    	<li>Licences missing from source files</li>
-	                    	<li>Source files with other licenses which are not mentioned in LICENSE</li>
-	                    	<li>Check current policy on headers that all comply</li>
-                    	</ul>
-                    </li>
-                </ul>
-            </li>
-            <li><a href="#glossary-artifact">Distributed Artifacts</a>
-                <ul>
-                    <li>Check <a href="#license">LICENSE</a> and <a href="#notice">NOTICE</a> files.</li>
-                </ul>
-            </li>
-            <li><a href="#glossary-source-distribution">Source Distribution</a>
-            	<ul>
-            		<li>Check build instructions exist and that source <a href="#best-practice-source-build">builds</a>
-            		using these instructions</li>
-            		<li>Check <a href="glossary-license-headers">license headers</a> 
-            		are <a href="notes-license-headers">correctly applied</a></li>
-            		<li>Check for <a href="#best-practice-source">version control</a> files</li>
-            		<li>Check that source is exported from tag</li>
-            	</ul>
-            </li>
-         	<li>OpenPGP keys
-         		<ul>
-         			<li>Check KEYS file contains signing key</li>
-         			<li>Check key has been uploaded to regular public key servers</li>
-         		</ul>
-         	</li>
-        </ul>
-</div>
-           <h2><img src="/images/redarrow.gif" />
-   <a name="rules">Rules</a>
-</h2>
-<div class="section-content">
-<p>
-        TODO release votes by pmc, legal rules (licenses of distributed dependencies, source licenses, LICENSE, NOTICE), 
-        infrastructure rules(signing). Use links so information is maintained 
-        in only one place.
-        </p>
-<h3>
-   <a name="naming"></a>
-</h3>
-<div class="section-content">
-<p>
-            TODO: incubator rules
-            </p>
-</div>
-</div>
-           <h2><img src="/images/redarrow.gif" />
-   <a name="release-guidelines">Release Guidelines</a>
-</h2>
-<div class="section-content">
-<p>
-In addition to policy, the infrastructure, public relations and legal teams also
-document <a href="#glossary-guidelines">guidelines</a> for projects.
-There are almost certainly good reasons why a project should follow
-these guidelines but they have not been blessed as policy.
-    	</p>
-<p>
-Guidelines change much more frequently than policy. Release managers should follow the appropriate
-lists (TODO: create list of useful mailing lists).
-    	</p>
-</div>
-           <h2><img src="/images/redarrow.gif" />
-   <a name="best-practice">Best Practice</a>
-</h2>
-<div class="section-content">
-<h3>
-   <a name="best-practice-jars">Jars</a>
-</h3>
-<div class="section-content">
-<ul>
-                <li><code>META-INF</code>
-                    <ul>
-                        <li>
-    Should include <a href="#license">LICENSE</a> and <a href="#NOTICE">NOTICE</a>. 
-    Note <a href="#distributing-jars">this</a>
-                        </li>
-                        <li>
-    Should include a standards compliant MANIFEST. Note <a href="#jar-manifest">this</a>.
-                        </li>
-                    </ul>
-                </li>
-            </ul>
-</div>
-<h3>
-   <a name="best-practice-naming">Artifact Naming</a>
-</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>
-   <a name="best-practice-types">Distribution Types</a>
-</h3>
-<div class="section-content">
-<p>
- TODO: glossay - distribution type: based on the same tagged source built  
- TODO: Common Types of distribtuion
- 			</p>
-<p>
- The source distribution is canonical. Every release should create a source distribution.
- compiled languages may also wish to create binary releases. these may be platform specific.
- some project may also convenience types which package the project for particular containers.
-        	</p>
-<p>
- All types of distribution ship as <a href="best-practice-formats">compressed artifacts</a>.
- This means a distribution type may be shipped as multiple compressed artifacts.
-        	</p>
-</div>
-<h3>
-   <a name="best-practice-downstream">Downstream Packagers</a>
-</h3>
-<div class="section-content">
-<p>
- TODO: glossay - 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 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>
-   <a name="best-practice-source">Source Distributions</a>
-</h3>
-<div class="section-content">
-<p>
-        	TODO: describe what a source distribution is; version control for distributions; 
-        	add content to release documents; export not checkout
-        	</p>
-<p>
- Many would argue that for open source projects, the source distribution is the release:
- binaries are just for convenience. There are some pragmatic (as well as philosophical)
- reasons why a source distribution should be issued:
-        	</p>
-<ul>
-        		<li>Downstream packages usually prefer to work from a source distribution.
-        		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 distributions encourages developers to modify the code base. Recruiting
-new developers is vital for the long term health of an Apache project.
-				</li>
-        	</ul>
-</div>
-<h3>
-   <a name="best-practice-binary">Binary Distribution</a>
-</h3>
-<div class="section-content">
-<p>
-A binary distribution is any distribution that is not an exported snapshot of the source.
-Binary distributions may include source. For some projects, this makes sense.
-For others, it does not.
-        	</p>
-</div>
-<h3>
-   <a name="best-practice-documentation">Release Documentation</a>
-</h3>
-<div class="section-content">
-<p>
-Users expect <a href="glossary-release-documentation">release documentation</a> 
-to be present in the root directory of the distribution. 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 distribution</a>
-including source distributions.
-So the master documents should be checked into the base subversion directory.
-        	</p>
-<p>
-TODO: rewrite to be topic centric.
-* project status. DISCLAIMER or STATUS 
-Incubating projects should ensure that either contain the STATUS document describing. TODO: check this
-        	</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 tool (for example maven) to collect this information automatically.
-A third is for the release manager to collect all the information required
-when the release is made. The disadvantage of this method is that increases
-the work required to create a release.
-			</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
- (TODO: maven) or included in the RELEASE NOTES. svn log can be used to collect changes.
-  This is a good opertunity 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 tool) 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>
-   <a name="best-practice-status">STATUS document</a>
-</h3>
-<div class="section-content">
-<p>
-TODO: check this TODO: the STATUS document should be checked to ensure that it is up to date
-before release. Incubator releases should do a <a href="#best-practice-audit">legal audit</a> 
-before releasing. The legal STATUS of the codebase should be clean before it is released.
-        	</p>
-</div>
-<h3>
-   <a name="best-practice-license">LICENSE and NOTICE</a>
-</h3>
-<div class="section-content">
-<p>
-Apache projects may distribute artifacts and documents as part of a release
-which are not Apache Licensed. TODO link to policy. 
-        	</p>
-<p>
-The artifacts and documents to which each subsidary clause applies should be 
-indicated in the document. This <a href="examples/LICENSE">LICENSE</a>
-(curtous of <a href="http://httpd.apache.org">Apache HTTPD</a>) is a
-good example. The Apache License is at the top of document. The explaination
-is clear and the files to which the licenses apply are clearly noted.
-        	</p>
-</div>
-<h3>
-   <a name="best-practice-audit">Legal Audit</a>
-</h3>
-<div class="section-content">
-<p>
- It is of particular importance that released code is clean. 
- It is good practice to check the provinance of any source documents 
- which do not have license headers. Check that dependencies (and in particular
- those dependencies that ship in the distribution) 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>
-   <a name="best-practice-formats">Compression Formats</a>
-</h3>
-<div class="section-content">
-<p>
-<a href="best-practice-distributions">Distributions</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. 
-It is therefore convenient for users to ship each type of distribution in more than one
-compressed format. Ship 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 distributions.
-            </p>
-<p>
-Different <a href="#best-practice-types">distribution 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 distributions do not overwrite each other</li>
-				<li>it allows easy identification of different distribution types</li>
-			</ul>
-<p>
-For project, <em>Apache Foo</em> (say) with source and binary types, it is conventional for the main binary
-to unpack to <code>apache-foo</code> and the source to <code>apache-foo-src</code>.
-Other binary types should unpack to suitably suffixed directories (for example, 
-<code>apache-foo-sdk</code>).
-            </p>
-<p>
-Compressed archives should unpack into a contained directory (rather than straight 
-into the current directory). The directory into which the release unpacks should follow
-the standard naming convention. apache-foo.tar.gz should unpack to the apache-foo
-directory.
-            </p>
-<p>
-Note (TODO link) that there are known compatibility issues when using certain tar programs. 
-(TODO solaris verses GNU tar)
-It is recommend that project that use Ant or Maven as build tools use these tools to create
-the archives since these implementations work well across a range of platforms. 
-It is recommended that project which do not use these tools consider shipping the
-*nix distribution as a bz2 archive.
-            </p>
-</div>
-<h3>
-   <a name="best-practice-source-build">Source Distribution Build</a>
-</h3>
-<div class="section-content">
-<p>
-This section applies only to compiled languages.
-        	</p>
-<p>
-Source distributions should contain easy instructions describing how to build the project.
-The source distribution should build from instructions contained. 
-TODO: best practices for instructing users about building the project.
-            </p>
-<p>
-Build instructions should give supported version numbers for build tools (for example, maven and ant).
-            </p>
-</div>
-<h3>
-   <a name="best-practice-dependencies">Dependencies</a>
-</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 distribution
-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.
-tool 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>
-</div>
-<h3>
-   <a name="best-practice-distributing-libraries">Distributing Libraries</a>
-</h3>
-<div class="section-content">
-<p>
-TODO: ASF policy compliance
-TODO: project policy - explicit policy should be written down
-            </p>
-<p>
-TODO: Discussion on the merits of distributing dependent jars. 
-            </p>
-</div>
-<h3>
-   <a name="best-practice-notice">NOTICE files</a>
-</h3>
-<div class="section-content">
-<p>
- TODO: links to infra
-        	</p>
-<p>
- Discuss about what's appropriate for NOTICE files. 
-        	</p>
-</div>
-<h3>
-   <a name="best-practices-svn">Subversion Best Practices</a>
-</h3>
-<div class="section-content">
-<p>
-        	TODO: svn is flexible. branchs and tags are not the same as svn.
-        	</p>
-<p>
-All releases should be built from a tag. It is occasionally necessary to rebuild
-releases many years later.
-Tagging is cheap and easy when using subversion.
-So, every release and candidate should be tagged. 
-        	</p>
-<p>
-It is useful to adopt a reasonable naming convention when 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 reproducable.
-        	</p>
-</div>
-<h3>
-   <a name="best-practice-reproducability">Reproducability</a>
-</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 permenantly archived. 
-It is very occasionally necessary (for example, for legal reasons) 
-to alter some small parts of a release or simply to recreate an old 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 
-used to build the release should be noted.
-        	</p>
-</div>
-<h3>
-   <a name="best-practice-dependencies">Dependencies</a>
-</h3>
-<div class="section-content">
-<p>
-As well as libraries, projects often have more subtle dependencies.
-Many languages (for example Java and Perl) have different versions.
-It is important that the versions of a language upon which a project
-will run are clearly documented. The <a href="TODO:">release notes</a>
-are a typical location for this information. <a href="TODO:link to note on ">Note</a>
-that Java also includes the version used to build in the MANIFEST. 
-        	</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, those shipped as binary libraries 
-and those shipped as source document 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>
-   <a name="announcements">Announcements</a>
-</h3>
-<div class="section-content">
-<p>
-TODO: release managers should ensure that releases are announced.
-TODO: links to release management FAQs
-TODO: consider grassroot sites eg freshmeat.net
-TODO: link note on press release 
-        	</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 transfering this.
-        	</p>
-<p>
-Announcements should be posted from the release manager's 
-<code>apache.org</code> address.
-        	</p>
-</div>
-<h3>
-   <a name="best-practices-release-candidates">Release Candidates</a>
-</h3>
-<div class="section-content">
-<p>
-A release candidate is a artifact 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 release 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 reachs full release status. In this case the same candidate will
-be know as a release candidate, an alpha, a beta and then a full release.
-        	</p>
-<p>
- Those projects which reroll candidates will vote on a sample release candidate.
-        	</p>
-<p>
-Only full releases should be place 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 old releases.
-        	</p>
-</div>
-<h3>
-   <a name="signing-releases">Signatures</a>
-</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 propergate 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><img src="/images/redarrow.gif" />
-   <a name="notes">Notes</a>
-</h2>
-<div class="section-content">
-<h3>
-   <a name="distributing-jars">Distributing Jars</a>
-</h3>
-<div class="section-content">
-<p>
-            TODO: link to infrastructure
-            </p>
-<p>
-Jars are just another form of binary distribution. If they are likely to be distributed
-(for example, through the Apache Repository) then they must adhere to the same policy
-as other binary distributions. In particular, LICENSE and NOTICE files must be distributed.
-            </p>
-<p>
-It is convenient to include these with the META-INF directory. This can be done easily either 
-either with Ant or Maven. TODO: move examples here from jakarta commons releases.
-            </p>
-</div>
-<h3>
-   <a name="jar-manifest">Jar MANIFEST</a>
-</h3>
-<div class="section-content">
-<p>
-TODO
-Lots of projects get this wrong and (by default) most tools produce substandard manifests.
-Offer some guidance on values
-TODO: Add how to create a specification complient MANIFEST 
-http://jakarta.apache.org/commons/releases/prepare.html#checkjarmanifest
-            </p>
-<p>
-Maven 1 produces a minimal MANIFEST. This should be augemented with the 
-recommended by adding appropriate 
-<a href="http://maven.apache.org/maven-1.x/plugins/jar/properties.html">properties</a>
-to the <code>project.properties</code> file.
-            </p>
-<p>
-Maven 2 produces a much better manifest provided that the POM is reasonably full.
-It does not (by default) include some recommended. It is recommended that POM should be
-<a href="http://maven.apache.org/plugins/maven-jar-plugin/examples/manifest-customization.html">customized</a>
-so that it includes the missing recommendation.
-            </p>
-</div>
-<h3>
-   <a name="best-practice-release-candidate">Release Candidates</a>
-</h3>
-<div class="section-content">
-<p>
-There are two distinct approaches <a href="glossary-release-candidate">release candidate</a>.  
-        	</p>
-</div>
-<h3>
-   <a name="best-practice-versioning">Versioning</a>
-</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 necessessity to raise a major version number (say) if 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>
-   <a name="notes-numbering-between-releases">Version Numbering Between Releases</a>
-</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>
-   <a name="best-practice-unique-names">Unique Artifact Names</a>
-</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 excerted 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 distribution</a> should be 
-assigned a consistent and unique name. Conventionally, source distributions use <code>src</code>
-and main binary distributions no prefix. Typically each type of distributions is made available in a number of 
-<a href="best-practice-formats">compression format</a>. These are conventionally distiguished 
-by the usual file type suffix.
-        	</p>
-<p>
-So, the traditional format is apache-project-product-type-version.format.
-        	</p>
-</div>
-<h3>
-   <a name="release-notes">Release Notes</a>
-</h3>
-<div class="section-content">
-<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 distribution should ship with the release notes.
-The release notes document should therefore be committed to the source
-repository so that it ships with the source distribution.
-            </p>
-</div>
-<h3>
-   <a name="notes-signing-releases">Signing Releases</a>
-</h3>
-<div class="section-content">
-<p>
-TODO: links to dev pages
-batch signing scripts in committers
-        	</p>
-</div>
-<h3>
-   <a name="note-on-multiple-products">On Mutiple Products</a>
-</h3>
-<div class="section-content">
-<p>
-A project may release a number of distinction products created by the same community.
-TODO: differences between products and distributions.
-        	</p>
-</div>
-<h3>
-   <a name="notes-on-templates">On Template Sources</a>
-</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 
-distribution 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 restributions. 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>
-   <a name="notes-on-java-version">On Java Versions</a>
-</h3>
-<div class="section-content">
-<p>
-Indicating supported versions for dependencies is 
-<a href="#best-practice-dependencies">important</a>. The minimum 
-(and - where appropriate - maxiumum)  Java version need to be clearly documented
-in the release. This information should be included in a README or the RELEASE NOTES.
-        	</p>
-<p>
- Users often expect the minimum version supported to be the one listed in the MANIFEST.
- There are also good reasons for releases to be compiled with the minimum version 
- of Java supported by the release. This is the easiest way to ensure that the release
- will work as expected on that version. This will ensure that the version in the MANIFEST
- is as expected. 
- 			</p>
-<p>
-If the version in the MANIFEST cannot reflect the minimum support version (see below) 
-then it is recommended that the following additional entries are added to MANIFEST.
- 			</p>
-<p>
-The usual reason for need to use a more modern Java version is to support
-optional classes which require features present only in the new version.
-			</p>
-<p>
-The approach which requires the least configuration is to adopt a split compilation
-strategy. The release manager installs two separate Java versions. The build
-script supports optional parameterisation allowing the optional code to be compiled with 
-a second JSDK. It is recommended that the build scrip includes clear indications
-that a second JSDK has been detected.
- 			</p>
-<p>
-The alternative is to correctly configure a more modern JSDK to compile code
-which will function correctly on an older JRE. This means TODO: javac settings through 
-Ant. This is not sufficient. Unfortunately the source also need to be compiled against
-the appropriate version of the Java API. TODO: check where the jar has to be exactly
-placed.
-        	</p>
-</div>
-<h3>
-   <a name="notes-on-export-regulations">On Export Regulations</a>
-</h3>
-<div class="section-content">
-<p>
-TODO preable TODO link to legal
-        	</p>
-</div>
-<h3>
-   <a name="notes-on-compression-formats"></a>
-</h3>
-<div class="section-content">
-</div>
-<h3>
-   <a name="notes-on-line-endings">On Line Endings</a>
-</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 distributions can use <code>svn export --native-eols</code>. Binary distributions
-build with <a href="http://ant.apace.org">Ant</a> can use 
-<a href="http://ant.apache.org/manual/CoreTasks/fixcrlf.html">fixcrlf</a>.
-            </p>
-</div>
-<h3>
-   <a name="notes-press-releases">On Press Releases</a>
-</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>
-   <a name="notes-on-signing-jars">On Signing Jars</a>
-</h3>
-<div class="section-content">
-<p>
-Java includes a standard mechanism for signing jars. Apache uses digitial
-signatures to protect releases. TODO: reconsider this section.
-        	</p>
-<p>
-Though there is no rule against issuing signed jars, project should educate
-themselves about the potentially negative consequences of doing so.
-Classloaders treat signed jars differently. In particular, packages are 
-sealed against modification. Open source encourages modification. 
-TODO: rephrase and check
-        	</p>
-</div>
-<h3>
-   <a name="notes-license-headers">On License Headers</a>
-</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 stylesheets, test code and resources, build files 
-            and documentation source. When in doubt, add a header.
-            </p>
-<p>
-            TODO: tool
-            </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>
-</div>
-<h3>
-   <a name="note-license-and-notice">Understanding Content For NOTICE and LICENSE</a>
-</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 following 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>
-</div>
-<h3>
-   <a name="note-votes">VOTEs</a>
-</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 prioritise 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 PMCers is available TODO: link online. Note that 
-sometimes the online lists are out of date. TODO: link to foundation site.
-			</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 followed by <code>[WAS</code> and the old subject.
-For example, old 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>
-   <a name="note-pmc-vote"></a>
-</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>
-   <a name="notes-revote">On Managing VOTE Threads</a>
-</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 ackowledged.
-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 abandone a VOTE thread that goes estray 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>
-   <a name="notes-release-candidate-java">On Java Release Candidates</a>
-</h3>
-<div class="section-content">
-<p>
-This section applies to any distribution that contains redistributable artifacts which contain version
-information but in particular binary distributions of Java contain jar files. A complient MANIFEST 
-meta data file within each of these files should contain the implementation version.
-These are good reasons to use the release version number as the implementation version.
-This allows the exact version to be determined from just the jar.
-Unfortunately, some applications expect the format to be entirely numeric (TODO: maven?)
-			</p>
-<p>
-This does mean that release candidates for binary distributions of this type must either
-be rerolled with the version number as the only change or accept that artifacts will not be 
-uniquely named. Uncertainty about exact jar versions has caused nasty dependency
-issues in the past.
-			</p>
-</div>
-<h3>
-   <a name="notes-on-gnu-tar">GNU Tar Known Incompatibilities</a>
-</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 Solaris and some
-(older) versions of MacOSX is not always compatible with the output of GNU tar.
-        	TODO: check information and expand
-        	</p>
-</div>
-<h3>
-   <a name="notes-on-source-only-releases">On Source Only Releases</a>
-</h3>
-<div class="section-content">
-<p>
-A source only release contains only the source distribution. Though users often prefer
-binary distributions, 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>
-   <a name="notes-on-binary-only-releases">On Binary Only Releases</a>
-</h3>
-<div class="section-content">
-<p>
-Releases containing only binary distributions are strongly frowned upon. Open source 
-development is characterised by the accessibility of the source. Binary only distributions
-discourage developers from interacting with the source. Every successful Apache
-project needs to recruit new developers to carry the project forward.
-        	</p>
-</div>
-</div>
-           <h2><img src="/images/redarrow.gif" />
-   <a name="glossary">Glossary</a>
-</h2>
-<div class="section-content">
-<h3>
-   <a name="glossary-artifact">Distributed Artifact</a>
-</h3>
-<div class="section-content">
-<p>
-A file that is actually shipped.
-        	</p>
-<p>
-            TODO (include link to infra documentation)
-            </p>
-</div>
-<h3>
-   <a name="glossary-license">LICENSE file</a>
-</h3>
-<div class="section-content">
-<p>
-  Document containing the licenses for the distribution.
-        	</p>
-<p>
-            TODO (include link to infra documentation)
-            </p>
-</div>
-<h3>
-   <a name="glossary-notice">NOTICE file</a>
-</h3>
-<div class="section-content">
-<p>
-            TODO (include link to infra documentation)
-            </p>
-</div>
-<h3>
-   <a name="glossary-ceremony">Ceremony</a>
-</h3>
-<div class="section-content">
-<p>
-        	Process and procedure associated with - but not necessary to - a particular end.
-        	TODO: link to foundation docs
-        	</p>
-</div>
-<h3>
-   <a name="glossary-manifest">Jar MANIFEST</a>
-</h3>
-<div class="section-content">
-<p>
-Meta data associated with the Java Jar format.
-        	</p>
-<p>
-            TODO link to sun documentation
-            </p>
-</div>
-<h3>
-   <a name="glossary-license-header">License Header</a>
-</h3>
-<div class="section-content">
-<p>
-Text referring to the license for a file (as opposed to the license text).
-         	</p>
-<p>
-            TODO (include link to legal documentation)
-            </p>
-</div>
-<h3>
-   <a name="glossary-release-manager">Release Manager</a>
-</h3>
-<div class="section-content">
-<p>
-Committer responsible for sheparding the release. 
-        	</p>
-<p>
-            TODO (include link to infra documentation)
-            TODO say something about the technical release manager (who
-            cuts the release) and the social one (who organises it).
-            </p>
-</div>
-<h3>
-   <a name="glossary-release-candidate">Release Candidate</a>
-</h3>
-<div class="section-content">
-<p>
-            TODO (include link to infra documentation)
-            </p>
-</div>
-<h3>
-   <a name="glossary-distribution">Distribution</a>
-</h3>
-<div class="section-content">
-<p>
-            TODO (include link to infra documentation)
-            </p>
-</div>
-<h3>
-   <a name="glossary-distribution-type">Distribution Type</a>
-</h3>
-<div class="section-content">
-<p>
-            TODO (include link to infra documentation)
-            </p>
-</div>
-<h3>
-   <a name="glossary-source-distribution">Source Distribution</a>
-</h3>
-<div class="section-content">
-<p>
-            TODO: (include link to infra documentation)
-            </p>
-</div>
-<h3>
-   <a name="glossary-binary-distribution">Binary Distribution</a>
-</h3>
-<div class="section-content">
-<p>
-            TODO: (include link to infra documentation)
-            binary distributions include all types which are not source. 
-            one canonical source distribution, many binary distributions.
-            </p>
-</div>
-<h3>
-   <a name="glossary-cutting-release">Cutting The Release</a>
-</h3>
-<div class="section-content">
-<p>
-The actual execution of the release. Typically consists of building the distribtions
-from the repository tag.
-TODO: link to infra
-        	</p>
-</div>
-<h3>
-   <a name="glossary-guidelines">Guidelines</a>
-</h3>
-<div class="section-content">
-<p>
-Guidelines are documented recommendations which have not yet been blessed as policy.
-There are usually good reasons why project should follow the guidelines given
-even if these may be initially obvious.
-        	</p>
-</div>
-<h3>
-   <a name="glossary-release-documentation">Release Documentation</a>
-</h3>
-<div class="section-content">
-<p>
-Documents a particular release of a product rather than the product itself.
-        	</p>
-</div>
-</div>
-         </td>
-    <!-- RIGHT SIDE NAVIGATION -->
-    <td valign="top" nowrap="nowrap" class="navright">
-           <div class="menuheader"><a 
-href="/projects/index.html">Projects</a></div>
-    <menu compact="compact">
-          <li><a href="/projects/abdera.html">Abdera</a></li> 
-          <li><a href="/projects/activemq.html">ActiveMQ</a></li> 
-          <li><a href="/projects/adffaces.html">ADF Faces</a></li> 
-          <li><a href="/projects/agila.html">Agila</a></li> 
-          <li><a href="/projects/altrmi.html">AltRMI</a></li> 
-          <li><a href="/projects/cayenne.html">Cayenne</a></li> 
-          <li><a href="/projects/cxf.html">CXF</a></li> 
-          <li><a href="/projects/felix.html">Felix</a></li> 
-          <li><a href="/projects/ftpserver.html">FtpServer</a></li> 
-          <li><a href="/projects/graffito.html">Graffito</a></li> 
-          <li><a href="/projects/harmony.html">Harmony</a></li> 
-          <li><a href="/projects/heraldry.html">Heraldry</a></li> 
-          <li><a href="/projects/juice.html">JuiCE</a></li> 
-          <li><a href="/projects/log4net.html">log4net</a></li> 
-          <li><a href="/projects/log4php.html">log4php</a></li> 
-          <li><a href="/projects/lokahi.html">Lokahi</a></li> 
-          <li><a href="/projects/lucene4c.html">Lucene4c</a></li> 
-          <li><a href="/projects/lucene.net.html">Lucene.Net</a></li> 
-          <li><a href="/projects/mod_ftp.html">mod_ftp</a></li> 
-          <li><a href="/projects/ode.html">Ode</a></li> 
-          <li><a href="/projects/ofbiz.html">OFBiz</a></li> 
-          <li><a href="/projects/openejb.html">OpenEJB</a></li> 
-          <li><a href="/projects/openjpa.html">OpenJPA</a></li> 
-          <li><a href="/projects/qpid.html">Qpid</a></li> 
-          <li><a href="/projects/roller.html">Roller</a></li> 
-          <li><a href="/projects/servicemix.html">ServiceMix</a></li> 
-          <li><a href="/projects/solr.html">Solr</a></li> 
-          <li><a href="/projects/stdcxx.html">stdcxx</a></li> 
-          <li><a href="/projects/synapse.html">Synapse</a></li> 
-          <li><a href="/projects/tsik.html">TSIK</a></li> 
-          <li><a href="/projects/tuscany.html">Tuscany</a></li> 
-          <li><a href="/projects/wadi.html">wadi</a></li> 
-          <li><a href="/projects/wicket.html">Wicket</a></li> 
-          <li><a href="/projects/woden.html">Woden</a></li> 
-          <li><a href="/projects/wsrp4j.html">WSRP4J</a></li> 
-          <li><a href="/projects/xap.html">XAP</a></li> 
-          <li><a href="/projects/yoko.html">Yoko</a></li> 
-        </menu>
-
-<form action="http://www.google.com/search" method="get">
-    <input value="incubator.apache.org" name="sitesearch" type="hidden"/>
-    <input size="8" name="q" id="query" type="text" value="search..."
-        onclick="if(this.value == 'search...') {this.value = ''}"/>
-    <input name="Search" value="Go" type="submit"/>
-</form>
-    </td>     
-   </tr>
-   <!-- FOOTER -->
-   <tr><td colspan="3"><hr noshade="noshade" size="1"/></td></tr>
-   <tr><td colspan="3" class="footer">
-         Copyright &#169; 1999-2006, The Apache Software Foundation<br />
-Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
-       </td>
-   </tr>
-  </table>
- </body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!--
+Copyright 1999-2006 The Apache Software Foundation
+Licensed 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>
+ <head>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <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>        
+  <table border="0" width="100%" cellspacing="0">
+   <tr><!-- SITE BANNER AND PROJECT IMAGE -->
+    <td align="left" valign="top">
+<a href="http://www.apache.org/"><img src="/images/asf_logo_wide.gif" alt="The Apache Software Foundation" border="0"/></a>
+</td>
+<td align="right">
+<a href="http://incubator.apache.org/"><img src="../images/apache-incubator-logo.png" alt="Apache Incubator" border="0"/></a>
+</td>
+   </tr>
+  </table>
+  <table border="0" width="100%" cellspacing="4">
+   <tr><td colspan="3"><hr noshade="noshade" size="1"/></td></tr>
+   <tr>
+    <!-- LEFT SIDE NAVIGATION -->
+    <td valign="top" nowrap="nowrap" class="navleft">
+           <div class="menuheader"><a 
+href="http://www.apache.org/foundation/glossary.html#Podling">Podlings (What's that?)</a></div> 
+    <menu compact="compact">
+          <li><a href="/incubation/Incubation_Policy.html">How? (Policy)</a></li> 
+          <li><a href="/incubation/Roles_and_Responsibilities.html">Who? (Roles)</a></li> 
+          <li><a href="/incubation/Process_Description.html">When? (Process)</a></li> 
+            </menu>
+      <div class="menuheader"><a 
+href="/guides/index.html">Entry Guides</a></div> 
+    <menu compact="compact">
+          <li><a href="/guides/proposal.html">Proposal Guide</a></li> 
+            </menu>
+      <div class="menuheader"><a 
+href="/guides/index.html">Podling Guides</a></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/projects.html">Podling Mentor</a></li> 
+          <li><a href="/guides/releasemanagement.html">Podling Releases</a></li> 
+          <li><a href="/guides/branding.html">Podling Branding</a></li> 
+          <li><a href="/guides/sites.html">Podling Websites</a></li> 
+            </menu>
+      <div class="menuheader"><a 
+href="/ip-clearance/index.html">IP Clearance</a></div> 
+    <menu compact="compact">
+            </menu>
+      <div class="menuheader"><a 
+href="/whoweare.html">Who We Are</a></div> 
+    <menu compact="compact">
+            </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">PMC</a> (<a href="/guides/chair.html">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"><a 
+href="http://wiki.apache.org/incubator">Wiki</a></div> 
+    <menu compact="compact">
+            </menu>
+
+     <!--#include virtual="/ads/bannerbar.html" -->    </td>
+    <!-- CONTENT -->
+    <td align="left" valign="top" class="content">
+                <h2><img src="/images/redarrow.gif" />
+   <a name="intro">A Guide To Release Management During Incubation (DRAFT)</a>
+</h2>
+<div class="section-content">
+<h3>
+   <a name="status">Status - DRAFT</a>
+</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>
+<h3>
+   <a name="abstract">Abstract</a>
+</h3>
+<div class="section-content">
+<p>
+This document is descriptive, not normative. It aims to guide podlings through the process of release management.
+            </p>
+<p>
+It contains advice on best practice, links to Apache release management 
+<a href="http://www.apache.org/dev/index.html#releases">policy and practice</a> 
+with commentary and discusses incubation release management  
+<a href="/incubation/Incubation_Policy.html#Releases">policy</a>. 
+            </p>
+</div>
+<h3>
+   Apache Releases
+</h3>
+<div class="section-content">
+<p>
+Releases are important:
+		</p>
+<ul>
+	          <li>Publishing software has legal consequences. </li>
+	          <li>Most users interact with a project only through it's releases. 
+	          They are a public face of the project and are often the first chance 
+	          to make a good impression.</li>
+        </ul>
+<p>
+Releases at Apache involve more ceremony than many other processes. Poor quality releases impact
+not only on the project but also the foundation as a whole. 
+        </p>
+</div>
+<h3>
+   Organisation
+</h3>
+<div class="section-content">
+<p>
+			TODO: describe organisation of this document.
+			</p>
+</div>
+<h3>
+   <a name="help">Help Wanted!</a>
+</h3>
+<div class="section-content">
+<p>
+Help to finish this document by contributing documentation patches to the incubator general list!
+If the information you seek isn't in this document, 
+then please submit a patch once the incubator folks have answered your question.
+    </p>
+<p>
+<strong>Best Practice Needs You!</strong> This document aims to collect best practice amongst
+Apache projects, not to disseminate some wisdom from on high. If you know some good release practice
+that isn't included then please ask for karma or submit a patch. Different options or opinions 
+are encouraged.
+    </p>
+</div>
+</div>
+           <h2><img src="/images/redarrow.gif" />
+   <a name="guidelines">Guidelines</a>
+</h2>
+<div class="section-content">
+<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>
+<h3>
+   <a name="process">Release Process</a>
+</h3>
+<div class="section-content">
+<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.
+Release approved by project 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 project adopt more ceremony than this minimum for a number of important reasons. 
+ 			</p>
+<p>
+ ASF releases are often widely distributed and long lived. Expect to be publically held to account 
+ for a substandard release for a long time to come. 
+    		</p>
+<p>
+As a project matures and its reputation grows, the consequences of a poor quality release increase.
+It is therefore typical for mature projects to use release candidates, beta, alphas and so on. 
+This ceremony is usually not necessary for neonate projects but may need to be adopted in time.
+			</p>
+<p>
+			TODO: release models - describe process models for more complex projects.
+			</p>
+</div>
+<h3>
+   <a name="policies">ASF Release Policy</a>
+</h3>
+<div class="section-content">
+<p>
+Policy is set by the board and by board committees (legal, infra, prc). 
+    		</p>
+<p>
+it is simple but subtle (it's rare for components to create complient releases first time).
+
+    		</p>
+</div>
+<p>
+It is strong recommended that a project creates it's own release guidelines. The actual 
+<a href="#rules">minimum</a> required by the ASF is reasonable small but subtle. However,
+the traditional standards for ASF releases are quite high. 
+        </p>
+<p>
+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="glossay-release-manager">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 organisations,
+in the middle stages of a release, for deciding which code will be included in the release,
+in the late stages for marshalling the VOTEs required for formal approval
+then finally for <a href="#glossay-cutting-release">cutting the release</a>.
+TODO: maybe be better in a time line
+        </p>
+</div>
+           <h2><img src="/images/redarrow.gif" />
+   <a name="check-list">Check List</a>
+</h2>
+<div class="section-content">
+<p>
+<strong>Note</strong> this is not intended to replace an understanding of the release process.
+        </p>
+<ul>
+            <li><a href="#glossary-distributions">Distributions</a>
+                <ul>
+                    <li>Check compressed distributions <a href="#best-practice-formats">unpack correctly</a></li>
+                    <li>Check documentation is readable</li>
+                    <li>Check <a href="best-practice-distributing-libraries">distributed libraries</a>
+                    	<ul>
+	                    	<li>Check licenses for libraries are distributed together with any applicable 
+	                    	<a href="best-practice-notice">NOTICEs</a> TODO: link</li>
+                    		<li>Check that licenses comply with incubator policy TODO: link</li>
+                    		<li>Check that licenses comply with project policy TODO: link</li> 
+                    		<li>Check that LICENSE and NOTICE documents contain required sections</li>
+                    		<li>Check that any cryptographic dependencies satisfy export regulations</li>
+                    	</ul>
+                    </li>
+                    <li>Check copyright notices:
+                    	<ul>
+	                    	<li>Licences missing from source files</li>
+	                    	<li>Source files with other licenses which are not mentioned in LICENSE</li>
+	                    	<li>Check current policy on headers that all comply</li>
+                    	</ul>
+                    </li>
+                </ul>
+            </li>
+            <li><a href="#glossary-artifact">Distributed Artifacts</a>
+                <ul>
+                    <li>Check <a href="#license">LICENSE</a> and <a href="#notice">NOTICE</a> files.</li>
+                </ul>
+            </li>
+            <li><a href="#glossary-source-distribution">Source Distribution</a>
+            	<ul>
+            		<li>Check build instructions exist and that source <a href="#best-practice-source-build">builds</a>
+            		using these instructions</li>
+            		<li>Check <a href="glossary-license-headers">license headers</a> 
+            		are <a href="notes-license-headers">correctly applied</a></li>
+            		<li>Check for <a href="#best-practice-source">version control</a> files</li>
+            		<li>Check that source is exported from tag</li>
+            	</ul>
+            </li>
+         	<li>OpenPGP keys
+         		<ul>
+         			<li>Check KEYS file contains signing key</li>
+         			<li>Check key has been uploaded to regular public key servers</li>
+         		</ul>
+         	</li>
+        </ul>
+</div>
+           <h2><img src="/images/redarrow.gif" />
+   <a name="rules">Rules</a>
+</h2>
+<div class="section-content">
+<p>
+        TODO release votes by pmc, legal rules (licenses of distributed dependencies, source licenses, LICENSE, NOTICE), 
+        infrastructure rules(signing). Use links so information is maintained 
+        in only one place.
+        </p>
+<h3>
+   <a name="naming"></a>
+</h3>
+<div class="section-content">
+<p>
+            TODO: incubator rules
+            </p>
+</div>
+</div>
+           <h2><img src="/images/redarrow.gif" />
+   <a name="release-guidelines">Release Guidelines</a>
+</h2>
+<div class="section-content">
+<p>
+In addition to policy, the infrastructure, public relations and legal teams also
+document <a href="#glossary-guidelines">guidelines</a> for projects.
+There are almost certainly good reasons why a project should follow
+these guidelines but they have not been blessed as policy.
+    	</p>
+<p>
+Guidelines change much more frequently than policy. Release managers should follow the appropriate
+lists (TODO: create list of useful mailing lists).
+    	</p>
+</div>
+           <h2><img src="/images/redarrow.gif" />
+   <a name="best-practice">Best Practice</a>
+</h2>
+<div class="section-content">
+<h3>
+   <a name="best-practice-jars">Jars</a>
+</h3>
+<div class="section-content">
+<ul>
+                <li><code>META-INF</code>
+                    <ul>
+                        <li>
+    Should include <a href="#license">LICENSE</a> and <a href="#NOTICE">NOTICE</a>. 
+    Note <a href="#distributing-jars">this</a>
+                        </li>
+                        <li>
+    Should include a standards compliant MANIFEST. Note <a href="#jar-manifest">this</a>.
+                        </li>
+                    </ul>
+                </li>
+            </ul>
+</div>
+<h3>
+   <a name="best-practice-naming">Artifact Naming</a>
+</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>
+   <a name="best-practice-types">Distribution Types</a>
+</h3>
+<div class="section-content">
+<p>
+ TODO: glossay - distribution type: based on the same tagged source built  
+ TODO: Common Types of distribtuion
+ 			</p>
+<p>
+ The source distribution is canonical. Every release should create a source distribution.
+ compiled languages may also wish to create binary releases. these may be platform specific.
+ some project may also convenience types which package the project for particular containers.
+        	</p>
+<p>
+ All types of distribution ship as <a href="best-practice-formats">compressed artifacts</a>.
+ This means a distribution type may be shipped as multiple compressed artifacts.
+        	</p>
+</div>
+<h3>
+   <a name="best-practice-downstream">Downstream Packagers</a>
+</h3>
+<div class="section-content">
+<p>
+ TODO: glossay - 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 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>
+   <a name="best-practice-source">Source Distributions</a>
+</h3>
+<div class="section-content">
+<p>
+        	TODO: describe what a source distribution is; version control for distributions; 
+        	add content to release documents; export not checkout
+        	</p>
+<p>
+ Many would argue that for open source projects, the source distribution is the release:
+ binaries are just for convenience. There are some pragmatic (as well as philosophical)
+ reasons why a source distribution should be issued:
+        	</p>
+<ul>
+        		<li>Downstream packages usually prefer to work from a source distribution.
+        		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 distributions encourages developers to modify the code base. Recruiting
+new developers is vital for the long term health of an Apache project.
+				</li>
+        	</ul>
+</div>
+<h3>
+   <a name="best-practice-binary">Binary Distribution</a>
+</h3>
+<div class="section-content">
+<p>
+A binary distribution is any distribution that is not an exported snapshot of the source.
+Binary distributions may include source. For some projects, this makes sense.
+For others, it does not.
+        	</p>
+</div>
+<h3>
+   <a name="best-practice-documentation">Release Documentation</a>
+</h3>
+<div class="section-content">
+<p>
+Users expect <a href="glossary-release-documentation">release documentation</a> 
+to be present in the root directory of the distribution. 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 distribution</a>
+including source distributions.
+So the master documents should be checked into the base subversion directory.
+        	</p>
+<p>
+TODO: rewrite to be topic centric.
+* project status. DISCLAIMER or STATUS 
+Incubating projects should ensure that either contain the STATUS document describing. TODO: check this
+        	</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 tool (for example maven) to collect this information automatically.
+A third is for the release manager to collect all the information required
+when the release is made. The disadvantage of this method is that increases
+the work required to create a release.
+			</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
+ (TODO: maven) or included in the RELEASE NOTES. svn log can be used to collect changes.
+  This is a good opertunity 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 tool) 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>
+   <a name="best-practice-status">STATUS document</a>
+</h3>
+<div class="section-content">
+<p>
+TODO: check this TODO: the STATUS document should be checked to ensure that it is up to date
+before release. Incubator releases should do a <a href="#best-practice-audit">legal audit</a> 
+before releasing. The legal STATUS of the codebase should be clean before it is released.
+        	</p>
+</div>
+<h3>
+   <a name="best-practice-license">LICENSE and NOTICE</a>
+</h3>
+<div class="section-content">
+<p>
+Apache projects may distribute artifacts and documents as part of a release
+which are not Apache Licensed. TODO link to policy. 
+        	</p>
+<p>
+The artifacts and documents to which each subsidary clause applies should be 
+indicated in the document. This <a href="examples/LICENSE">LICENSE</a>
+(curtous of <a href="http://httpd.apache.org">Apache HTTPD</a>) is a
+good example. The Apache License is at the top of document. The explaination
+is clear and the files to which the licenses apply are clearly noted.
+        	</p>
+</div>
+<h3>
+   <a name="best-practice-audit">Legal Audit</a>
+</h3>
+<div class="section-content">
+<p>
+ It is of particular importance that released code is clean. 
+ It is good practice to check the provinance of any source documents 
+ which do not have license headers. Check that dependencies (and in particular
+ those dependencies that ship in the distribution) comply with Apache policy.
+ Legal policy and interpretation changes from time to time so it is worth investing

[... 1036 lines stripped ...]


---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@incubator.apache.org
For additional commands, e-mail: cvs-help@incubator.apache.org


Mime
View raw message