incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mar...@apache.org
Subject svn commit: r1369717 [2/2] - /incubator/public/trunk/content/guides/release-java.xml
Date Mon, 06 Aug 2012 03:31:49 GMT

Copied: incubator/public/trunk/content/guides/release-java.xml (from r1369703, incubator/public/trunk/content/guides/releasemanagement.xml)
URL: http://svn.apache.org/viewvc/incubator/public/trunk/content/guides/release-java.xml?p2=incubator/public/trunk/content/guides/release-java.xml&p1=incubator/public/trunk/content/guides/releasemanagement.xml&r1=1369703&r2=1369717&rev=1369717&view=diff
==============================================================================
--- incubator/public/trunk/content/guides/releasemanagement.xml [utf-8] (original)
+++ incubator/public/trunk/content/guides/release-java.xml [utf-8] Mon Aug  6 03:31:49 2012
@@ -21,586 +21,19 @@ limitations under the License.
 <document>
   <properties>
     <atom url="http://mail-archives.apache.org/mod_mbox/incubator-general/?format=atom">general@incubator.apache.org Archives</atom>
-    <title>Apache Incubator: Release Management (DRAFT)</title>
+    <title>Apache Incubator: Java-specific Release Management Issues (DRAFT)</title>
   </properties>
   <body>
-    <section id='intro'><title>A Guide To Release Management During Incubation (DRAFT)</title>
+    <section id='intro'><title>Java-specific Release Management Issues (DRAFT)</title>
           <section id='TOC'><title>Contents</title><toc/></section>
-            <section id="status">
-          <title>Status - DRAFT</title>
-          <p>
-This document is under active <a href='#help-wanted'>development</a>. This is a first 
-draft intended to allow public review. 
-          </p>
-        </section>
-        <section id="abstract">
-            <title>Abstract</title>
-            <p>
-This document is descriptive, not normative. It aims to guide podlings through the process of release management.
-For a normative reference, instead see <a href="http://www.apache.org/dev/release.html">this FAQ</a> covering
-foundation-wide release policy.
-            </p>
-            <p>
-This document 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="&root-path;/incubation/Incubation_Policy.html#Releases">policy</a>. 
-            </p>
-        </section>
-        <section id='apache-releases'><title>Apache Releases</title>
-        <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>
-        </ul>
-        <p>
-Releases at Apache involve more ceremony than many other processes. Poor quality releases reflect badly
-not only on the project but also the foundation as a whole. 
-        </p>
-		</section>
-		<section id='organisation'><title>Organization</title>
-			<p>
-        This document is a collection of information related to best-practices for releases.
-        It is intended to serve as reference material for release managers, particularly those
-        conducting Incubator releases.  Don't worry, it isn't currently organized to be read
-        in its entirety in a single sitting.  Just skim through the top menu looking for relevant
-        bits of information to consume as time permits.  Come back often, as the contents are
-        always subject to change.
-			</p>
-            <section id='document-usage'><title>Usage</title>
-            <p><strong>NOTE</strong> beta quality TODO: Improve PROSE, check content</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><p>
-        The minimum that Podlings need to demonstrate is to understand this policy in practice.
-        In practice, Podlings should expect to be held to a higher standard. Apache projects
-        care about creating high quality releases. Releases are approved by an Incubator PMC VOTE. In order 
-        to achieve positive votes, qualities higher than just this minimum are usually required.
-        The actual practical level tends to vary as each voter applies their own subjective criteria.
-            </p><p>
-        This document is descriptive not normative. It describes best practices. Policy is defined
-        elsewhere. Podlings are free to accept or reject any of the recommendations. Enquiries may 
-        be expected about novel or unusual practices. Best practice evolves. New ideas may be patched
-        in. 
-            </p><p>
-        This document introduces terminology in common use at Apache but perhaps a bit unfamiliar to
-        people new to the organization.  Please skim the <a href='#glossary'>glossary</a> first for
-        definitions of the more commonly-used terms: artifact, source package, binary package,
-        distribution, release, and release manager.
-            </p>
-            </section>
-		</section>
-        <section id='help'><title>Help Wanted!</title>
-    <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>
-    </section>
-    <section id='references'><title>References</title>
-        <p>
-        TODO: links to project management books.
-        </p>
-        <ul>
-          <li>Apache <a href='http://www.apache.org/dev/#releases'>Release Management</a></li>
-        </ul>
-    </section>
-    </section>
-    <section id='guidelines'><title>Guidelines</title>
-        <!-- 
-    	<p>
-  TODO: may need to think about this title. The idea is to try to clearly separate guidelines
-  about release processes and procedures from rules and guidelines.
-    	</p>
-    	<section id='process'><title>Release Process</title>
-    		<p>
-The minimal formal requirements for an official ASF release are (contrary to rumor) minimal.
-A successful binding VOTE by a project means that the artifact is an official ASF release.
-Releases approved by a podling must comply with the current ASF release policies.
-Those with binding votes must check that the release complies with these policies.
-    		</p>
-    		<p>
- In practice, most projects adopt more ceremony than this minimum for a number of important reasons. 
- 			</p>
- 			<p>
-ASF releases are often widely distributed and long lived. This document is not normative.
-It should not be seen as a recipe for definitive ASF releases. It is
-strongly recommended that podlings create their own release guidelines. Hopefully the incubator documentation
-may help to shorten the process of creating good release guidelines for the podling by providing 
-options, highlighting issues and providing templates.
-        </p>
-        <p>
-There is great variety amongst existing Apache project. Diversity is good. 
-        </p>
-        <p>
-There is inevitably a conflict between the excellent advice to release often and the documentation
-required to create good releases.
-        </p>
-        <ul>
-            <li>
-        ASF releases are high visibility and long lived. A release manager may find that a 
-        poor quality release may be held up as an example for years to come.
-            </li>
-            <li>
-        TODO: legal consequences
-            </li>
-        </ul>
-        <p>
-A podling should have a release guide. A good starting point (once this document has been read)
-is release guides for existing projects:
-        </p>
-        <ul>
-        	<li><a href='http://httpd.apache.org/dev/release.html'>HTTPD</a></li>
-        	<li><a href='http://jakarta.apache.org/commons'>Jakarta Commons</a></li>
-        	<li><a href='http://struts.apache.org/releases.html'>Struts</a></li>
-        </ul>
- <p>Please also check the <a href="http://www.apache.org/dev/release.html">Apache Release guidelines</a>
- in particular the <a href="http://www.apache.org/dev/release.html#license">license requirements</a>.
- Also you might find it useful to read some of the
- <a href="http://wiki.apache.org/general/ReleaseGuides">release guides</a> from other projects.
-</p>
-        <p>
-Most projects find it difficult to issue quality releases without appointing a 
-<a href='glossary-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 organizations,
-in the middle stages of a release, for deciding which code will be included in the release,
-in the late stages for marshaling the VOTEs required for formal approval
-then finally for <a href='#glossary-cutting-release'>cutting the release</a>.
-TODO: maybe be better in a time line
-        </p>
-       -->
     </section>
     
-    <section id='managing subversion'><title>Managing Your SVN Tree</title>
-      <p>
-        Leo Simons has written an excellent
-        <a href="http://lsimons.wordpress.com/2010/02/19/using-long-lived-stable-branches/">blog entry</a>
-        on this subject.  Do read it!
-      </p>
-    </section>
-
     <section id='release-distribution'><title>Distributing Releases</title>
-      <p>
-      Once a release has been approved by the 
-      <a href="&root-path;/incubation/Roles_and_Responsibilities.html#Incubator+Project+Management+Committee+%28PMC%29">Incubator PMC</a>,
-      it needs to be uploaded to the servers for wider distribution. A description of this process and the policy
-      governing it follows.
-      </p>
-        
-      <div class="alert-message block-message warning">
-         <p><strong>Attention!</strong>
-             Sometimes you <a href="http://www.apache.org/dev/release#heads-up">need to talk to Infra</a> before 
-             distributing a release, esp. when your release artifacts are huge.
-         </p>
-     </div>
     <!--
     TODO:                
         Maven: 
           Stop ignoring the elephant
        -->
