incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject svn commit: r468977 - in /incubator/public/trunk: site-author/guides/releasemanagement.xml site-publish/guides/releasemanagement.html
Date Sun, 29 Oct 2006 20:34:32 GMT
Author: rdonkin
Date: Sun Oct 29 12:34:31 2006
New Revision: 468977

URL: http://svn.apache.org/viewvc?view=rev&rev=468977
Log:
Some more content on release notes and related topics

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=468977&r1=468976&r2=468977
==============================================================================
--- incubator/public/trunk/site-author/guides/releasemanagement.xml (original)
+++ incubator/public/trunk/site-author/guides/releasemanagement.xml Sun Oct 29 12:34:31 2006
@@ -763,6 +763,67 @@
 The release notes document should therefore be committed to the source
 repository so that it ships with the source distribution.
             </p>
+            <p>
+The first paragraph of the release notes should introduce the project and the release.
+It is often useful to characterise the release (TODO examples). Spend time thinking
+about the best organisation. Important information should be prominent.
+            </p>
+            <p>
+The exact contents of the release notes varies and it is not unusual for 
+this content to be distributed amongst several documents. This is fine:
+these recommendations should be viewed as pertaining to the mass of
+notes that accumpany the release and do not need to be included 
+in any particular document.
+            </p>
+            <p>
+Any changes which may effect a user who wishes to replace the last version with
+this should be highlighted. In particular, document:
+            </p>
+            <ul>
+            	<li>Deprecations</li>
+            	<li>Binary incompatibilities</li>
+            	<li>Semantic incompatibilities (TODO: glossary)</li>
+            </ul>
+            <p>
+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>
+        </section>
+        <section id='note-compatibility-checkers'><title>Compatibility Checkers</title>
+			<p>
+Some tools used by Apache projects:
+			</p>
+			<ul>
+				<li>Java
+					<ul>
+						<li><a href='http://clirr.sourceforge.net//'>Clirr</a> works on binaries</li>
+						<li><a href='http://jdiff.sourceforge.net/'>JDiff</a> uses sources</li>
+					</ul>
+				</li>
+			</ul>
+        </section>
+        <section id='notes-change-log'><title>Change Logs</title>
+        	<p>
+TODO: should this be in best practices
+TODO: add examples
+        	</p>
+        	<p>
+A change log indicates the changes made to the project since the last release.
+Some projects include a change log in the release notes documents.
+Others use a separate document often called <code>ChangeLog</code>.
+Maven can be used to generate a change log as part of the project documentation.
+        	</p>
+        	<p>
+Change logs can be created in various ways. Some project ask committers to fill
+in details each time they commit. Other rely on analysing the commit messages
+when the release is prepared. (To do this, go through the logs since the revision
+of the last release. TODO example)
+        	</p>
+        	<p>
+The change log typically includes every feature added and every bug resolved since 
+the last release.
+        	</p>
         </section>
         <section id='notes-signing-releases'><title>Signing Releases</title>
         	<p>
@@ -958,6 +1019,13 @@
  (http://jdbm.sourceforge.net/).</em>) should be appended to the NOTICE
  document.
         	</p>	
+        	<p>
+The contents of the NOTICE document should be included by all downstream distributors
+and packagers. So, this is the right place for all required credits and attribution
+notices required by any of the contents of the distribution (whether legally or ethically).
+It is better to include any other types of explanations and notes
+in the RELEASE-NOTES or in a README.
+        	</p>
         </section>
         <section id='note-votes'><title>VOTEs</title>
         	<p>

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=468977&r1=468976&r2=468977
==============================================================================
--- incubator/public/trunk/site-publish/guides/releasemanagement.html (original)
+++ incubator/public/trunk/site-publish/guides/releasemanagement.html Sun Oct 29 12:34:31
2006
@@ -959,6 +959,73 @@
 The release notes document should therefore be committed to the source
 repository so that it ships with the source distribution.
             </p>
+<p>
+The first paragraph of the release notes should introduce the project and the release.
+It is often useful to characterise the release (TODO examples). Spend time thinking
+about the best organisation. Important information should be prominent.
+            </p>
+<p>
+The exact contents of the release notes varies and it is not unusual for 
+this content to be distributed amongst several documents. This is fine:
+these recommendations should be viewed as pertaining to the mass of
+notes that accumpany the release and do not need to be included 
+in any particular document.
+            </p>
+<p>
+Any changes which may effect a user who wishes to replace the last version with
+this should be highlighted. In particular, document:
+            </p>
+<ul>
+            	<li>Deprecations</li>
+            	<li>Binary incompatibilities</li>
+            	<li>Semantic incompatibilities (TODO: glossary)</li>
+            </ul>
+<p>
+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>
+</div>
+<h3>
+   <a name="note-compatibility-checkers">Compatibility Checkers</a>
+</h3>
+<div class="section-content">
+<p>
+Some tools used by Apache projects:
+			</p>
+<ul>
+				<li>Java
+					<ul>
+						<li><a href="http://clirr.sourceforge.net//">Clirr</a> works on binaries</li>
+						<li><a href="http://jdiff.sourceforge.net/">JDiff</a> uses sources</li>
+					</ul>
+				</li>
+			</ul>
+</div>
+<h3>
+   <a name="notes-change-log">Change Logs</a>
+</h3>
+<div class="section-content">
+<p>
+TODO: should this be in best practices
+TODO: add examples
+        	</p>
+<p>
+A change log indicates the changes made to the project since the last release.
+Some projects include a change log in the release notes documents.
+Others use a separate document often called <code>ChangeLog</code>.
+Maven can be used to generate a change log as part of the project documentation.
+        	</p>
+<p>
+Change logs can be created in various ways. Some project ask committers to fill
+in details each time they commit. Other rely on analysing the commit messages
+when the release is prepared. (To do this, go through the logs since the revision
+of the last release. TODO example)
+        	</p>
+<p>
+The change log typically includes every feature added and every bug resolved since 
+the last release.
+        	</p>
 </div>
 <h3>
    <a name="notes-signing-releases">Signing Releases</a>
@@ -1184,6 +1251,13 @@
  <em>This product includes software developed by The JDBM Project
  (http://jdbm.sourceforge.net/).</em>) should be appended to the NOTICE
  document.
+        	</p>
+<p>
+The contents of the NOTICE document should be included by all downstream distributors
+and packagers. So, this is the right place for all required credits and attribution
+notices required by any of the contents of the distribution (whether legally or ethically).
+It is better to include any other types of explanations and notes
+in the RELEASE-NOTES or in a README.
         	</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