incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject svn commit: r439564 - in /incubator/public/trunk: site-author/guides/releasemanagement.xml site-publish/guides/releasemanagement.html
Date Sat, 02 Sep 2006 09:08:04 GMT
Author: rdonkin
Date: Sat Sep  2 02:08:04 2006
New Revision: 439564

URL: http://svn.apache.org/viewvc?rev=439564&view=rev
Log:
Roughed out 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?rev=439564&r1=439563&r2=439564&view=diff
==============================================================================
--- incubator/public/trunk/site-author/guides/releasemanagement.xml (original)
+++ incubator/public/trunk/site-author/guides/releasemanagement.xml Sat Sep  2 02:08:04 2006
@@ -75,7 +75,7 @@
     <section id='guidelines'><title>Guidelines</title>
         <p>
 It is strong recommended that a project creates it's own release guidelines. The actual 
-<a href='rules'>minimum</a> required by the ASF is reasonable small but subtle.
However,
+<a href='#rules'>minimum</a> required by the ASF is reasonable small but subtle.
However,
 the traditional standards for ASF releases are quite high. 
         </p>
                 <p>
@@ -109,6 +109,17 @@
         	<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>
+Most projects find it difficult to issue quality releases without appointing a 
+<a href='glossay-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 organisations,
+in the middle stages of a release, for deciding which code will be included in the release,
+in the late stages for marshalling the VOTEs required for formal approval
+then finally for <a href='#glossay-cutting-release'>cutting the release</a>.
+TODO: maybe be better in a time line
+        </p>
     </section>
     <section id='check-list'><title>Check List</title>
         <p>
@@ -184,7 +195,7 @@
  TODO: Common Types of distribtuion
  			</p>
  			<p>
- TODO: the source distribution is canonical. every project should create a source distribution.
+ The source distribution is canonical. Every release should create a source distribution.
  compiled languages may also wish to create binary releases. these may be platform specific.
  some project may also convenience types which package the project for particular containers.
         	</p>
@@ -267,6 +278,7 @@
 TODO: Discussion on the merits of distributing dependent jars. 
             </p>
         </section>
+        
         <section id='best-practice-notice'><title>NOTICE files</title>
         	<p>
  TODO: links to infra
@@ -281,6 +293,36 @@
 TODO: java version with indication in MANIFEST (link to note)
         	</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 grassroot 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 transfering this.
+        	</p>
+        	<p>
+Announcements should be posted from the release manager's 
+<code>apache.org</code> address.
+        	</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 propergate 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>
     <section id='notes'><title>Notes</title>
         <section id='distributing-jars'><title>Distributing Jars</title>
@@ -308,13 +350,23 @@
         </section>
         <section id='release-notes'><title>Release Notes</title>
             <p>
-            TODO: text is best. Every release should have them and should be positioned in
the base directory
+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
+TODO: contents
+include a short description of the project and links to the apache site
             </p>
             <p>
-            TODO: Ship with source and binary
+Whenever possible, each type of distribution should ship with the release notes.
+The release notes document should therefore be committed to the source
+repository so that it ships with the source distribution.
             </p>
         </section>
         <section id='notes-on-compression-formats'><title></title>
@@ -322,10 +374,28 @@
         TODO: problems with incompatibilities with older 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>
-            TODO: windows vs *nix line endings. use svn to export. example.
+Source distributions can use <code>svn export --native-eols</code>. Binary distributions
+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-license-headers'><title>On License Headers</title>
             <p>
             TODO: links into legal documentation. discuss issues about which files need to
apply.
@@ -402,11 +472,17 @@
     </section>
     <section id='glossary'><title>Glossary</title>
         <section id='glossary-artifact'><title>Distributed Artifact</title>
+        	<p>
+A file that is actually shipped.
+        	</p>
             <p>
             TODO (include link to infra documentation)
             </p>
         </section>
         <section id='glossary-license'><title>LICENSE file</title>
+        	<p>
+  Document containing the licenses for the distribution.
+        	</p>
             <p>
             TODO (include link to infra documentation)
             </p>
@@ -417,16 +493,25 @@
             </p>
         </section>
         <section id='glossary-manifest'><title>Jar MANIFEST</title>
+        	<p>
+Meta data associated with the Java Jar format.
+        	</p>
             <p>
             TODO link to sun documentation
             </p>
         </section>
          <section id='glossary-license-header'><title>License Header</title>
+         	<p>
+Text referring to the license for a file (as opposed to the license text).
+         	</p>
             <p>
             TODO (include link to legal documentation)
             </p>
         </section>
         <section id='glossary-release-manager'><title>Release Manager</title>
+        	<p>
+Committer responsible for sheparding the release. 
+        	</p>
             <p>
             TODO (include link to infra documentation)
             </p>
@@ -457,6 +542,13 @@
             binary distributions include all types which are not source. 
             one canonical source distribution, many binary distributions.
             </p>
+        </section>
+        <section id='glossary-cutting-release'><title>Cutting The Release</title>
+        	<p>
+The actual execution of the release. Typically consists of building the distribtions
+from the repository tag.
+TODO: link to infra
+        	</p>
         </section>
     </section>
   </body>

