incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject svn commit: r607865 - in /incubator/public/trunk: site-author/guides/releasemanagement.xml site-publish/guides/releasemanagement.html
Date Tue, 01 Jan 2008 16:37:12 GMT
Author: rdonkin
Date: Tue Jan  1 08:37:12 2008
New Revision: 607865

URL: http://svn.apache.org/viewvc?rev=607865&view=rev
Log:
Added material on layouts

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=607865&r1=607864&r2=607865&view=diff
==============================================================================
--- incubator/public/trunk/site-author/guides/releasemanagement.xml (original)
+++ incubator/public/trunk/site-author/guides/releasemanagement.xml Tue Jan  1 08:37:12 2008
@@ -324,8 +324,109 @@
       </section>
       <section id='distribution-best-practice'><title>Best Practice</title>
         <section id='distribution-layout'><title>Layout</title>
+          <p>
+            A podling is free to choose a suitable layout for it's released
+            artifacts within <code>www.apache.org/dist/incubator/<em>podling</em></code>.
+            It is recommended that standard layouts (commonly used by other projects) 
+            are studied and that the layout adopted is documented in the podling's 
+            release documentation. The descriptions which follow can be used as a 
+            useful basis for this documentation
+          </p><p>
+            The choice between different layouts is mostly subjective branding.
+            The mirroring and archiving infrastructure should work well
+            with most choices.
+          </p>
+          <section id='distribution-layout-plain'><title>Plain Artifacts</title>
+            <p>
+          All artifacts, sums and signatures should be placed in
+          <code>www.apache.org/dist/incubator/<em>podling</em></code>.
No release
+          documentation is placed within the distribution directory.
+            </p>
+          </section>
+          <section id='distribution-layout-misc'><title>Miscellaneous Documents</title>
+            <p>
+            All files contained in <code>www.apache.org/dist</code> will be mirrored.
+            So, other documents placed in the distribution directories will be 
+            available on the mirrors for those casual browsers.
+            </p><p>
+            As is traditional in some communities, some like to add notices 
+            (such as <code>RELEASE_NOTES</code>, <code>README</code>

+            and <code>CHANGES</code>) for each release. Note that from publicity
+            perspective it may be effective to include this information on the download page.
+            </p><p>
+            The HTTPD runs with fancy indexing enabled. So, creating <code>HEADER.html</code>
and
+            <code>FOOTER.html</code> documents allows the text of the index page
to be customised.
+            </p>
+          </section>
+          <section id='distribution-layout-structured'><title>A Structured Layout</title>
+            <p>
+            Many projects use structured layouts. For example:
+            </p>
+            <ul>
+              <li><a href='http://www.apache.org/dist/ant/'>Ant</a></li>
+              <li><a href='http://www.apache.org/dist/httpd/'>HTTPD</a></li>
+            </ul>
+            <p>
+            The common theme is that each type of distribution is grouped into a
+            subdirectory. For example, binary releases into <code>binaries</code>
+            and source releases into <code>source</code> (say). 
+            </p>
+            <p>
+            Often symbolic links are created from the root of the project distribution
+            directory to the latest version of each release. This allows scripts or users
to
+            easily locate the latest release.
+            </p>
+          </section>
         </section>
         <section id='distribution-release-documentation'><title>Release Documentation</title>
+          <p>
+          Many project distribute notices for a release (such as <code>RELEASE_NOTES</code>,

+          <code>README</code>, <code>CHANGES</code> and so on) in
addition to the main
+          compressed archives. This allows users to read them and decide whether they want
+          to download the archive artifacts. 
+          </p><p>
+          There are also some compelling arguments for making the documentation for a release
+          available for browsing online. (Issuing documentation as compressed archives is
just
+          another type of distribution and the standard rules for artifacts apply.) This
+          makes support of releases easier and helps users understand which release
+          is most appropriate for them.
+          </p><p>
+          Some projects do exactly this.
+          For example:
+          </p>
+          <ul>
+            <li>HTTPD
+              <ul>
+                <li><a href='http://httpd.apache.org/docs/2.0/'>2.0</a></li>
+                <li><a href='http://httpd.apache.org/docs/2.2/'>2.2</a></li>
+              </ul>
+            </li>
+            <li><a href='http://commons.apache.org/digester/'>Commons Digester</a>
+              <ul>
+                <li><a href='http://commons.apache.org/digester/commons-digester-1.7/apidocs/'>1.7
API</a></li>
+                <li><a href='http://commons.apache.org/digester/commons-digester-1.6/docs/api/'>1.6
API</a></li>
+              </ul>
+            </li>
+          </ul>
+          <p>
+          Online documentation should be archived so that it can be easily recreated.
+          Though using <code>www.apache.org/dist</code> 
+          for these files is convenient and ensures that they are archived, it should not