-      <section id='distribution-policy-overview'><title>Policy Overview</title>
-        <p>
-        Distribution policy with regard to releases is simple:
-        </p>
-        <ul>
-        <li>
-        The Incubator 
-        <a href="&root-path;/incubation/Incubation_Policy.html#Releases">insists</a> 
-        that artifacts for <em>{podling}</em> are contained within
-        <code>www.apache.org/dist/incubator/{podling}</code>. 
-        </li>
-        <li>
-        Infrastructure insists that releases are mirrored, permissions are correct and that
-        <a href='http://www.apache.org/dev/release-signing.html#keys-policy'>signatures+checksums</a> 
-        are uploaded for every artifact. 
-        </li>
-        </ul>
-        <p>
-          All non-release software distributions (e.g. links to the subversion repository, automated builds, etc.)
-          are reserved for folks participating in product development on the project's developer list.
-          See <a href='http://www.apache.org/dev/release.html#release-typeso'>this description</a> for details
-          on the policy.
-        </p>
-        <p>
-        The rest is up to the community to decide and that's quite a lot. 
-        Documenting the release management processes is important and often neglected. 
-        It is 
-        <a href='#document-usage'>strongly
-        recommended</a> that the rest of this section is used as the basis for a written release
-        guide for the podling.
-        </p>
-      </section>
-      <section id='understanding-distribution'><title>Understanding Release Distribution</title>
-        <section id='understanding-upload'><title>Uploading Artifacts</title>
-          <p>
-          The distribution upload location (<code>www.apache.org/dist</code>) for all Apache projects is the
-          <code>/www/www.apache.org/dist</code> directory on <code>people.apache.org</code>.
-          Each project (including the Incubator) owns a directory within <code>dist</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 uploaded into the podling distribution directory
-          using <a href='http://www.apache.org/dev/user-ssh.html'>scp</a>. It is best
-          to <code>scp</code> into the home directory and then copy into position from there.
-          </p>
-        </section>
-        <section id='understanding-mirroring'><title>Mirroring</title>
-          <p>
-          To avoid excessive use of bandwidth and to increase download speeds,
-          official releases are made available through a 
-          <a href='http://www.apache.org/mirrors/'>global network</a> of 
-          <a href='http://www.apache.org/info/how-to-mirror.html'>volunteer mirrors</a>.
-          Using these mirrors has some notable
-          <a href='http://www.apache.org/dev/mirrors.html'>differences</a> from unmirrored
-          downloads. 
-          In particular, a <a href='http://www.apache.org/dev/release-download-pages.html'>script</a> 
-          must be used to direct the download to an appropriate URL. 
-          </p><p>
-          Users will download the mirrored release artifacts from machines outside Apache control.
-          Users need to verify that the copy downloaded is identical to the original.
-          Mirrored copies of checksums, <code>KEYS</code> and signature files 
-          (<code>.asc</code> and <code>.md5</code> files) will be present on the
-          mirrors but must <strong>never</strong> be used for verification. So, all links 
-          from the podling website to signatures, sums and <code>KEYS</code> need to refer 
-          to the original documents on <code>www.apache.org</code>.
-          See <a href='http://www.apache.org/dev/release-signing.html'>release signing guide</a> for more information.
-          </p>
-        </section>
-        <section id='understanding-archiving'><title>Archiving</title>
-          <p>
-          All Apache releases form an important part of the history of a project.
-          They are therefore archived with the aim of preserving them indefinitely
-          for future reference. 
-          <p></p>
-          <a href='http://archive.apache.org'>http://archive.apache.org</a>
-          is the archive host. Releases are archived under 
-          <a href='http://archive.apache.org/dist'>http://archive.apache.org/dist</a>.
-          Please remember that these archives are served from Apache bandwidth. Anyone 
-          who wants to obtain a large quantity of data from the archives should 
-          contact the
-          <a href='http://www.apache.org/foundation/how-it-works.html#infrastructure'>Infrastructure Team</a>.
-          </p><p>
-          All artifacts within <code>www.apache.org/dist</code> will be automatically
-          archived. When a new artifact is uploaded, it will be sync'd to the archive.
-          The sync'ing is scheduled to operate several times a day. So it may be some
-          hours before an added artifact is archived.
-          </p><p>
-          When an (archived) artifact is deleted from the live distribution, it will
-          remain in the archives. See 
-          <a href='http://www.apache.org/dev/release.html#how-to-archive'>how to archive</a>.
-          </p>
-        </section>
-        <section id='understanding-security'><title>Security</title>
-          <section id='distribution-permissions'><title>Permissions</title>
-            <p>
-        One group is created by infrastructure for each top level project. All releases 
-        by the project should be owned by that group. This group should have read
-        and write permissions. This ensures that each project can manage its own releases. 
-        The world should have only read only permissions to avoid accidental modification.
-        In short <code>-rw-rw-r--</code>.
-            </p><p>
-        Each podling release is a release of the Incubator project. So, all files should 
-        be:
-            </p>
-            <ul>
-        <li>owned by the <code>incubator</code> group</li>
-        <li>be group writable</li>
-        <li>be read only for the world</li>
-            </ul>
-            <p>
-        To do this from the top level:
-            </p>
-            <source>
-        > find . -type f -exec chmod 664 {} \;
-        > find . -type d -exec chmod 775 {} \;
-        > chgrp -R incubator *
-            </source>
-            <p>
-        When a podling graduates to a top level project, a new group will be created. 
-        New releases will then use that group (as well as being located in a subdirectory 
-        of <code>dist</code> rather than <code>dist/incubator</code>).
-        If a podling graduates as a subproject then the group of its new parent project
-        will then be used.
-            </p>
-          </section>
-          <section id='distribution-checksums-sigs'><title>Sums And Signatures</title>
-            <p>
-        Start by reading the <a href='http://www.apache.org/dev/release-signing.html'>guide</a> 
-        and <a href='http://www.apache.org/dev/release-signing.html#policy'>policy</a>. 
-            </p><p>
-        Sums are a convenient and simple way for users to verify releases.
-        Signatures play a critical role in ensuring security for releases. 
-            </p><p>
-        If a release is signed by a key that is strongly connected to the 
-        <a href='http://www.apache.org/dev/release-signing.html#web-of-trust'>Apache web of trust</a>
-        then it can be <a href='http://www.apache.org/dev/release-signing.html#web-of-trust'>verified</a> 
-        (by anyone with access to that web of trust) that a file has not been modified 
-        (by anyone without access to the corresponding private key). This allows the infrastructure
-        team to check that releases have not been tampered with. 
-          </p><p>
-        So, it is crucial that new release managers ensure:
-          </p>
-          <ul>
-            <li>that the code signing private key is 
-        <a href='http://www.apache.org/dev/release-signing.html#private-key-protection'>kept safe</a>.</li>
-            <li>that the <a href='http://www.apache.org/dev/release-signing.html#keys-policy'><code>KEYS</code></a> 
-            file contains the public key. (Storing public keys in a KEYS file is recommended but is 
-            not policy.)</li>
-         </ul>
-           <p>
-        It is important that the key is 
-        <a href='http://www.apache.org/dev/release-signing.html#apache-wot'>linked</a> 
-        to the Apache <a href='http://www.apache.org/dev/release-signing.html#web-of-trust'>web of trust</a>. 
-           </p><p>
-        Always upload the checksums and signatures at the same time as the artifact.
-        This will ensure no false alarms from the infrastructure team. 
-           </p>
-          </section>
-          <section id='distribution-modifications'><title>Modifications</title>
-            <p>
-        Once an artifact has been uploaded, it must never be modified. Not only is there no
-        guarantee that the modified artifact will be correctly archived or mirrored but
-        a change to an existing artifact is the signature of an attack. 
-            </p><p>
-        This applies only to release artifacts. It's expected that 
-        <code>README'</code>s, <code>NOTES</code>, <code>KEYS</code>, and so on 
-        may be updated.
-            </p>
-          </section>
-        </section>
-      </section>
-      <section id='distribution-check-list'><title>Distribution Check List</title>
-        <ul>
-          <li>Directory is <code>www.apache.org/dist/incubator/<em>podling</em></code></li>
-          <li>Group is <code>incubator</code></li>
-          <li>Permissions are group writable and world read-only</li>
-          <li>All artifacts have matching checksums and signatures</li>
-          <li>Old releases archived</li>
-          <li>Links to <code>KEYS</code>, signature and checksum documents
-          refer to the originals on <code>www.apache.org</code></li>
-        </ul>
-      </section>
-      <section id='distribution-best-practice'><title>Best Practice</title>
-        <section id='distribution-layout'><title>Layout</title>
-          <p>
-            A podling is free to choose a suitable layout for its released
-            artifacts within the 
-            <a href='#glossary-podling-dist'>podling distribution directory</a> .
-            It is recommended that standard layouts (commonly used by other projects) 
-            be studied and that the layout adopted is documented in the podling's 
-            release documentation. The descriptions which follow can be used as a 
-            useful basis for this documentation
-          </p><p>
-            The choice between different layouts is mostly subjective branding.
-            The mirroring and archiving infrastructure should work well
-            with most choices.
-          </p>
-          <section id='distribution-layout-plain'><title>Plain Artifacts</title>
-            <p>
-          All artifacts, checksums and signatures placed directly into the
-          <a href='#glossary-podling-dist'>podling distribution directory</a>.
-          No subdirectories are created. 
-          No <a href='#distribution-release-documentation'>release documentation</a> 
-          is placed within the distribution directory.
-            </p>
-          </section>
-          <section id='distribution-layout-misc'><title>Miscellaneous Documents</title>
-            <p>
-            All files contained in <code>www.apache.org/dist</code> will be mirrored.
-            So, in addition in archives other documents placed in the distribution 
-            directories will be available on the mirrors for casual browsing.
-            </p><p>
-            As is traditional in some communities, some like to add notices 
-            (such as <code>RELEASE_NOTES</code>, <code>README</code> 
-            and <code>CHANGES</code>) for each release. Note that from publicity
-            perspective it may be effective to include this information on the 
-            download page as well as in the release itself.
-            </p><p>
-            The HTTPD runs with fancy indexing enabled. So, creating <code>HEADER.html</code> and
-            <code>FOOTER.html</code> documents allows the text of the index page to be customised.
-            </p>
-          </section>
-          <section id='distribution-layout-structured'><title>A Structured Layout</title>
-            <p>
-            Many projects use structured layouts. For example:
-            </p>
-            <ul>
-              <li><a href='http://www.apache.org/dist/ant/'>Ant</a></li>
-              <li><a href='http://www.apache.org/dist/httpd/'>HTTPD</a></li>
-            </ul>
-            <p>
-            The common theme is that each type of artifact is grouped into a
-            subdirectory. For example, binary packages into <code>binaries</code>
-            and source packages into <code>source</code> (say). 
-            </p>
-            <p>
-            Often symbolic links are created from the root of the project distribution
-            directory to the latest version of each release. This allows scripts or users to
-            easily locate the latest release.
-            </p>
-          </section>
-        </section>
-        <section id='distribution-release-documentation'><title>Release Documentation</title>
-          <p>
-          Many project distribute notices for a release (such as <code>RELEASE_NOTES</code>, 
-          <code>README</code>, <code>CHANGES</code> and so on) in addition to the main
-          compressed archives. This allows users to read them and decide whether they want
-          to download the archive artifacts. 
-          </p><p>
-          There are also some compelling arguments for making the documentation for a release
-          available for browsing online. (Issuing documentation as compressed archives is just
-          another type of distribution and the standard rules for artifacts apply.) This
-          makes support of releases easier and helps users understand which release
-          is most appropriate for them.
-          </p><p>
-          Some projects do exactly this.
-          For example:
-          </p>
-          <ul>
-            <li>HTTPD
-              <ul>
-                <li><a href='http://httpd.apache.org/docs/2.0/'>2.0</a></li>
-                <li><a href='http://httpd.apache.org/docs/2.2/'>2.2</a></li>
-              </ul>
-            </li>
-            <li><a href='http://commons.apache.org/digester/'>Commons Digester</a>
-              <ul>
-                <li><a href='http://commons.apache.org/digester/commons-digester-1.7/apidocs/'>1.7 API</a></li>
-                <li><a href='http://commons.apache.org/digester/commons-digester-1.6/docs/api/'>1.6 API</a></li>
-              </ul>
-            </li>
-          </ul>
-          <p>
-          Online documentation should be archived so that it can be easily recreated.
-          Though using <code>www.apache.org/dist</code> 
-          for these files is convenient and ensures that they are archived, it should not 
-          be used for this purpose. Documentation typically consists of many relatively 
-          small files and so is inefficient to sync. Users will view it using http and so 
-          there is no advantage in these files being distributed to the mirrors. The cost
-          of syncing to the mirrors should therefore be avoided. 
-          </p><p>
-          The best approach is to commit the documentation for a release into subversion. 
-          Then check out into a directory in the website.
-          Generally, checking generated documentation into source control is often 
-          considered bad practise. But it is very suitable for fixing the documentation 
-          for a particular release.
-          </p><p>
-          It would be possible to use the subversion URL directly. However, checking out 
-          into the website space is better from the perspective of server load and website 
-          mirroring. So that is recommended.
-       </p>
-        </section>
-        <section id='archiving-old-releases'><title>Archiving Old Releases</title>
-          <p>
-          Old releases should be archived 
-          (<a href='http://www.apache.org/dev/release.html#how-to-archive'>by deletion</a>) 
-          <a href='http://www.apache.org/dev/release.html#when-to-archive'>promptly</a>. 
-          For podlings, typically all old releases should be archived when a new one
-          becomes available.
-          </p>
-          <p>
-          <code>.htaccess</code> files are sometimes used to redirect live urls to archived releases.
-          Direct links to distributions on <code>www.apache.org</code> bypass the mirroring.
-          They should therefore be discouraged. It is therefore best to save the effort and not
-          offer redirects for archived (mirrored) releases.
-          </p><p> 
-          If a redirect is used then for performance reasons, then a <code>.htaccess</code> in the root 
-          incubator directory should be used.
-          </p>
-        </section>
-        <section id='distribution-mirroring'><title>Mirroring Scripts</title>
-          <p>
-          There are two options:
-          </p>          
-          <ul>
-            <li>Use the 
-            <a href='http://www.apache.org/dev/release-download-pages.html#closer'>generic mirror script</a></li>
-            <li>Create a <a href='http://www.apache.org/dev/release-download-pages.html#custom'>
-            custom script</a> for <a href='http://uima.apache.org/downloads.cgi'>example</a>.</li>
-          </ul>
-          <p>
-          The generic script can be used immediately and requires the minimum of setup.
-          Creating a custom script allows control over the look, feel and content of the
-          download page but requires more initial effort.
-          </p><p>
-        A consequence of mirroring downloads is that the number of downloads cannot be 
-        monitored directly by using 
-        <a href='http://people.apache.org/~vgritsenko/stats/index.html'>hits</a> on the Apache site. 
-        When using a custom script, it may be possible to use a service like
-        <a href='http://www.google.com/analytics/en-GB/index.html'>Google analytics</a> 
-        to gain a reasonable estimate. 
-          </p><p>
-          It is important that users verify releases. Apache has no control 
-          over the integrity of releases on mirrors.  
-          </p><p>
-          It is recommended that the download page is used to remind users that they
-          need to verify releases and to give instructions on how they can do this.
-          Links provided to checksums and signatures need to refer to the originals on
-          <code>www.apache.org</code> and not the copies on the mirrors. More
-          information can be found in the 
-          <a href='http://www.apache.org/dev/release-signing.html'>signing guide</a>.
-          </p>
-        </section>
-        <section id='distribution-signing'><title>Signatures</title>
-          <p>
-          Understand the <a href='http://www.apache.org/dev/release-signing.html'>guide</a>.
-          See <a href='#signing'>signing best practice</a>.
-          </p>
-          <p>
-          Each podling should maintain its own 
-          <a href='http://www.apache.org/dev/release-signing.html#keys-policy'>KEYS</a> 
-          file directly in the <a href='#glossary-podling-dist'>podling distribution directory</a>. 
-          It is recommended that all committers add their keys to that file.
-          </p>
-        </section>
-        <section id='distribution-defects'><title>Dealing With A Defect</title>
-          <p>
-        Once an artifact has been uploaded, it must never be modified. No matter how 
-        serious a defect is discovered, the right action is to roll a new
-        one with a new number. 
-          </p><p>
-        Very serious defects may necessitate the withdrawl of a release. This should be done
-        by: 
-          </p>
-          <ol>
-          <li><a href='http://www.apache.org/dev/release-publishing.html#archive'>Archiving</a> the
-          release (so that it is no accessible from <code>www.apache.org/dist</code>). 
-          It may be some hours before an artifact added is archived.
-          Check that
-          <code>archive.apache.org/dist</code> contains the archived release before deleting 
-          the original.
-          If necessary, use a temporary <code>.htaccess</code> to prevent access during this period.
-          </li>
-          <li>Posting a suitable announcement (to the same lists that received the original)</li>
-          <li>Adding a suitable notice to the download page</li>
-          </ol>
-        </section>
         <section id='distributing-eclipse'><title>Eclipse Update Site</title>
           <p>
           Podlings may distribute suitable artifacts through an 
