incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject svn commit: r471874 - in /incubator/public/trunk: site-author/guides/releasemanagement.xml site-publish/guides/releasemanagement.html
Date Mon, 06 Nov 2006 20:48:08 GMT
Author: rdonkin
Date: Mon Nov  6 12:48:07 2006
New Revision: 471874

URL: http://svn.apache.org/viewvc?view=rev&rev=471874
Log:
More 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=471874&r1=471873&r2=471874
==============================================================================
--- incubator/public/trunk/site-author/guides/releasemanagement.xml (original)
+++ incubator/public/trunk/site-author/guides/releasemanagement.xml Mon Nov  6 12:48:07 2006
@@ -188,6 +188,12 @@
 	                    	<li>Check current policy on headers that all comply</li>
                     	</ul>
                     </li>
+                    <li>Check incubator requirements
+                    	<ul>
+                    		<li>Check disclaimer is distributed TODO: link</li>
+                    		<li>Check <a href='#best-practice-status'>status document</a></li>
+                    	</ul>
+                    </li>
                 </ul>
             </li>
             <li><a href='#glossary-artifact'>Distributed Artifacts</a>
@@ -246,7 +252,16 @@
     	</section>
     	<section id='best-practice-bugs'><title>Bugs</title>
     		<p>
-The list of open bugs needs to be analysed. TODO: expand
+The list of open issues needs to be analysed. The community needs to decide which 
+issues could be resolved for this release and how much energy the community
+has to deal with these. Time may also become a factor: some issues which 
+cannot be resolved promptly may need to be postponed.
+    		</p>
+    		<p>
+Issue tracking system can be used to help this process especially for complex projects 
+with many open issues. Each open issues should be analysed and marked appropriately.
+An accurate view of those bugs which are targetted for the upcoming release helps
+to concentrate community effort. Consider asking reporters to donate unit tests.
     		</p>
     	</section>
     	<section id='best-practice-prepare-documentation'><title>Preparing Documentation</title>
@@ -325,6 +340,13 @@
 new developers is vital for the long term health of an Apache project.
 				</li>
         	</ul>
+        	<p>
+It is strongly recommended that source distributions are included in every release.
+Many packagers (for example, FreeBSD and linux distributions) prefer or demand
+to work from source releases. Archivists prefer source. Many large organisations
+prefer to verify and then build their own versions from source. A source distribution
+is easy to create but helps to reach these audiences.
+        	</p>
         </section>
         <section id='best-practice-binary'><title>Binary Distribution</title>
         	<p>
@@ -495,6 +517,13 @@
 as dependencies and documented. these should be listed in the README
 or RELEASE NOTEs.
         	</p>
+        	<p>
+Any changes in dependencies (including dependencies added or removed
+or changes in supported version) should be noted in the change log for this
+release. (Where appropriate) check the that the application is built against 
+the correct versions. Note that this includes platform as well as library
+dependencies.
+        	</p>
         </section>
         <section id='best-practice-distributing-libraries'><title>Distributing
Libraries</title>
             <p>
@@ -502,7 +531,7 @@
 TODO: project policy - explicit policy should be written down
             </p>
             <p>
-TODO: Discussion on the merits of distributing dependent jars. 
+TODO: Discussion on the merits of distributing dependent jars. This should be a link to the
notes section
             </p>
         </section>
         
@@ -554,6 +583,14 @@
 used to build the release should be noted.
         	</p>
         </section>
+        <section id='best-practice-release-as-advertising'><title>Release As
Advertising</title>
+        	<p>
+Releases are a primary form of communication with open source users and potential developers.
+It's useful to think about releases in this way. TODO: what a release says about a projects

+TODO: link into media relations and announcements (grassroots and mainstream, articles
+on new features, freshmeat, downstream packagers)
+        	</p>
+        </section>
         <section id='best-practice-dependencies'><title>Dependencies</title>
         	<p>
 As well as libraries, projects often have more subtle dependencies.
@@ -808,6 +845,18 @@
 compatibility. Note that the discovery of incompatibilities at this stage
 may require a change in version number or revision of function.
             </p>
+            <p>
+ Release notes should be readable with minimal requirement. So, they should
+ be plain text with explicit line breaks at a reasonable number of characters 
+ (80, say). Most projects now produce documentation that is formatted as
+ html. The development and supply of release notes in this format is fine
+ but release managers should create and supply a plain text version
+ by stripping out the formatting.
+            </p>
+            <p>
+Remember that a user may have received the software indirectly. So, include
+some brief details about the project and an url.
+            </p>
         </section>
         <section id='note-compatibility-checkers'><title>Compatibility Checkers</title>
 			<p>
@@ -982,6 +1031,38 @@
             <p>
 TODO: check with legal-discuss then move this content into the legal pages and link with
commentary
             </p>
