incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject svn commit: r446828 - in /incubator/public/trunk: site-author/guides/releasemanagement.xml site-publish/guides/releasemanagement.html
Date Sat, 16 Sep 2006 08:00:24 GMT
Author: rdonkin
Date: Sat Sep 16 01:00:23 2006
New Revision: 446828

URL: http://svn.apache.org/viewvc?view=rev&rev=446828
Log:
More rough content

Modified:
    incubator/public/trunk/site-author/guides/releasemanagement.xml
    incubator/public/trunk/site-publish/guides/releasemanagement.html

Modified: incubator/public/trunk/site-author/guides/releasemanagement.xml
URL: http://svn.apache.org/viewvc/incubator/public/trunk/site-author/guides/releasemanagement.xml?view=diff&rev=446828&r1=446827&r2=446828
==============================================================================
--- incubator/public/trunk/site-author/guides/releasemanagement.xml (original)
+++ incubator/public/trunk/site-author/guides/releasemanagement.xml Sat Sep 16 01:00:23 2006
@@ -360,6 +360,25 @@
 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 distribution
+information should be included about their official home. minimum (and max) supported versions.
+        	</p>
+        	<p>
+dependencies should comply with the current apache policy. TODO: link
+        	</p>
+        	<p>
+TODO: dependencies also include the tools required to build and test the source.
+tool dependencies are often included in BUILDING or README
+        	</p>
+        	<p>
+TODO: particularly important for languages. language should be approached
+as dependencies and documented. these should be listed in the README
+or RELEASE NOTEs.
+        	</p>
+        </section>
         <section id='best-practice-distributing-libraries'><title>Distributing
Libraries</title>
             <p>
 TODO: ASF policy compliance
@@ -524,6 +543,70 @@
 repository so that it ships with the source distribution.
             </p>
         </section>
+        <section id='notes-signing-releases'><title>Signing Releases</title>
+        	<p>
+TODO: links to dev pages
+batch signing scripts in committers
+        	</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 
+distribution then the documents generated should contain the license header.
+        	</p>
+        	<p>
+However, if this template is used by a user to generate output, usually
+this output should be free of license restributions. Most templating languages
+allow comments which are not included in the output. If this is allowed
+then the license header should be included in the template as a comment.
+If not then consider adding a NOTE or a README to the directory rather 
+than a license header.
+        	</p>
+        </section>
+        <section id='notes-on-java-version'><title>On Java Versions</title>
+        	<p>
+Indicating supported versions for dependencies is 
+<a href='#best-practice-dependencies'>important</a>. The minimum 
+(and - where appropriate - maxiumum)  Java version need to be clearly documented
+in the release. This information should be included in a README or the RELEASE NOTES.
+        	</p>
+        	<p>
+ Users often expect the minimum version supported to be the one listed in the MANIFEST.
+ There are also good reasons for releases to be compiled with the minimum version 
+ of Java supported by the release. This is the easiest way to ensure that the release
+ will work as expected on that version. This will ensure that the version in the MANIFEST
+ is as expected. 
+ 			</p>
+ 			<p>
+If the version in the MANIFEST cannot reflect the minimum support version (see below) 
+then it is recommended that the following additional entries are added to MANIFEST.
+ 			</p>
+ 			<p>
+The usual reason for need to use a more modern Java version is to support
+optional classes which require features present only in the new version.
+			</p>
+			<p>
+The approach which requires the least configuration is to adopt a split compilation
+strategy. The release manager installs two separate Java versions. The build
+script supports optional parameterisation allowing the optional code to be compiled with

+a second JSDK. It is recommended that the build scrip includes clear indications
+that a second JSDK has been detected.
+ 			</p>
+ 			<p>
+The alternative is to correctly configure a more modern JSDK to compile code
+which will function correctly on an older JRE. This means TODO: javac settings through 
+Ant. This is not sufficient. Unfortunately the source also need to be compiled against
+the appropriate version of the Java API. TODO: check where the jar has to be exactly
+placed.
+        	</p>
+        </section>
         <section id='notes-on-compression-formats'><title></title>
         TODO: discuss merits tgz, bz, bz2
         TODO: problems with incompatibilities with older version of some utilities
@@ -576,6 +659,9 @@
             </p>
         </section>
         <section id='note-votes'><title>VOTEs</title>