@@ -632,203 +65,19 @@ TODO: maybe be better in a time line
           
           -->
         </section>
-      </section>
     </section> 
-    
-    <section id='check-list'><title>Check List</title>
-        <p>
-<strong>Note</strong> this is not intended to replace an understanding of the release process.
-        </p>
-        <ul>
-            <li><a href='#glossary-packages'>Packages</a>
-                <ul>
-                    <li>Check that compressed artifacts <a href='#best-practice-formats'>unpack correctly</a></li>
-                    <li>Check that the 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>Licenses 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>
-                    <li>Check incubator requirements
-                    	<ul>
-                    		<li>Check <a href='#notes-disclaimer'>disclaimer</a> is distributed TODO: link</li>
-                    		<li>Check <a href='#best-practice-status'>status document</a></li>
-                    	</ul>
-                    </li>
-                </ul>
-            </li>
-            <li><a href='#glossary-source-package'>Source Package</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>
-    </section>
-    <section id='rules'><title>Rules</title>
-        <p>
-Every incubator release is also an Apache release. So Apache policy must be followed. 
-Incubator policy is additional and builds on these rules. 
-        </p><p>
-Release managers for podlings
-need to read the <a href='http://www.apache.org/dev/index.html#releases'>release</a>
-and <a href='http://www.apache.org/legal'>legal</a>
-documentation on the main <a href='http://www.apache.org'>Apache site</a>. 
-        </p>
-        <p>
-A few important topics are discussed below. These are a supplement and not a substitute 
-for the Apache documentation.
-        </p>
-        <section id='signing'><title>Signing</title>
-         <p>
- The release manager need to create a
- <a href='http://www.apache.org/dev/release-signing.html#sign-release'>signature</a>
- for every artifact released. It only takes a little time to create a key and the process
- is reasonably straight forward.
-        </p>
-        <p>
-However, it is recommended that enough time is taken to gain a basic understanding of the 
-public key cryptography.
-Read the <a href='http://www.apache.org/dev/release-signing.html'>Apache Signing Guide</a>
-and at least some of the background material linked from it.
-            </p>
-            <p>
- See:
-            </p>
-            <ul>
-                <li>
-<a href='http://www.apache.org/dev/release-signing.html'>Apache Signing Guide</a>
-                </li>
-            </ul>
-        </section>
-        <section id='naming'><title>Naming</title>
-            <p>
-Apache releases should contain the full name of the project responsible for the release. This ensures that
-trademark law can be used against others issuing artifacts with the same name. 
-             </p>
-             <p>
-For example, one good name for product bar Apache Foo Project would be <code>apache-foo-bar</code>.
-            </p>
-            <p>
-Once a podling graduations, it should adopt this naming convention. 
-Whilst in the incubator, practice is a little different.
-The release name should contain the podling name and may contain apache. 
-Incubator policy insists that it must also contain <code>incubating</code> (though small variations 
-for the sake of readability are usually acceptable). 
-            </p>
-             <p>
-For example, for podling foo, both <code>apache-foo-incubating</code> and 
-<code>foo-incubating</code> would be acceptable names. 
-            </p>
-            <p>
- See also:
-            </p>
-            <ul>
-                <li>
- <a href="&root-path;/incubator/Incubator_Policy.html">Incubator Policy</a>
-                </li>
-                <li>
- <a href='branding.html'>Incubator Branding Guide</a>
-                </li>
-            </ul>
-        </section>
-        <section id='release-legal-audit'><title>License Audit</title>
-            <p>
-Incubator policy <a href="&root-path;/incubation/Incubation_Policy.html#Releases">requires</a> that 
-all incoming code is fully signed off before any release. This simply reinforces the Apache 
-requirements: all code must have appropriate licenses. 
-Potential liability for released code is greater than for unreleased code.
-So, it is of particular importance that this is true of all released code. 
-            </p>
-            <p>
- The process of preparing a release should include an audit of the code to ensure
- that all files have appropriate headers and that all dependencies complies with
- <a href='http://www.apache.org/legal/3party.html'>Apache policy</a>. 
- The release build also needs to be check
- to ensure that the LICENSE and NOTICE files are included in every released artifact.
-            </p>
-            <p>
- See:
-            </p>
-            <ul>
-                <li><a href='http://www.apache.org/legal/src-headers.html'>Header for source files</a></li>
-                <li><a href='http://www.apache.org/legal/3party.html'>Policy for dependencies</a></li>
-                <li><a href='http://www.apache.org/dev/release.html'>Release policy and FAQ</a></li>
-           </ul>
-        </section>
-    </section>
+
     <section id='release-guidelines'><title>Release Guidelines</title>
     	<p>