+          be used for this purpose. Documentation typically consists of many relatively 
+          small files and so is inefficient to sync. Users will view it using http and so

+          there is no advantage in these files being distributed to the mirrors. The cost
+          of syncing to the mirrors should therefore be avoided. 
+          </p><p>
+          The best approach is to commit the documentation for a release into subversion.

+          Then check out into a directory in the website.
+          Generally, checking generated documentation into source control is often 
+          considered bad practise. But it is very suitable for fixing the documentation 
+          for a particular release.
+          </p><p>
+          It would be possible to use the subversion URL directly. However, checking out

+          into the website space is better from the perspective of server load and website

+          mirroring. So that is recommended.
+       </p>
         </section>
         <section id='archiving-old-releases'><title>Archiving Old Releases</title>
           <p>
@@ -409,34 +510,13 @@
       </section>
       
 <!--
-        </p><p>
-        A podling is free to choose a suitable layout. However, it is recommended that the
standard layouts
-        are studied. A podling should document it's layout (feel to start with the
-        prose in this document or from the Apache guides).
-        </p>   <p>
-        HTTPD tricks - HEADER.html FOOTER.html
+
 
         </p><p>
         Eclipse: see http://mail-archives.apache.org/mod_mbox/incubator-general/200711.mbox/%3c474F3221.3040800@schor.com%3e
         </p>
        <section id='documentation'>
-       <p>
-       References to best practice on preserving documentation on line for each releases.

-       </p><p>
-       Online documentation typically consists of many relatively small files and so is inefficient
to 
-       sync. Users will view using http and so there is no need for these files to be distributed
to the
-       mirrors. Though using dist for these files is convenient and ensures that they are
archived,
-       it should not be used for this purpose. 
-       </p><p>
-       The best approach is to check in the documentation for a release into subversion.
It can then 
-       be checked out a directory in the website.
-       </p><p>
-       Generally, checking generated documentation into source control is often considered
bad practice.
-       As a method for fixing the documentation for a particular release.
-       </p><p>
-       It is possible to use the subversion URL directly. Checking out into the website space
is 
-       better from the perspective of server load and mirroring.
-       </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?rev=607865&r1=607864&r2=607865&view=diff
==============================================================================
--- incubator/public/trunk/site-publish/guides/releasemanagement.html (original)
+++ incubator/public/trunk/site-publish/guides/releasemanagement.html Tue Jan  1 08:37:12
2008
@@ -200,6 +200,20 @@
 <li><a href='#distribution-layout'>
 Layout
  </a>
+ <ul>
+<li><a href='#distribution-layout-plain'>
+Plain Artifacts
+ </a>
+</li>
+<li><a href='#distribution-layout-misc'>
+Miscellaneous Documents
+ </a>
+</li>
+<li><a href='#distribution-layout-structured'>
+A Structured Layout
+ </a>
+</li>
+</ul>
 </li>
 <li><a href='#distribution-release-documentation'>
 Release Documentation
@@ -905,11 +919,128 @@
    <a name="distribution-layout">Layout</a>
 </h4>
 <div class="section-content">
