incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject svn commit: r450940 [2/2] - in /incubator/public/trunk: site-author/guides/ site-author/guides/examples/ site-publish/guides/ site-publish/guides/examples/
Date Thu, 28 Sep 2006 17:53:07 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=450940&r1=450939&r2=450940
==============================================================================
--- incubator/public/trunk/site-publish/guides/releasemanagement.html (original)
+++ incubator/public/trunk/site-publish/guides/releasemanagement.html Thu Sep 28 10:53:06
2006
@@ -269,7 +269,16 @@
 	                    	<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 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>
@@ -288,6 +297,12 @@
             		<li>Check for <a href="#best-practice-source">version control</a>
files</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" />
@@ -382,6 +397,9 @@
  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>
@@ -391,18 +409,65 @@
         	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 that <a href="glossary-release-documentation">release documentation</a>

+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 build copies them. 
-        	</p>
+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>
-Incubating projects should contain the STATUS document describing. TODO: check this
+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.
@@ -412,7 +477,15 @@
  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.
+ 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>
@@ -426,6 +499,22 @@
         	</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">
@@ -480,6 +569,20 @@
 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>
@@ -543,6 +646,27 @@
         	</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>
+</div>
+<h3>
    <a name="best-practices">Dependencies</a>
 </h3>
 <div class="section-content">
@@ -550,6 +674,9 @@
 TODO: versions should be clearly indicated
 TODO: java version with indication in MANIFEST (link to note)
         	</p>
+<p>
+TODO: see note on export regulation complience.
+        	</p>
 </div>
 <h3>
    <a name="announcements">Announcements</a>
@@ -572,6 +699,43 @@
         	</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">
@@ -741,6 +905,15 @@
         	</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">
@@ -805,6 +978,14 @@
         	</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">
@@ -839,6 +1020,22 @@
         	</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">
@@ -866,6 +1063,65 @@
             </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">
@@ -920,6 +1176,21 @@
 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>
@@ -1081,6 +1352,8 @@
         	</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>



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


Mime
View raw message