-In addition to policy, the infrastructure, public relations and legal teams also
-document <a href='#glossary-guidelines'>guidelines</a> for projects.
-There are almost certainly good reasons why a project should flow
-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. Subscribe to:
     	</p>
         <ul>
-            <li><em>legal-discuss</em> for matters related to licensing</li>
             <li><em>repository</em> for matters related to the maven repositories</li>
-            <li><em>infrastructure-issues</em> for matters related to </li>
         </ul>
     </section>
+    
     <section id='best-practice'><title>Best Practice</title>
-    	<section id='best-practice-preparation'><title>Preparation</title>
-            <p>
-Preparation is the key to quality. The <a href='#glossary-release-manager'>release manager</a>
-will need to organise and coordinate this but need not execute all.
-            </p>
-			<ul>
-				<li>Analyze <a href='#best-practice-prepare-documentation'>bugs</a></li>
-				<li>Check <a href='#best-practice-prepare-documentation'>documentation</a></li>
-			</ul>
-    	</section>
-    	<section id='best-practice-bugs'><title>Bugs</title>
-    		<p>
-The list of open issues needs to be analyzed. The community needs to decide which 
-issues could be resolved for this release and how much energy the community
-has to deal with these. Time may also become a factor: some issues which 
-cannot be resolved promptly may need to be postponed.
-    		</p>
-    		<p>
-Issue tracking system can be used to help this process especially for complex projects 
-with many open issues. Each open issues should be analyzed and marked appropriately.
-An accurate view of those bugs which are targeted for the upcoming release helps
-to concentrate community effort. Consider asking reporters to donate unit tests.
-    		</p>
-    	</section>
-    	<section id='best-practice-prepare-documentation'><title>Preparing Documentation</title>
-    		<p>
-Any documentation that the release contains should be proof-read and spell checked.
-This is obviously something that needs to happen after the content is finalized.
-So typically, the release manager needs to coordinate the documentation effort.
-A release is a good time to concentrate energy on documentation.
-    		</p>
-    	</section>
         <section id='best-practice-jars'><title>Jars</title>
             <ul>
                 <li><code>META-INF</code>
@@ -850,203 +99,8 @@ A release is a good time to concentrate 
             with the same name)
         	</p>
         </section>
