incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject svn commit: r442709 - in /incubator/public/trunk: site-author/guides/releasemanagement.xml site-publish/guides/releasemanagement.html
Date Tue, 12 Sep 2006 21:18:22 GMT
Author: rdonkin
Date: Tue Sep 12 14:18:21 2006
New Revision: 442709

URL: http://svn.apache.org/viewvc?view=rev&rev=442709
Log:
More rough content on release management.

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=442709&r1=442708&r2=442709
==============================================================================
--- incubator/public/trunk/site-author/guides/releasemanagement.xml (original)
+++ incubator/public/trunk/site-author/guides/releasemanagement.xml Tue Sep 12 14:18:21 2006
@@ -380,6 +380,70 @@
 http://jakarta.apache.org/commons/releases/prepare.html#checkjarmanifest
             </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>.
 
+        	</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 necessessity to raise a major version number (say) if the minor version has
+ reached 9. The exact rules vary and it is recommended that a project agrees and documents
+ its own rules. 
+			</p>
+ 			<p>
+ In addition to an official release with a particular version number, any number of
+ unofficial releases of various types may share the same number. These are usually
+ terms alphas, beta, release candidates, TODO: link to foundation release documents.
+ These release may be designated by adding an appropriate suffix to the release 
+ number (for example, 3.11.15RC1). The exact form is not as important as 
+ documenting the system adopted by the project and its consistent use. Users
+ should be able to predict the status of the release from the artifact and the documentation.
+ 			</p><p>
+ TODO: (move to a note) Notes on 0.x releases verses alpha and betas. It is better to use
<code>0.x</code>
+ releases than to create numerous alphas and betas for 1.0. Conventionally, 0.x releases
+ are aimed at early adopters only without a strong promise of easy upgrade or backwards
+ compatibility. 0.x is a good designation for a product that is not feature complete 
+ but whose code is solid for those features which are implemented.
+        	</p>
+        </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 excerted over errant downstream repackages

+ by trademark law. If this practice is adopted then the release manager merely has to ensure

+ that each artifact is uniquely named within the set of Apache artifacts. By including the
name of 
+ the project, each artifact only has to be unique within the artifacts release by the project.
When 
+ a project distributes several distinct products then the product name should also be included.
+        	</p>
+        	<p>
+For each product, each <a href='best-practice-types'>type of distribution</a>
should be 
+assigned a consistent and unique name. Conventionally, source distributions use <code>src</code>
+and main binary distributions no prefix. Typically each type of distributions is made available
in a number of 
+<a href='best-practice-formats'>compression format</a>. These are conventionally
distiguished 
+by the usual file type suffix.
+        	</p>
+        	<p>
+So, the traditional format is apache-project-product-type-version.format.
+        	</p>
+        </section>
         <section id='release-notes'><title>Release Notes</title>
             <p>
 The release notes should be in a common and easily read format (plain text is best).
@@ -500,6 +564,22 @@
         	<p>
 TODO: move VOTE netiquette into either ppmc or lists and link from here
         	</p>
+        </section>
+        <section id='notes-release-candidate-java'><title>On Java Release Candidates</title>
+			<p>
+This section applies to any distribution that contains redistributable artifacts which contain
version
+information but in particular binary distributions of Java contain jar files. A complient
MANIFEST 
+meta data file within each of these files should contain the implementation version.
+These are good reasons to use the release version number as the implementation version.
+This allows the exact version to be determined from just the jar.
+Unfortunately, some applications expect the format to be entirely numeric (TODO: maven?)
+			</p>
+			<p>
+This does mean that release candidates for binary distributions of this type must either
+be rerolled with the version number as the only change or accept that artifacts will not
be 
+uniquely named. Uncertainty about exact jar versions has caused nasty dependency
+issues in the past.
+			</p>
         </section>
     </section>
     <section id='glossary'><title>Glossary</title>

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=442709&r1=442708&r2=442709
==============================================================================
--- incubator/public/trunk/site-publish/guides/releasemanagement.html (original)
+++ incubator/public/trunk/site-publish/guides/releasemanagement.html Tue Sep 12 14:18:21
2006
@@ -524,6 +524,80 @@
             </p>
 </div>
 <h3>
+   <a name="best-practice-release-candidate">Release Candidates</a>
+</h3>
+<div class="section-content">
+<p>
+There are two distinct approaches <a href="glossary-release-candidate">release candidate</a>.
 