+			<p>
+TODO: link into provinance
+			</p>
+        </section>
+        <section id='note-privinence'><title>Code Provinance</title>
+			<p>
+<a href='LINK'>License headers</a> may seem trivial and to some extent that is
true. 
+The important issue is code provinence. All code contributions must be tracked and the 
+provinence of the code traceable. 
+			</p>
+			<p>
+Commit comments are an important tool. When source
+which is not originally created for the project is committed, the message should contain
+details about the provinance of that source. When a patch is applied from an 
+<a href='#glossary-issue-tracker'>issue tracking system</a>
+system, the issue should be noted in the commit message. 
+			</p>
+			<p>
+Releases are important. Released code is distributed widely. It is important that the provinance
+for all released code is known and is appropriate. License headers are a way of documenting

+provinence. Any source which is created for Apache should have the standard boilerplate text.
+Other source should have the headers (copyright and license) retained. Before a release,
+source which has not been originally created for (or donated to) Apache should be checked
+against the current Apache policy. 
+			</p>
+			<p>
+Any source which does not have a license header must be considered suspect 
+and it's provinence checked. There are several classes of source which do not require
+license headers. It is useful to adopt a policy of documentation in this case perhaps
+by including a short header if the file is generated (say) or by creating a README 
+in the directory containing license information. This makes code auditing much easier.
+			</p>
         </section>
         <section id='note-license-and-notice'><title>Understanding Content For
NOTICE and LICENSE</title>
         	<p>
@@ -1285,6 +1366,11 @@
                 <section id='glossary-release-documentation'><title>Release Documentation</title>
         	<p>
 Documents a particular release of a product rather than the product itself.
+        	</p>
+        </section>
+        <section id='glossary-issue-tracker'><title>Issue Tracking System</title>
+        	<p>
+An application that store manages issues reported in Apache products. TODO: links
         	</p>
         </section>
     </section>

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=471874&r1=471873&r2=471874
==============================================================================
--- incubator/public/trunk/site-publish/guides/releasemanagement.html (original)
+++ incubator/public/trunk/site-publish/guides/releasemanagement.html Mon Nov  6 12:48:07
2006
@@ -281,6 +281,12 @@
 	                    	<li>Check current policy on headers that all comply</li>
                     	</ul>
                     </li>
+                    <li>Check incubator requirements
+                    	<ul>
+                    		<li>Check disclaimer is distributed TODO: link</li>
+                    		<li>Check <a href="#best-practice-status">status document</a></li>
+                    	</ul>
+                    </li>
                 </ul>
             </li>
             <li><a href="#glossary-artifact">Distributed Artifacts</a>
@@ -357,7 +363,16 @@
 </h3>
 <div class="section-content">
 <p>
-The list of open bugs needs to be analysed. TODO: expand
+The list of open issues needs to be analysed. The community needs to decide which 
+issues could be resolved for this release and how much energy the community
+has to deal with these. Time may also become a factor: some issues which 
+cannot be resolved promptly may need to be postponed.
+    		</p>
+<p>
+Issue tracking system can be used to help this process especially for complex projects 
+with many open issues. Each open issues should be analysed and marked appropriately.
+An accurate view of those bugs which are targetted for the upcoming release helps
+to concentrate community effort. Consider asking reporters to donate unit tests.
     		</p>
 </div>
 <h3>
@@ -650,6 +665,13 @@
 as dependencies and documented. these should be listed in the README
 or RELEASE NOTEs.
         	</p>
+<p>
+Any changes in dependencies (including dependencies added or removed
+or changes in supported version) should be noted in the change log for this
+release. (Where appropriate) check the that the application is built against 
+the correct versions. Note that this includes platform as well as library
+dependencies.
+        	</p>
 </div>
 <h3>
    <a name="best-practice-distributing-libraries">Distributing Libraries</a>
@@ -660,7 +682,7 @@
 TODO: project policy - explicit policy should be written down
             </p>
 <p>
-TODO: Discussion on the merits of distributing dependent jars. 
+TODO: Discussion on the merits of distributing dependent jars. This should be a link to the
notes section
             </p>
 </div>
 <h3>
@@ -723,6 +745,17 @@
         	</p>
 </div>
 <h3>
+   <a name="best-practice-release-as-advertising">Release As Advertising</a>
+</h3>
+<div class="section-content">
+<p>
+Releases are a primary form of communication with open source users and potential developers.
+It's useful to think about releases in this way. TODO: what a release says about a projects

+TODO: link into media relations and announcements (grassroots and mainstream, articles
+on new features, freshmeat, downstream packagers)
+        	</p>
+</div>
+<h3>
    <a name="best-practice-dependencies">Dependencies</a>
 </h3>
 <div class="section-content">
@@ -1012,6 +1045,14 @@
 It is recommended that (where possible) automated tests are used to verify 
 compatibility. Note that the discovery of incompatibilities at this stage
 may require a change in version number or revision of function.
+            </p>
+<p>
+ Release notes should be readable with minimal requirement. So, they should
+ be plain text with explicit line breaks at a reasonable number of characters 
+ (80, say). Most projects now produce documentation that is formatted as
+ html. The development and supply of release notes in this format is fine
+ but release managers should create and supply a plain text version
+ by stripping out the formatting.
             </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