-        <section id='best-practice-types'><title>Package Types</title>
-        	<p>
- TODO: glossary - distribution type: based on the same tagged source built  
- TODO: Common Types of distribution
- 			</p>
- 			<p>
- The source package is canonical. Every release must revolve around a source package.
- Compiled languages may also wish to create binary packages. These may be platform specific.
- Some projects may issue builds (ie binary packages) which package the project for
- particular containers.
-        	</p>
-        	<p>
- All types of packages ship as <a href='best-practice-formats'>compressed artifacts</a>.
- This means multiple packages may be shipped as various compressed artifacts (eg tar.gz and .zip).
-        	</p>
-        </section>
-        <section id='best-practice-downstream'><title>Downstream Packagers</title>
-        	<p>
- TODO: glossary - downstream packager: takes an apache release and packages it for a particular platform.
- TODO: best practice is to work with downstream packagers and link to their packages
- rather than roll their own packages. Need to add notes that these are not official releases.
- TODO: link to notes on working with downstream packagers
-        	</p>
-        	<p>
-TODO: write up gentoo wiki on good upstream. google for other distros.
-        	</p>
-        </section>    
-        <section id='best-practice-source'><title>Source Package</title>
-        	<p>
-        	TODO: describe what a source package is; version control for source packages; 
-        	add content to release documents; export not checkout
-        	</p>
-        	<p>
- Many would argue that for open source projects, the source package is the release:
- binaries are just for convenience. There are some pragmatic (as well as philosophical)
- reasons why a source package should be issued:
-        	</p>
-        	<ul>
-        		<li>Downstream packages usually prefer to work from an Apache source package.
-        		Typically, they will patch the source both to apply fixes and to add elements
-        		of their own build system. Being a good upstream encourages wider
-        		distribution and use of the project.
-        		</li>
-        		<li>
-Source packages encourage developers to modify the code base. Recruiting
-new developers is vital for the long term health of an Apache project.
-				</li>
-        	</ul>
-        	<p>
-It is required that source packages are included in every release.
-Many packagers (for example, FreeBSD and linux distributions) prefer or demand
-to work from source releases. Archivists prefer source. Many large organizations
-prefer to verify and then build their own versions from source. A source package
-is easy to create but helps to reach these audiences.
-        	</p>
-        </section>
-        <section id='best-practice-binary'><title>Binary Package</title>
-        	<p>
-A binary package is any package that is not an exported snapshot of the source.
-Binary packages may include some source code. For some projects, this makes sense.
-For others, it does not.
-        	</p>
-        </section>
-        <section id='best-practice-documentation'><title>Release Documentation</title>
-        	<p>
-Users expect <a href='#glossary-release-documentation'>release documentation</a> 
-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>
-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 to (for example maven) to collect this information automatically.
-A third is for the release manager to collect all the information required
-when the release is made. The disadvantage of this method is that increases
-the work required to create a release.
-			</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 opportunity to reinforce the need for good commit messages.
- CHANGES should also include references to bugs fixed (TODO URLS, searches in JIRA or bugzilla).
- Include a description of the build process either in a README or BUILDING document.
- This should include details of the dependencies (both library and to) required to build and run 
- the product but may do so by reference
- CHANGES should note any incompatibilities introduced since the last release.
-        	</p>
-        	<p>
- Remember that the RELEASE_NOTES will be used as a basis for downstream packagers
-  (TODO add links to this in packagers section)
- as well as users. Create a short paragraph explain what the product is. The proposal
- short already include something suitable. Include this description in the RELEASE_NOTES
- and in ANNOUNCEMENTSs (TODO add links to this in announcements section)
-        	</p>
-        </section>
-        <section id='best-practice-status'><title>STATUS document</title>
-        	<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 code base should be clean before it is released.
-        	</p>
-        </section>
-        <section id='best-practice-license'><title>LICENSE and NOTICE</title>
-        	<p>
-Apache projects may distribute artifacts and documents as part of a release
-which are not Apache Licensed.  All such artifacts must comply with Apache's
-<a href='http://www.apache.org/legal/resolved.html'>3rd party licensing policy</a>.
-        	</p>
-        	<p>
-All the licenses on all the files to be included within a package
-should be included in the LICENSE document.  This <a href='examples/LICENSE'>LICENSE</a>
-(courtesy of <a href='http://httpd.apache.org'>Apache HTTPD</a>) is a
-good example. The Apache License is at the top of the LICENSE document.
-After that, the license for each non-Apache licensed component is included,
-along with a clear explanation of which files that license applies to.
-        	</p>
-                <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>
-        </section>
-        <section id='best-practice-audit'><title>Legal Audit</title>
-        	<p>
- It is of particular importance that released code is clean. 
- It is good practice to check the provenance of any source documents 
- which do not have license headers. Check that dependencies (and in particular
- those dependencies that ship in the packages) comply with Apache policy.
- Legal policy and interpretation changes from time to time so it is worth investing
- a little time reading again the legal release material. 
-        	</p>
-        </section>
         <section id='best-practice-formats'><title>Compression Formats</title>
             <p>
-<a href='best-practice-packages'>Packages</a> of all 
-<a href='best-practice-types'>types</a> should be shipped in a compress format
-to minimize bandwidth requirements. 
-			</p><p>
-Though utilities for all major compression formats are available for all major platforms,
-not all platforms support all major compression formats by default. 
-Users find it convenient to download the package compressed in a familiar
-format that is easy to decompress on their platform.
-It is therefore recommended that each type of package is shipped in a variety of
-compressed formats. Ship at least one of tar.gz, bz or bz2 for UNIX and linux (but note 
-<a href='notes-on-compression-formats'>this</a>). 
-Ship zip for windows. 
-			</p><p>
-Some formats are strongly associated with particular platforms. 
-Even when the uncompressed contents have no functional differences,
-this leads to conventional associations between particular compressed artifacts and
-platforms.
-For example, <code>zip</code> with <code>windows</code> and <code>tar.gz</code>
-with <code>UNIX</code> and <code>linux</code>.
-Users often expect this association.
-See <a href='notes-line-endings'>notes</a> on line endings for source packages.
-            </p>
-            <p>
-Different <a href='#best-practice-types'>package types</a> should unpack to 
-directories with different names. This is more convenient for users since:
-			</p>
-			<ul>
-				<li>users who download more than one type do not need to 
-				take action to ensure that unpacked packages do not overwrite each other</li>
-				<li>it allows easy identification of different package types</li>
-			</ul>
-			<p>
-For project, <em>Apache Foo</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 package unpacks should flow
-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 Saris verses GNU tar)
 It is recommend that project that use Ant or Maven as build tools, use these tools to create
@@ -1056,139 +110,16 @@ It is recommended that project which do 
             </p>
         </section>
         <section id='best-practice-source-build'><title>Source Package Build</title>
-        	<p>
-This section applies only to compiled languages.
-        	</p>
-            <p>
-Source packages should contain easy instructions describing how to build the project.
-The source package should build from instructions contained. 
-TODO: best practices for instructing users about building the project.
-            </p>
             <p>
 Build instructions should give supported version numbers for build tools (for example, maven and ant).
             </p>
         </section>
-        <section id='best-practice-dependencies'><title>Dependencies</title>	
-        	<p>
-TODO: information about dependencies is a FAQ. releases should indicate dependencies
-and which are optional and which required. if they are not shipped with the package,
-information should be included about their official home. minimum (and max) supported versions.
-        	</p>
-        	<p>
-dependencies should comply with the current apache policy. TODO: link
-        	</p>
-        	<p>
-TODO: dependencies also include the tools required to build and test the source.
-to dependencies are often included in BUILDING or README
-        	</p>
-        	<p>
-TODO: particularly important for languages. language should be approached
-as dependencies and documented. these should be listed in the README
-or RELEASE NOTEs.
-        	</p>
-        	<p>
-Any changes in dependencies (including dependencies added or removed
-or changes in supported version) should be noted in the change log for this
-release. (Where appropriate) check the that the application is built against 
-the correct versions. Note that this includes platform as well as library
-dependencies.
-        	</p>
-        </section>
         <section id='best-practice-distributing-libraries'><title>Distributing Libraries</title>
             <p>
-TODO: ASF policy compliance
-TODO: project policy - explicit policy should be written down
-            </p>
-            <p>
 TODO: Discussion on the merits of distributing dependent jars. This should be a link to the notes section
             </p>
         </section>
         