+<p>
+            A podling is free to choose a suitable layout for it's released
+            artifacts within <code>www.apache.org/dist/incubator/<em>podling</em></code>.
+            It is recommended that standard layouts (commonly used by other projects) 
+            are studied and that the layout adopted is documented in the podling's 
+            release documentation. The descriptions which follow can be used as a 
+            useful basis for this documentation
+          </p>
+<p>
+            The choice between different layouts is mostly subjective branding.
+            The mirroring and archiving infrastructure should work well
+            with most choices.
+          </p>
+<h5> 
+   <a name="distribution-layout-plain">Plain Artifacts</a> 
+</h5> 
+<div class="section-content">
+<p>
+          All artifacts, sums and signatures should be placed in
+          <code>www.apache.org/dist/incubator/<em>podling</em></code>.
No release
+          documentation is placed within the distribution directory.
+            </p>
+</div>
+<h5> 
+   <a name="distribution-layout-misc">Miscellaneous Documents</a> 
+</h5> 
+<div class="section-content">
+<p>
+            All files contained in <code>www.apache.org/dist</code> will be mirrored.
+            So, other documents placed in the distribution directories will be 
+            available on the mirrors for those casual browsers.
+            </p>
+<p>
+            As is traditional in some communities, some like to add notices 
+            (such as <code>RELEASE_NOTES</code>, <code>README</code>

+            and <code>CHANGES</code>) for each release. Note that from publicity
+            perspective it may be effective to include this information on the download page.
+            </p>
+<p>
+            The HTTPD runs with fancy indexing enabled. So, creating <code>HEADER.html</code>
and
+            <code>FOOTER.html</code> documents allows the text of the index page
to be customised.
+            </p>
+</div>
+<h5> 
+   <a name="distribution-layout-structured">A Structured Layout</a> 
+</h5> 
+<div class="section-content">
+<p>
+            Many projects use structured layouts. For example:
+            </p>
+<ul>
+              <li><a href="http://www.apache.org/dist/ant/">Ant</a></li>
+              <li><a href="http://www.apache.org/dist/httpd/">HTTPD</a></li>
+            </ul>
+<p>
+            The common theme is that each type of distribution is grouped into a
+            subdirectory. For example, binary releases into <code>binaries</code>
+            and source releases into <code>source</code> (say). 
+            </p>
+<p>
+            Often symbolic links are created from the root of the project distribution
+            directory to the latest version of each release. This allows scripts or users
to
+            easily locate the latest release.
+            </p>
+</div>
 </div>
 <h4>
    <a name="distribution-release-documentation">Release Documentation</a>
 </h4>
 <div class="section-content">
+<p>
+          Many project distribute notices for a release (such as <code>RELEASE_NOTES</code>,

+          <code>README</code>, <code>CHANGES</code> and so on) in
addition to the main
+          compressed archives. This allows users to read them and decide whether they want
+          to download the archive artifacts. 
+          </p>
+<p>
+          There are also some compelling arguments for making the documentation for a release
+          available for browsing online. (Issuing documentation as compressed archives is
just
+          another type of distribution and the standard rules for artifacts apply.) This
+          makes support of releases easier and helps users understand which release
+          is most appropriate for them.
+          </p>
+<p>
+          Some projects do exactly this.
+          For example:
+          </p>
+<ul>
+            <li>HTTPD
+              <ul>
+                <li><a href="http://httpd.apache.org/docs/2.0/">2.0</a></li>
+                <li><a href="http://httpd.apache.org/docs/2.2/">2.2</a></li>
+              </ul>
+            </li>
+            <li><a href="http://commons.apache.org/digester/">Commons Digester</a>
+              <ul>
+                <li><a href="http://commons.apache.org/digester/commons-digester-1.7/apidocs/">1.7
API</a></li>
+                <li><a href="http://commons.apache.org/digester/commons-digester-1.6/docs/api/">1.6
API</a></li>
+              </ul>
+            </li>
+          </ul>
+<p>
+          Online documentation should be archived so that it can be easily recreated.
+          Though using <code>www.apache.org/dist</code> 
+          for these files is convenient and ensures that they are archived, it should not

+          be used for this purpose. Documentation typically consists of many relatively 
+          small files and so is inefficient to sync. Users will view it using http and so

+          there is no advantage in these files being distributed to the mirrors. The cost
+          of syncing to the mirrors should therefore be avoided. 
+          </p>
+<p>
+          The best approach is to commit the documentation for a release into subversion.

+          Then check out into a directory in the website.
+          Generally, checking generated documentation into source control is often 
+          considered bad practise. But it is very suitable for fixing the documentation 
+          for a particular release.
+          </p>
+<p>
+          It would be possible to use the subversion URL directly. However, checking out

+          into the website space is better from the perspective of server load and website

+          mirroring. So that is recommended.
+       </p>
 </div>
 <h4>
    <a name="archiving-old-releases">Archiving Old Releases</a>



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


Mime
View raw message