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