-        <section id='best-practice-notice'><title>NOTICE files</title>
-            <p>
-Read <a href='http://apache.org/legal/src-headers.html#notice'>this</a>.
-The <code>NOTICE</code> is important and serves several purposes. 
-The contents should be included in all downstream redistributions.
-            </p>
-            <p>
-The <code>NOTICE</code> documents copyright notices and other required attributions.
-This must include:
-            </p>
-            <ul>
-                <li>the 
-<a href='http://apache.org/legal/src-headers.html#notice'>standard Apache attribution and copyright notice</a></li>
-                <li> 
-<a href='http://apache.org/legal/src-headers.html#header-existingcopyright'>inherited</a> 
-                copyright and attributions notices</li>
-                <li>all attribution and copyright notices required by licenses for 
- <a href='http://apache.org/legal/src-headers.html#3party'>third party documents</a></li>
-             </ul>
-             <p>
-Every contributor retains the copyright to their contributions and grants Apache only a (generous)
-license for the work. A release is an act of selection by the <a href='#glossary-pmc'>PMC</a>. Apache holds the copyright
-to the collective work that is the release. The Apache copyright in the <code>NOTICE</code>
-pertains to the collective.
-             </p>
-             <p>
-It is strongly recommended that the <code>NOTICE</code> contains only these legally
-important contents. The <a href='#notes-disclaimer'>incubator disclaimer</a> is best placed in 
-another document.
-             </p>
-            <p>
-The exact name may be optionally suffixed. For example, both <code>NOTICE</code> 
-and <code>NOTICE.txt</code> are fine.
-            </p>
-        </section>
-        <section id='best-practices-svn'><title>Subversion Best Practices</title>
-        	<p>
-        	TODO: svn is flexible. branches and tags with svn are not the same as with cvs.
-        	</p>
-        	<p>
-All releases should be identified with a tag. It is occasionally necessary to rebuild
-releases many years later, and having a tag easily allows this to be done.
-Tagging is cheap and easy when using subversion.
-So, every release should be tagged. Releases should be built from a tag, 
-or built from a stable branch (not trunk). If not built from a tag, the
-approved release candidate should be tagged.
-        	</p>
-        	<p>
-It is useful to adopt a consistent naming convention for tagging releases.
-This allows release tags to be recognized easily. Typically the tag will be a
-variation on the name of the release. For example, some projects use
-ALL CAPS to indicate release tags in which can apache-foo-1.2 would be tagged
-APACHE_FOO_1_2. 
-        	</p>
-        	<p>
-If <code>svn:externals</code> is used, check carefully that a tag is referenced.
-This ensure that all the source for the release is fixed. If the target of a <code>svn:externals</code>
-changes then the release will no longer be complete reproducible.
-        	</p>
-        </section>
-        <section id='best-practice-reproducability'><title>Reproducibility</title>
-        	<p>
-It is important that any release can be reproduced from the source at any time in the future. 
-Apache releases have long active lives and are permanently archived. 
-It may be necessary (for example, for legal reasons) 
-to provide a new release that is a slight alteration of a previous release.
-Release managers owe it to those who come afterwards to use build processes
-that are reproducible.
-			</p><p>
-The build script should fully capture all the processes necessary to create the release.
-Manual processing (other than creating compressed archives) is a sign that the build
-is not mature enough for a full Apache release.
-        	</p><p>
-The requirements of the build should be fully documented. The versions of tools 
-and platforms used to build the release should be noted.
-        	</p>
-        </section>
-        <section id='best-practice-release-as-advertising'><title>Release As Advertising</title>
-        	<p>
-Releases are a primary form of communication with open source users and potential developers.
-Its useful to think about releases in this way. TODO: what a release says about a projects 
-TODO: link into media relations and announcements (grassroots and mainstream, articles
-on new features, freshmeat, downstream packagers)
-        	</p>
-        </section>
         <section id='best-practice-dependencies'><title>Dependencies</title>
         	<p>
 As well as libraries, projects often have more subtle dependencies.
@@ -1198,115 +129,6 @@ will run are clearly documented. The <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, including those shipped as binary libraries 
-and those shipped as source together with the licenses for
-those dependencies. These lists should be checked against the latest policy documents.
-        	</p>
-        	<p>
-This list should also be used to check for compliance with US export regulations.
-If any dependencies are cryptographic libraries then it may be necessary
-to fill in some <a href='TODO:'>paperwork</a>. 
-        	</p>
-        </section>
-         <section id='announcements'><title>Announcements</title>
-        	<p>
-TODO: release managers should ensure that releases are announced.
-TODO: links to release management FAQs
-TODO: consider grassroots sites eg freshmeat.net
-TODO: link note on press release 
-        	</p>
-        	<p>
-Announcements should be signed by the release manager with the key used to sign the 
-release. Note that this may mean creating a plain text signature on the machine used
-to sign the release and then transferring this.
-        	</p>
-        	<p>
-Announcements should be posted from the release manager's 
-<code>apache.org</code> address.
-        	</p>
-        </section>
-        <section id='best-practice-incubator-release-vote'><title>Incubator Release Vote</title>
-            <p>
-All releases by podlings must be approved by the TODO: link Incubator PMC. The conventional process
-is for the podling to follow the usual Apache process (including TODO: link release vote)
-and then call for a Incubator PMC VOTE on the TODO: link general incubator list.
-            </p>
-            <p>
-The release manager should post the call for the VOTE. 
-            </p>
-            <ul>
-                <li>Links to the release artifacts</li>
-                <li>Links to the PPMC release vote thread</li>
-                <li>Link to the tag from which the release is cut</li>
-            </ul>
-        </section>
-        <section id='best-practice-mailing-lists'><title></title>
-            <p>
-Release managers should subscribe to a number of Apache-wide mailing lists.
-Decisions are taken on these mailing lists and issues resolved.
-Documentation is updated later (if at all). It's important that release
-managers ensure that they keep up to date.
-            </p>
-            <ul>
-                <li>TODO: link General infrastructure list</li>
-                <li>TODO: link Legal discuss list</li>
-            </ul>
-            <p>
-Release managers for incubating podlings should also subscribe to the TODO: link general list.
-            </p>
-        </section>
-        <section id='best-practices-release-candidates'><title>Release Candidates</title>
-        	<p>
-A release candidate is a set of artifacts upon which a vote is held for a release.
-The actual nature of the release candidate depends on the release system
-adopted by a the project.
-			</p>
-			<p>
-Those projects adopting a system of blessing a candidate will start by creating a
-candidate which will then be promoted by a series of votes until it either fails
-or reaches full release status. In this case, the same candidate may
-be known as a release candidate, an alpha, a beta and then a full release.
-Other projects may release alphas and/or betas or developer releases until the
-project has agreed there is sufficient quality in place to make the code available
-as a General Availibility (GA) release.
-        	</p>
-        	<p>
-Those projects which have release candidates will vote on a sample release candidate.
-        	</p>
-        	<p>
-Only formally-approved releases may be distributed from the main directories. 
-There are a number of reasons for this: 
-			</p>
-			<ul>
-				<li>the URL indicates the status of the release</li>
-				<li>the main directory is archived for historical purposes. To conserve space
-				only official release should be archived.</li>
-				<li>syncing too many short lived artifacts use bandwidth</li>
-			</ul>
-			<p>
-TODO: links to infra dev
-        	</p>
-        	<p>
-It is traditional that release managers use their Apache home space to make available
-release candidates. TODO:link to dev instructions on using Apache web space.
-Please remember to delete release candidates after voting concludes.
-        	</p>
-        </section>
-        <section id='signing-releases'><title>Signatures</title>
-        	<p>
- TODO: links to release signing documentation
-        	</p>
-        	<p>
- Ensure that the code signing public key is uploaded to a network in good time.
- It may take some days for keys to propagate to all servers in the network.
-        	</p>
-        	<p>
- Novice signers should read the documentation and practice. Consider using an
- isolated installation to store the code signing key and to sign releases.
-        	</p>
         </section>
         <section id='best-practice-maven'><title>Maven</title>
         	<p>
@@ -1321,243 +143,49 @@ be used upon graduation. The version sho
         	</p>
         	<p>
 For example