Modified: incubator/public/trunk/site-publish/guides/releasemanagement.html
URL: http://svn.apache.org/viewvc/incubator/public/trunk/site-publish/guides/releasemanagement.html?rev=439564&r1=439563&r2=439564&view=diff
==============================================================================
--- incubator/public/trunk/site-publish/guides/releasemanagement.html (original)
+++ incubator/public/trunk/site-publish/guides/releasemanagement.html Sat Sep  2 02:08:04
2006
@@ -153,7 +153,7 @@
 <div class="section-content">
 <p>
 It is strong recommended that a project creates it's own release guidelines. The actual 
-<a href="rules">minimum</a> required by the ASF is reasonable small but subtle.
However,
+<a href="#rules">minimum</a> required by the ASF is reasonable small but subtle.
However,
 the traditional standards for ASF releases are quite high. 
         </p>
 <p>
@@ -187,6 +187,17 @@
         	<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>
+Most projects find it difficult to issue quality releases without appointing a 
+<a href="glossay-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 organisations,
+in the middle stages of a release, for deciding which code will be included in the release,
+in the late stages for marshalling the VOTEs required for formal approval
+then finally for <a href="#glossay-cutting-release">cutting the release</a>.
+TODO: maybe be better in a time line
+        </p>
 </div>
            <h2><img src="/images/redarrow.gif" />
    <a name="check-list">Check List</a>
@@ -283,7 +294,7 @@
  TODO: Common Types of distribtuion
  			</p>
 <p>
- TODO: the source distribution is canonical. every project should create a source distribution.
+ The source distribution is canonical. Every release should create a source distribution.
  compiled languages may also wish to create binary releases. these may be platform specific.
  some project may also convenience types which package the project for particular containers.
         	</p>
@@ -403,6 +414,42 @@
 TODO: java version with indication in MANIFEST (link to note)
         	</p>
 </div>
+<h3>
+   <a name="announcements">Announcements</a>
+</h3>
+<div class="section-content">
+<p>
+TODO: release managers should ensure that releases are announced.
+TODO: links to release management FAQs
+TODO: consider grassroot 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 transfering this.
+        	</p>
+<p>
+Announcements should be posted from the release manager's 
+<code>apache.org</code> address.
+        	</p>
+</div>
+<h3>
+   <a name="signing-releases">Signatures</a>
+</h3>
+<div class="section-content">
+<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 propergate 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>
+</div>
 </div>
            <h2><img src="/images/redarrow.gif" />
    <a name="notes">Notes</a>
@@ -442,13 +489,23 @@
 </h3>
 <div class="section-content">
 <p>
-            TODO: text is best. Every release should have them and should be positioned in
the base directory
+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
+TODO: contents
+include a short description of the project and links to the apache site
             </p>
 <p>
-            TODO: Ship with source and binary
+Whenever possible, each type of distribution should ship with the release notes.
+The release notes document should therefore be committed to the source
+repository so that it ships with the source distribution.
             </p>
 </div>
 <h3>
@@ -461,10 +518,31 @@
 </h3>
 <div class="section-content">
 <p>
-            TODO: windows vs *nix line endings. use svn to export. example.
+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 distributions can use <code>svn export --native-eols</code>. Binary distributions
+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>
 </div>
 <h3>
+   <a name="notes-press-releases">On Press Releases</a>
+</h3>
+<div class="section-content">
+<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>
+</div>
+<h3>
    <a name="notes-license-headers">On License Headers</a>
 </h3>
 <div class="section-content">
@@ -553,6 +631,9 @@
 </h3>
 <div class="section-content">
 <p>
+A file that is actually shipped.
+        	</p>
+<p>
             TODO (include link to infra documentation)
             </p>
 </div>
@@ -561,6 +642,9 @@
 </h3>
 <div class="section-content">
 <p>
+  Document containing the licenses for the distribution.
+        	</p>
+<p>
             TODO (include link to infra documentation)
             </p>
 </div>
@@ -577,6 +661,9 @@
 </h3>
 <div class="section-content">
 <p>
+Meta data associated with the Java Jar format.
+        	</p>
+<p>
             TODO link to sun documentation
             </p>
 </div>
@@ -585,6 +672,9 @@
 </h3>
 <div class="section-content">
 <p>
+Text referring to the license for a file (as opposed to the license text).
+         	</p>
+<p>
             TODO (include link to legal documentation)
             </p>
 </div>
@@ -593,6 +683,9 @@
 </h3>
 <div class="section-content">
 <p>
+Committer responsible for sheparding the release. 
+        	</p>
+<p>
             TODO (include link to infra documentation)
             </p>
 </div>
@@ -637,6 +730,16 @@
             binary distributions include all types which are not source. 
             one canonical source distribution, many binary distributions.
             </p>
+</div>
+<h3>
+   <a name="glossary-cutting-release">Cutting The Release</a>
+</h3>
+<div class="section-content">
+<p>
+The actual execution of the release. Typically consists of building the distribtions
+from the repository tag.
+TODO: link to infra
+        	</p>
 </div>
 </div>
          </td>



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


Mime
View raw message