+        	</p>
+</div>
+<h3>
+   <a name="best-practice-versioning">Versioning</a>
+</h3>
+<div class="section-content">
+<p>
+There are several good versioning strategies used by projects at Apache. The version strategy
+adopted is less important than adopting one that is clear and consistent and documenting
it.
+If there are strong opinions amongst developers on the right way to version then document
this
+strategy. If there are not then time can be saved by adopting an existing strategy with a
good
+fit. It is usually better to start by copying the documentation rather than using by reference.
+Strategies sometimes change as do URLs. Project often (in time) find that they need to expand
+or fine tune their versioning strategy and this is hard if another project's documentation
is used.
+A project should therefore use their own strategy.
+        	</p>
+<p>
+ TODO: notes on strategies. 
+ 			</p>
+<p>
+ The most common system of versioning is based on <code>major.minor.point</code>
+ where major, minor and point are all integers. Note that these are not decimals and
+ there is no necessessity to raise a major version number (say) if the minor version has
+ reached 9. The exact rules vary and it is recommended that a project agrees and documents
+ its own rules. 
+			</p>
+<p>
+ In addition to an official release with a particular version number, any number of
+ unofficial releases of various types may share the same number. These are usually
+ terms alphas, beta, release candidates, TODO: link to foundation release documents.
+ These release may be designated by adding an appropriate suffix to the release 
+ number (for example, 3.11.15RC1). The exact form is not as important as 
+ documenting the system adopted by the project and its consistent use. Users
+ should be able to predict the status of the release from the artifact and the documentation.
+ 			</p>
+<p>
+ TODO: (move to a note) Notes on 0.x releases verses alpha and betas. It is better to use
<code>0.x</code>
+ releases than to create numerous alphas and betas for 1.0. Conventionally, 0.x releases
+ are aimed at early adopters only without a strong promise of easy upgrade or backwards
+ compatibility. 0.x is a good designation for a product that is not feature complete 
+ but whose code is solid for those features which are implemented.
+        	</p>
+</div>
+<h3>
+   <a name="best-practice-unique-names">Unique Artifact Names</a>
+</h3>
+<div class="section-content">
+<p>
+ Every <a href="glossay-artifact">artifact</a> distributed should have a name
that is unique.
+ This allows each artifact to the recognized by its name and ensures that different artifacts
do not
+ overwrite each other. Including <em>apache</em> in the name of the artifact
not only gives
+ brand recognition but means influence can be excerted over errant downstream repackages

+ by trademark law. If this practice is adopted then the release manager merely has to ensure

+ that each artifact is uniquely named within the set of Apache artifacts. By including the
name of 
+ the project, each artifact only has to be unique within the artifacts release by the project.
When 
+ a project distributes several distinct products then the product name should also be included.
+        	</p>
+<p>
+For each product, each <a href="best-practice-types">type of distribution</a>
should be 
+assigned a consistent and unique name. Conventionally, source distributions use <code>src</code>
+and main binary distributions no prefix. Typically each type of distributions is made available
in a number of 
+<a href="best-practice-formats">compression format</a>. These are conventionally
distiguished 
+by the usual file type suffix.
+        	</p>
+<p>
+So, the traditional format is apache-project-product-type-version.format.
+        	</p>
+</div>
+<h3>
    <a name="release-notes">Release Notes</a>
 </h3>
 <div class="section-content">
@@ -659,6 +733,25 @@
 <p>
 TODO: move VOTE netiquette into either ppmc or lists and link from here
         	</p>
+</div>
+<h3>
+   <a name="notes-release-candidate-java">On Java Release Candidates</a>
+</h3>
+<div class="section-content">
+<p>
+This section applies to any distribution that contains redistributable artifacts which contain
version
+information but in particular binary distributions of Java contain jar files. A complient
MANIFEST 
+meta data file within each of these files should contain the implementation version.
+These are good reasons to use the release version number as the implementation version.
+This allows the exact version to be determined from just the jar.
+Unfortunately, some applications expect the format to be entirely numeric (TODO: maven?)
+			</p>
+<p>
+This does mean that release candidates for binary distributions of this type must either
+be rerolled with the version number as the only change or accept that artifacts will not
be 
+uniquely named. Uncertainty about exact jar versions has caused nasty dependency
+issues in the past.
+			</p>
 </div>
 </div>
            <h2><img src="/images/redarrow.gif" />



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


Mime
View raw message