-        	</p>
-<code><pre>
-	&lt;groupId&gt;org.apache.wicket&lt;/groupid&gt;
-	&lt;artifactId&gt;wicket-parent&lt;/artifactId&gt;
-	&lt;version&gt;1.3-incubating-SNAPSHOT&lt;/version&gt;
-</pre></code>
-        </section>
-    </section>
-    <section id='notes'><title>Notes</title>
-        <section id='notes-on-licenses'><title>License Issues</title> 
-            <p>
-            TODO: content
-            It is important that the right legal contracts are in place for all source code at Apache
-and that the right process has been followed. For the majority of the time, this
-is easy: committers create original works which are licensed by Apache under
-a CLA or CCLA
-TODO: complete content
-            </p>
-        </section>
-        <section id='notes-disclaimer'><title>The Incubator Disclaimer</title>
-            <p>
-            TODO: the incubator requires that users are informed that the by
-            including a standard disclaimer. may be include in README, RELEASE_NOTES
-            DISCLAIMER. It is recommended that it is not included in NOTICES
-            </p>
-        </section>
-        <section id='distributing-jars'><title>Distributing Jars</title>
-            <p>
-            TODO: link to infrastructure
-            </p>
-            <p>
-Jars are just another form of binary package. If they are likely to be distributed
-(for example, through the Apache Repository) then they must adhere to the same policy
-as other binary packages. In particular, LICENSE and NOTICE files must be distributed.
-            </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>
-        </section>
-        <section id='jar-manifest'><title>Jar MANIFEST</title>
-            <p>
-TODO
-Lots of projects get this wrong and most tools, by default, produce substandard manifests.
-Offer some guidance on values
-TODO: Add how to create a specification compliant MANIFEST 
-http://jakarta.apache.org/commons/releases/prepare.html#checkjarmanifest
-            </p>
-            <p>
-Maven 1 produces a minimal MANIFEST. This should be augmented 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 manifest entries. 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 recommended entries.
-            </p>
-        </section>
-        <section id='best-practice-release-candidate'><title>Release Candidates</title>
-              <p>
-There are two distinct approaches: <a href='#glossary-release-candidate'>release candidate</a> and TODO.  
-        	</p>
-        </section>
-        <section id='best-practice-versioning'><title>Versioning</title>
-        	<p>
-There are several good versioning strategies used by projects at Apache. The version strategy
-adopted is less important than adopting one that is clear and consistent and documenting it.
-If there are strong opinions amongst developers on the right way to version then document this
-strategy. If there are not then time can be saved by adopting an existing strategy with a good
-fit. It is usually better to start by copying the documentation rather than using by reference.
-Strategies sometimes change as do URLs. Project often (in time) find that they need to expand
-or fine tune their versioning strategy and this is hard if another project's documentation is used.
-A project should therefore use their own strategy.
-        	</p>
-        	<p>
- TODO: notes on strategies. 
- 			</p>
- 			<p>
- The most common system of versioning is based on <code>major.minor.point</code>
- where major, minor and point are all integers. Note that these are not decimals and
- there is no necessity to raise a major version number after the minor version has
- reached 9. The exact rules vary and it is recommended that a project agrees and documents
- its own rules. 
-			</p>
- 			<p>
- In addition to an official release with a particular version number, any number of
- unofficial releases of various types may share the same number. These are usually
- terms alphas, beta, release candidates, TODO: link to foundation release documents.
- These release may be designated by adding an appropriate suffix to the release 
- number (for example, 3.11.15RC1). The exact form is not as important as 
- documenting the system adopted by the project and its consistent use. Users
- should be able to predict the status of the release from the artifact and the documentation.
- 			</p><p>
- TODO: (move to a note) Notes on 0.x releases verses alpha and betas. It is better to use <code>0.x</code>
- releases than to create numerous alphas and betas for 1.0. Conventionally, 0.x releases
- are aimed at early adopters only without a strong promise of easy upgrade or backwards
- compatibility. 0.x is a good designation for a product that is not feature complete 
- but whose code is solid for those features which are implemented.
-        	</p>
-        </section>
-        <section id='notes-numbering-between-releases'><title>Version Numbering Between Releases</title>
-        	<p>
-It is useful to use a system of versioning for development (non-release) version numbers that
-allows artifacts built from a development code stream to be distinguished by their version
-from releases. Choose any reasonable and appropriate system but documented it so that
-users understand how to recognize the difference.
-        	</p>
-        	<p>
-There are two major approaches to this problem. Some use a suffix to indicate a development
-stream. Others use a property of the version number (conventionally odd or even).
-        	</p>
-        	<p>
-TODO: odd, even version numbers - research httpd, linux
-        	</p>
-        	<p>
-<code>SNAPSHOT</code> and <code>dev</code> are commonly used suffixes. 
-Typically these are set to the next minor version number in sequence. For example,
-after cutting <code>apache-foo-1.5.6</code>, the version would be 
-<code>1.6</code>. 
-        	</p>
-        </section>
-        <section id='best-practice-unique-names'><title>Unique Artifact Names</title>
-        	<p>
- Every <a href='glossay-artifact'>artifact</a> distributed should have a name that is unique.
- This allows each artifact to the recognized by its name and ensures that different artifacts do not
- overwrite each other. Including <em>apache</em> in the name of the artifact not only gives
- brand recognition but means influence can be exerted over errant downstream repackages 
- by trademark law. If this practice is adopted then the release manager merely has to ensure 
- that each artifact is uniquely named within the set of Apache artifacts. By including the name of 
- the project, each artifact only has to be unique within the artifacts release by the project. When 
- a project distributes several distinct products then the product name should also be included.
-        	</p>
-        	<p>
-For each product, each <a href='best-practice-types'>type of package</a> should be 
-assigned a consistent and unique name. Conventionally, source packages use <code>src</code>
-and main binary packages no prefix. Typically each type of package is made available in a number of 
-<a href='best-practice-formats'>compression formats</a>. These are conventionally distinguished 
-by the usual file type suffix.
-        	</p>
-        	<p>
-So, the traditional format is apache-project-product-type-version.format.
-        	</p>
-        </section>
-        <section id='release-notes'><title>Release Notes</title>
-            <p>
-TODO: rewrite this is section distinguishing between the content and the presentation.
-content may (and probably should) be replicated in many different places.
-The content presented in the RELEASE_NOTES needs to be plain text etc
-            </p>
-        	<p>
-Release notes are a vital to for communication between an open source project 
-and its users. They are often the first documentation a user will read. First
-impressions matter. Their content will often serve as the basis for TODO: link
-announcements and other TODO: link grassroots publicity.
-        	</p>
-            <p>
-The content may be replicated in many places. Use the content as news on the
-project website and as the basis for the download page. Use the content for 
-posting to TODO: link  grassroots media. Use the content for postings to 
-announcement lists.
-            </p>
-            <p>
-The release notes should be in a common and easily read format (plain text is best).
-The release notes should easily located and so should be positioned in the base directory.
-            </p>
-            <p>
-The content can often be edit for use in the announcement.
-            </p>
-            <p>
-TODO: move to best practice?
-            </p>
-            <p>
-TODO: contents
-include a short description of the project and links to the apache site
-            </p>
-            <p>
-Whenever possible, each type of package should ship with release notes.
-The release notes document should therefore be committed to the source
-repository so that it ships with the source package.
-            </p>
-            <p>
-The first paragraph of the release notes should introduce the project and the release.
-It is often useful to characterize the release (TODO examples). Spend time thinking
-about the best organization. Important information should be prominent.
-            </p>
+        	</p>
+<code><pre>
+	&lt;groupId&gt;org.apache.wicket&lt;/groupid&gt;
+	&lt;artifactId&gt;wicket-parent&lt;/artifactId&gt;
+	&lt;version&gt;1.3-incubating-SNAPSHOT&lt;/version&gt;
+</pre></code>
+        </section>
+    </section>
+    <section id='notes'><title>Notes</title>
+        <section id='distributing-jars'><title>Distributing Jars</title>
             <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.
+            TODO: link to infrastructure
             </p>
             <p>
-Any changes which may effect a user who wishes to replace the last version with
-this should be highlighted. In particular, document:
+Jars are just another form of binary package. If they are likely to be distributed
+(for example, through the Apache Repository) then they must adhere to the same policy
+as other binary packages. In particular, LICENSE and NOTICE files must be distributed.
             </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.
+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>
+        </section>
+        <section id='jar-manifest'><title>Jar MANIFEST</title>
             <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.
+TODO
+Lots of projects get this wrong and most tools, by default, produce substandard manifests.
+Offer some guidance on values
+TODO: Add how to create a specification compliant MANIFEST 
+http://jakarta.apache.org/commons/releases/prepare.html#checkjarmanifest
             </p>
             <p>
-Remember that a user may have received the software indirectly. So, include
-some brief details about the project and an url.
+Maven 1 produces a minimal MANIFEST. This should be augmented 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>
-Release notes are important TODO: glossary guerrilla advertising for a project.
-They should provide: 
+Maven 2 produces a much better manifest provided that the POM is reasonably full.
+It does not, by default, include some recommended manifest entries. It is recommended that POM should be
+<a href='http://maven.apache.org/plugins/maven-jar-plugin/examples/manifest-customization.html'>customized</a>
+so that it includes the missing recommended entries.
             </p>