+        	<p>
+        	TODO: add bill's excellent quote (apologies for the pun)
+        	</p>
         	<p>
  Apache releases are high ceremony. A number of formal VOTEs binding upon Apache
  are required before an release of any type.

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=446828&r1=446827&r2=446828
==============================================================================
--- incubator/public/trunk/site-publish/guides/releasemanagement.html (original)
+++ incubator/public/trunk/site-publish/guides/releasemanagement.html Sat Sep 16 01:00:23
2006
@@ -493,6 +493,28 @@
             </p>
 </div>
 <h3>
+   <a name="best-practice-dependencies">Dependencies</a>
+</h3>
+<div class="section-content">
+<p>
+TODO: information about dependencies is a FAQ. releases should indicate dependencies
+and which are optional and which required. if they are not shipped with the distribution
+information should be included about their official home. minimum (and max) supported versions.
+        	</p>
+<p>
+dependencies should comply with the current apache policy. TODO: link
+        	</p>
+<p>
+TODO: dependencies also include the tools required to build and test the source.
+tool dependencies are often included in BUILDING or README
+        	</p>
+<p>
+TODO: particularly important for languages. language should be approached
+as dependencies and documented. these should be listed in the README
+or RELEASE NOTEs.
+        	</p>
+</div>
+<h3>
    <a name="best-practice-distributing-libraries">Distributing Libraries</a>
 </h3>
 <div class="section-content">
@@ -693,6 +715,79 @@
             </p>
 </div>
 <h3>
+   <a name="notes-signing-releases">Signing Releases</a>
+</h3>
+<div class="section-content">
+<p>
+TODO: links to dev pages
+batch signing scripts in committers
+        	</p>
+</div>
+<h3>
+   <a name="notes-on-templates">On Template Sources</a>
+</h3>
+<div class="section-content">
+<p>
+        	TODO: this is probably a best practice
+        	</p>
+<p>
+Source files should contain the license header whenever this is reasonable.
+Templates are source documents and so this principle applies to them as well.
+			</p>
+<p>
+If these templates are used to generate documents which form part of the 
+distribution then the documents generated should contain the license header.
+        	</p>
+<p>
+However, if this template is used by a user to generate output, usually
+this output should be free of license restributions. Most templating languages
+allow comments which are not included in the output. If this is allowed
+then the license header should be included in the template as a comment.
+If not then consider adding a NOTE or a README to the directory rather 
+than a license header.
+        	</p>
+</div>
+<h3>
+   <a name="notes-on-java-version">On Java Versions</a>
+</h3>
+<div class="section-content">
+<p>
+Indicating supported versions for dependencies is 
+<a href="#best-practice-dependencies">important</a>. The minimum 
+(and - where appropriate - maxiumum)  Java version need to be clearly documented
+in the release. This information should be included in a README or the RELEASE NOTES.
+        	</p>
+<p>
+ Users often expect the minimum version supported to be the one listed in the MANIFEST.
+ There are also good reasons for releases to be compiled with the minimum version 
+ of Java supported by the release. This is the easiest way to ensure that the release
+ will work as expected on that version. This will ensure that the version in the MANIFEST
+ is as expected. 
+ 			</p>
+<p>
+If the version in the MANIFEST cannot reflect the minimum support version (see below) 
+then it is recommended that the following additional entries are added to MANIFEST.
+ 			</p>
+<p>
+The usual reason for need to use a more modern Java version is to support
+optional classes which require features present only in the new version.
+			</p>
+<p>
+The approach which requires the least configuration is to adopt a split compilation
+strategy. The release manager installs two separate Java versions. The build
+script supports optional parameterisation allowing the optional code to be compiled with

+a second JSDK. It is recommended that the build scrip includes clear indications
+that a second JSDK has been detected.
+ 			</p>
+<p>
+The alternative is to correctly configure a more modern JSDK to compile code
+which will function correctly on an older JRE. This means TODO: javac settings through 
+Ant. This is not sufficient. Unfortunately the source also need to be compiled against
+the appropriate version of the Java API. TODO: check where the jar has to be exactly
+placed.
+        	</p>
+</div>
+<h3>
    <a name="notes-on-compression-formats"></a>
 </h3>
 <div class="section-content">
@@ -757,6 +852,9 @@
    <a name="note-votes">VOTEs</a>
 </h3>
 <div class="section-content">
+<p>
+        	TODO: add bill's excellent quote (apologies for the pun)
+        	</p>
 <p>
  Apache releases are high ceremony. A number of formal VOTEs binding upon Apache
  are required before an release of any type.



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


Mime
View raw message