-            <ul>
-            	<li>an introduction for those who don't know the project in 
-detail</li>
-				<li>briefly state the aims of the project</li>
-				<li>briefly indicate the project's roadmap and how this release fits into it</li>
-				<li>list ways to get involved with the project</li>
-				<li>describe how to raise issues</li>
-			</ul>
-			<p>
-This may be included by reference to the main documentation 
-but (for the benefit of those that don't read document) should be mentioned.
-			</p>
         </section>
         <section id='note-compatibility-checkers'><title>Compatibility Checkers</title>
 			<p>
@@ -1574,79 +202,8 @@ Some tools used by Apache projects:
         </section>
         <section id='notes-change-log'><title>Change Logs</title>
         	<p>
-TODO: should this be in best practices
-TODO: add examples
-        	</p>
-        	<p>
-A change log indicates the changes made to the project since the last release.
-Some projects include a change log in the release notes documents.
-Others use a separate document often called <code>ChangeLog</code>.
 Maven can be used to generate a change log as part of the project documentation.
         	</p>
-        	<p>
-Change logs can be created in various ways. Some project ask committers to fill
-in details each time they commit. Other rely on analyzing the commit messages
-when the release is prepared. (To do this, go through the logs since the revision
-of the last release. TODO example)
-        	</p>
-        	<p>
-The change log typically includes every feature added and every bug resolved since 
-the last release.
-        	</p>
-        </section>
-        <section id='notes-signing-releases'><title>Signing Releases</title>
-        	<p>
-TODO: links to dev pages
-batch signing scripts in committers
-        	</p>
-        	<p>
-TODO: consider moving content into foundation docs
-        	</p>
-        	<p>
-OpenPGP compatible signatures must be generated to accompany releases.
-Public key encryption is a deep and wide subject. However, the
-knowledge required to safely create signatures for Apache releases can be
-learnt in a short time. TODO: link to foundation docs
-        	</p><p>
- What can be sometimes confusing is that though a signature is required, 
- connection to the web of trust is only strongly encouraged not required. 
- 			</p><p>
- A signature from a key which is well 
- connected to the Apache web of trust gives greater security than a signature
- that is not. 
- 			</p><p>
- However, the essential use of signatures at Apache is to allow
- release managers themselves to check whether an artifact is identical 
- to the release they created. All that is required in this case is that the 
- release managers knows whether a signature is their own.
-        	</p>   	
-        </section>
-        <section id='note-on-multiple-products'><title>On Multiple Products</title>
-        	<p>
-A project may release a number of distinct products created by the same community.
-TODO: differences between products and packages.
-        	</p>
-        </section>
-        <section id='notes-on-templates'><title>On Template Sources</title>
-        	<p>
-        	TODO: this is probably a best practice
-        	</p>
-        	<p>
-Source files should contain the license header whenever this is reasonable.
-Templates are source documents and so this principle applies to them as well.
-			</p>
-			<p>
-If these templates are used to generate documents which form part of the 
-package then the documents generated should contain the license header.
-        	</p>
-        	<p>
-However, if this template is used by a user to generate output, usually
-this output should be free of license restrictions. Most templating languages
-allow comments which are not included in the output. If this is allowed
-then the license header should be included in the template as a comment.
-If not then consider adding a NOTE or a README to the directory rather 
-than a license header.
-        	</p>
         </section>
         <section id='notes-on-java-version'><title>On Java Versions</title>
         	<p>
@@ -1685,38 +242,13 @@ the appropriate version of the Java API.
 placed.
         	</p>
         </section>
-        <section id='notes-on-export-regulations'><title>On Export Regulations</title>
-        	<p>
-TODO preamble TODO link to legal
-        	</p>
-        </section>
-        <section id='notes-on-compression-formats'><title></title>
-        TODO: discuss merits tgz, bz, bz2
-        TODO: problems with incompatibilities with different version of some utilities
-        </section>
         <section id='notes-on-line-endings'><title>On Line Endings</title>
         	<p>
-It is convenient for users and more consistent if line endings for appropriate files
-(text, xml, html and so on) reflect the platform usually associated with the 
-<a href='#best-practice-formats'>compression format</a> (<code>CRLF</code>
-for the <code>zip</code> and <code>LF</code> for the <code>tar.gz</code>).
-        	</p>
-            <p>
-Source packages can use <code>svn export --native-es</code>. Binary packages
+Binary packages
 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>
         </section>
-        <section id='notes-press-releases'><title>On Press Releases</title>
-        	<p>
-It is rare for Apache projects to issue mainstream press releases 
-and it is very rare for releases to justify this. If there is likely to be mainstream
-press interest in a release then please talk to the public relations committee.
-			</p>
-			<p>
-TODO: link to public relations committee
-        	</p>
-        </section>
         <section id='notes-on-signing-jars'><title>On Signing Jars</title>
         	<p>
 Java includes a standard mechanism for signing jars. Apache uses digital
@@ -1730,62 +262,6 @@ sealed against modification. Open source
 TODO: rephrase and check
         	</p>
         </section>
-        <section id='notes-license-headers'><title>On License Headers</title>
-            <p>
-            TODO: links into legal documentation. discuss issues about which files need to apply.
-            </p>
-            <p>
-            All source capable of copyright should contain license header. 
-            Easiest way to comply is to ensure that every human readable file has the header. 
-            Note that source includes not just the source code compiled into the final product 
-            but also all other resources such as style sheets, test code and resources, build files 
-            and documentation source. When in doubt, add a header.
-            </p>
-            <p>
-            TODO: to
-            </p>
-            <p>
-The issue of licenses on generated documentation is a little controversial. Copyright may not subsist
-in a document which is generated by an transformation from an original. In which case, the license header
-may be unnecessary. License headers should always be present in the original. Where it is 
-reasonable to do so, the templates should also add the license header to the generated documents.
-            </p>
-            <p>
-TODO: check with legal-discuss then move this content into the legal pages and link with commentary
-            </p>
-			<p>
-TODO: link into provenance
-			</p>
-        </section>
-        <section id='code-provenance'><title>Code Provenance</title>
-			<p>
-<a href='LINK'>License headers</a> may seem trivial and to some extent that is true. 
-The important issue is code provenance. All code contributions must be tracked and the 
-provenance of the code traceable. 
-			</p>
-			<p>
-Commit comments are an important to. When source
-which is not originally created for the project is committed, the message should contain
-details about the provenance of that source. When a patch is applied from an 
-<a href='#glossary-issue-tracker'>issue tracking system</a>
-system, the issue should be noted in the commit message. 
-			</p>
-			<p>
-Releases are important. Released code is distributed widely. It is important that the provenance
-for all released code is known and is appropriate. License headers are a way of documenting 
-provenance. Any source which is created for Apache should have the standard boilerplate text.
-Other source should have the headers (copyright and license) retained. Before a release,
-source which has not been originally created for (or donated to) Apache should be checked
-against the current Apache policy. 
-			</p>
-			<p>
-Any source which does not have a license header must be considered suspect 
-and its provenance checked. There are several classes of source which do not require
-license headers. It is useful to adopt a policy of documentation in this case perhaps
-by including a short header if the file is generated (say) or by creating a README 
-in the directory containing license information. This makes code auditing much easier.
-			</p>
-        </section>
         <section id='note-standards'><title>Implementations Of Standards</title>
         	<p>
 TODO: importance of accurately reporting to the user the state of an implementation
@@ -1798,169 +274,6 @@ TODO: then check with Geir
         		</p>
         	</section>
         </section>
-        <section id='note-license-and-notice'><title>Understanding Content For NOTICE and LICENSE</title>
-        	<p>
-
-        	</p>
-        	<p>
-The <a href='http://www.apache.org/licenses/LICENSE-2.0.txt'>Apache License, Version 2</a>
-clause 4d states:
-        	</p>
-        	<blockquote cite='http://www.apache.org/licenses/LICENSE-2.0.txt'>
- If the Work includes a "NOTICE" text file as part of its
- distribution, then any Derivative Works that You distribute must
- include a readable copy of the attribution notices contained
- within such NOTICE file, excluding those notices that do not
- pertain to any part of the Derivative Works, in at least one
- of the flowing places: within a NOTICE text file distributed
- as part of the Derivative Works; within the Source form or
- documentation, if provided along with the Derivative Works; or,
- within a display generated by the Derivative Works, if and
- wherever such third-party notices normally appear. The contents
- of the NOTICE file are for informational purposes only and
- do not modify the License. You may add Your own attribution
- notices within Derivative Works that You distribute, alongside

[... 455 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