commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From di...@apache.org
Subject cvs commit: jakarta-commons/docs/releases releases.html versioning.html
Date Sun, 14 Mar 2004 19:42:41 GMT
dirkv       2004/03/14 11:42:41

  Added:       docs/releases releases.html versioning.html
  Log:
  move into releases & sandbox subdirs
  
  Revision  Changes    Path
  1.1                  jakarta-commons/docs/releases/releases.html
  
  Index: releases.html
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  
  <!--
  Copyright 1999-2004 The Apache Software Foundation
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
  
  http://www.apache.org/licenses/LICENSE-2.0
  
  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
  -->
  
  
  <!-- Content Stylesheet for Site -->
  
          
  <!-- start the processing -->
      <!-- ====================================================================== -->
      <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
      <!-- Main Page Section -->
      <!-- ====================================================================== -->
      <html>
          <head>
              <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
  
                                                      <meta name="author" value="Commons Documentation Team">
              <meta name="email" value="commons-dev@jakarta.apache.org">
              
             
                                      
                          
              <title>Commons - Creating Commons Package Releases</title>
          </head>
  
          <body bgcolor="#ffffff" text="#000000" link="#525D76">        
              <table border="0" width="100%" cellspacing="0">
                  <!-- TOP IMAGE -->
                  <tr>
                      <td align="left">
  <a href="http://jakarta.apache.org"><img src="http://jakarta.apache.org/images/jakarta-logo.gif" border="0"/></a>
  </td>
  <td align="right">
  <a href="http://jakarta.apache.org/commons/"><img src="../images/logo.jpg" alt="Commons" border="0"/></a>
  </td>
                  </tr>
              </table>
              <table border="0" width="100%" cellspacing="4">
                  <tr><td colspan="2">
                      <hr noshade="" size="1"/>
                  </td></tr>
                  
                  <tr>
                      <!-- LEFT SIDE NAVIGATION -->
                      <td width="20%" valign="top" nowrap="true">
                      
      <!-- ============================================================ -->
  
                  <p><strong>About Us</strong></p>
          <ul>
                      <li>    <a href="http://jakarta.apache.org/commons/">Home</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/contributors.html">Contributors</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/license.html">License</a>
  </li>
                      <li>    <a href="../components.html">Components</a>
  </li>
                      <li>    <a href="../sandbox/index.html">Sandbox</a>
  </li>
                  </ul>
              <p><strong>Download</strong></p>
          <ul>
                      <li>    <a href="http://jakarta.apache.org/site/binindex.cgi">Binaries (mirrored)</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/site/sourceindex.cgi">Source Code (mirrored)</a>
  </li>
                      <li>    <a href="http://cvs.apache.org/builds/jakarta-commons/nightly/">Nightly Snapshots</a>
  </li>
                  </ul>
              <p><strong>View CVS</strong></p>
          <ul>
                      <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons/">Components</a>
  </li>
                      <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons-sandbox/">Sandbox</a>
  </li>
                  </ul>
              <p><strong>General Information</strong></p>
          <ul>
                      <li>    <a href="http://jakarta.apache.org/commons/charter.html">Charter</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/volunteering.html">Volunteering</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/patches.html">Contributing Patches</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/releases/index.html">Releasing Components</a>
  </li>
                  </ul>
              <p><strong>Jakarta Community</strong></p>
          <ul>
                      <li>    <a href="http://jakarta.apache.org/site/getinvolved.html">Get Involved</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/site/mail.html">Mailing Lists</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/site/cvsindex.html">Access CVS Repositories</a>
  </li>
                  </ul>
              <p><strong>Commons Resources (Unofficial)</strong></p>
          <ul>
                      <li>    <a href="http://nagoya.apache.org/wiki/apachewiki.cgi?JakartaCommonsProjectPages">Wiki</a>
  </li>
                      <li>    <a href="http://jakarta.terra-intl.com/commons/">Japanese Translation</a>
  </li>
                      <li>    <a href="http://jakarta.apache-korea.org/commons/">Korean Translation</a>
  </li>
                  </ul>
              <p><strong>Related</strong></p>
          <ul>
                      <li>    <a href="http://commons.apache.org/">Apache Commons</a>
  </li>
                      <li>    <a href="http://db.apache.org/commons/">DB Commons</a>
  </li>
                      <li>    <a href="http://xml.apache.org/commons/">XML Commons</a>
  </li>
                  </ul>
                          </td>
                      <td width="80%" align="left" valign="top">
                                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Note"><strong>Note</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
  This document is now <strong>deprecated</strong> since it describes how to create an unmirrored release.
  Mirroring releases makes downloads quicker for users and saves bandwidth for Apache.
  So please, mirror all new releases!
          </p>
                                                  <p>
  The new documentation can be found <a href="releases/index.html">here</a>.            
          </p>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Introduction"><strong>Introduction</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>The <em>Jakarta Commons</em> project differs from many other Jakarta
      hosted projects because it is comprised of multiple, independently
      released packages.  Therefore, the release procedure for an individual
      package needs to be documented so that package authors follow consistent
      practices.</p>
                                                  <p>Individual packages (such as Collections) might vary from these practices
      because they are somewhat larger than the typical Commons package, but
      these steps should prove sufficient for the majority of cases.</p>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Step By Step Instructions"><strong>Step By Step Instructions</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>The following steps are required to create and deploy a release version
      of a Commons library package.  The <code>example text</code> consistently
      assumes that we are releasing version <em>1.2</em> of the <em>foo</em>
      package.</p>
                                                  <p><b>For components other than Collections:</b></p>
                                                  <ol>
  
        <li>Announce your proposed release of a particular package to the
            <strong>commons-dev@jakarta.apache.org</strong> mailing list,
            and ask for a vote.  Per the Commons Project charter, votes of
            committers on the particular package in question (as listed in the
            <code>STATUS.html</code> file) are binding.<br /><br /></li>
  
        <li>Log on to jakarta.apache.org (via SSH) and create a new subdirectory for the
            release you are about to create.  For example:
  <pre>
  cd /www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/
  mkdir v1.2
  
  </pre>Please make sure that the directory you create is group writable.</li>
  
        <li>Check out and thoroughly test the package code that you plan to
            release.<br /><br /></li>
  
        <li>Update the project version number in the <code>build.xml</code>
            file for this project.  If the <code>foo</code> project follows
            the usual <code>build.xml</code> conventions, there will be an
            Ant property named <code>component.version</code> that would be
            updated to <code>1.2</code>.  Check in any files you have
            modified.<br /><br /></li>
  
        <li>Tag <strong>only</strong> the files in the subdirectory for this
            package with the package name (in caps) and version number for the
            package you are creating.  For example,
  <pre>
  cd $JAKARTA_COMMONS_HOME/foo
  cvs tag FOO_1_2
  </pre></li>
  
        <li>Regenerate the binary distribution of the code by running the
            <code>dist</code> target.  Review the generated documentation
            to ensure that it correctly reflects the functionality (and the
            version number) of this code.<br /><br /></li>
  
        <li>Based on the contents of the <code>dist</code> subdirectory that
            was created by the previous step, create the binary distributions
            for this release.  For example,
  <pre>
  cd $JAKARTA_COMMONS_HOME/foo
  mv dist commons-foo-1.2
  tar zcvf commons-foo-1.2.tar.gz commons-foo-1.2
  zip -r commons-foo-1.2.zip commons-foo-1.2
  mv commons-foo-1.2 dist
  </pre></li>
  
        <li>Upload the binary distribution files to the newly created directory
            on daedalus.  For example (where "xyz" is your login),
  <pre>
  cd $JAKARTA_COMMONS_HOME/foo
  scp commons-foo-1.2.* \
   xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/
  </pre>
  Please make sure that the files you copy are group writable.</li>
  
        <li>Log in to cvs.apache.org and create the source distributions, based on the
            tag specified earlier, and move these files to the distribution
            directory as well.  For example (where "xyz" is your login),
  <pre>
  mkdir temp
  cd temp
  cvs -d /home/cvspublic export -r FOO_1_2 jakarta-commons
  mv jakarta-commons commons-foo-1.2-src
  tar zcvf commons-foo-1.2-src.tar.gz commons-foo-1.2-src
  zip -r commons-foo-1.2-src.zip commons-foo-1.2-src
  rm -rf commons-foo-1.2-src
  scp commons-foo-1.2-src.* \
    xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/
  </pre>
  Please make sure that the files you copy are group writable.<br /></li>
  
        <li>Follow standard procedures to update the Jakarta web site (stored in
            CVS repository <code>jakarta-site2</code> to reflect the availability
            of the new release.  Generally, you will be updating the following
            pages:
            <ul>
            <li><code>xdocs/site/binindex.xml</code> - Create a link to the
                release directory under the <strong>Release Builds</strong>
                heading.</li>
            <li><code>xdocs/site/sourceindex.xml</code> - Create a link to the
                release directory under the <strong>Release Builds</strong>
                heading.</li>
            <li><code>xdocs/site/news.xml</code> - Create a news item that
                describes the new release, and includes hyperlinks to the
                release directory.</li>
            </ul>
            <ul>
              <li>Then run ant at the base to generate the new docs and commit the changes to jakarta-site2.
  <pre>
  ant
  cvs commit -m "update to reflect release of commons-foo"
  </pre></li>
              <li>If you have an account on daedalus, log in and update the web site:
  <pre>
  cd /www/jakarta.apache.org
  cvs update index.html site
  </pre></li>
  <li>You can also update the API docs and Release notes link:
  <pre>
  cd /www/jakarta.apache.org/commons/foo
  rm RELEASE-NOTES.txt
  rm api
  rm -rf commons-foo-1.1
  tar zxf ../../builds/jakarta-commons/release/commons-foo/v1.2/commons-foo-1.2.tar.gz
  ln -s commons-foo-1.2/RELEASE-NOTES.txt RELEASE-NOTES.txt
  ln -s commons-foo-1.2/docs/api api
  </pre></li>
            </ul>
            <br />
            </li>
            
  <li>Update the pertinent documents in the jakarta-commons/xdocs CVS and then build the docs by running ant.  These pages will probably include components.xml and foo.xml.  CVS commit, then if you have an account on daedalus, update the commons website with a cvs udpate in /www/jakarta.apache.org/commons.<br /></li>
  
        <li>Announce the availability of the new package on (at least) the
            following mailing lists:
            <ul>
            <li>announcements@jakarta.apache.org</li>
            <li>commons-dev@jakarta.apache.org</li>
            <li>commons-user@jakarta.apache.org</li>
            </ul><br /></li>
  
  <li>Ensure that the pertinent documents in the component's home directory are updated to reflect the new release.
  In particular :
      <ul>
      <li>In <strong>STATUS.html</strong>:
          <ul>
          <li>Update <code>Release Info</code> section</li>
          <li>Ensure <code>Dependencies</code> is correct</li>
          <li>Ensure completed tasks are removed from <code>To Do</code> list</li>
          </ul>
      </li>
      <li>Update build with new current version</li>
      </ul>
  <br /></li>
  <li>Check in bugzilla for all bugs which have been marked <code>LATER</code> and update their status appropriately. If you need to have some changes made to bugzilla you can contact <a href="mailto:mvdb@apache.org">mvdb@apache.org</a><br /><br /></li>
  </ol>
                                                  <p><b>For Collections:</b></p>
                                                  <ol>
      
        <li>Follow steps 1-5 above.</li>
        
        <li>Review the build.xml file to make sure that the "cvs.tag" 
        property is set correctly.  For example,
        
  <pre>
  &lt;property name="cvs.tag" value="FOO_1_2"/&gt;</pre></li>
  
        <li>Review the build.properties file to make sure that the 
        "cvs.root" property is set correctly.  For example,
  <pre>
  ## in build.properties where "xyz" is your login
  cvs.root=:pserver:xyz@localhost:/home/cvs
  </pre></li>
        
        <li>From the component directory, run <i>ant clean dist dist-src</i>.</li>
        
        <li>Upload the binary distribution files to the newly created directory
            on daedalus.  For example (where "xyz" is your login),
  <pre>
  cd $JAKARTA_COMMONS_HOME/foo/dist
  scp commons-foo-1.2* \
   xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/
  </pre></li>
  
        <li>Copy the release notes to daedalus.  For example (where "xyz" is your login),
  <pre>
  cd $JAKARTA_COMMONS_HOME/foo/dist
  scp RELEASE-NOTES-1.2.html \
   xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/
  </pre></li>
  
        <li>Update the <code>components.xml</code> and the <code>collections.xml</code>
            (including the link to the <code>STATUS.html</code>) files.  Run the 
            <code>ant</code> command at the root of the <code>jakarta-commons</code>
            module, which will build HTML versions of those documents in the 
            <code>docs</code> directory.  Check in the generated docs.</li>
            
        <li>Copy the API docs from the Collections build to the 
            <code>jakarta-commons/docs/collections/api</code> directory in CVS.
            Be sure to <i>remove</i> Javadocs for any Collections that have been
            permanently deleted.</li>
            
        <li>Log onto jakarta.apache.org and perform a CVS update to grab the new
            site documentation:
  
  <pre>
  cd /www/jakarta.apache.org/commons/
  cvs update
  </pre></li>      
  
        <li>Follow steps 10+ above.</li>
        
      </ol>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                          </td>
                  </tr>
  
                  <!-- FOOTER -->
                  <tr><td colspan="2">
                      <hr noshade="" size="1"/>
                  </td></tr>
                  <tr><td colspan="2">
                      <div align="center"><font color="#525D76" size="-1"><em>
                      Copyright &#169; 1999-2004, The Apache Software Foundation
                      </em></font></div>
                  </td></tr>
              </table>
          </body>
      </html>
  <!-- end the processing -->
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  1.1                  jakarta-commons/docs/releases/versioning.html
  
  Index: versioning.html
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  
  <!--
  Copyright 1999-2004 The Apache Software Foundation
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
  
  http://www.apache.org/licenses/LICENSE-2.0
  
  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
  -->
  
  
  <!-- Content Stylesheet for Site -->
  
          
  <!-- start the processing -->
      <!-- ====================================================================== -->
      <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
      <!-- Main Page Section -->
      <!-- ====================================================================== -->
      <html>
          <head>
              <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
  
                                                      <meta name="author" value="Commons Documentation Team">
              <meta name="email" value="commons-dev@jakarta.apache.org">
                                          <meta name="author" value="Morgan Delagrange">
              <meta name="email" value="morgand@apache.org">
                                          <meta name="author" value="Rodney Waldhoff">
              <meta name="email" value="rwaldhoff@apache.org">
              
             
                                      
                          
              <title>Commons - Versioning Guidelines</title>
          </head>
  
          <body bgcolor="#ffffff" text="#000000" link="#525D76">        
              <table border="0" width="100%" cellspacing="0">
                  <!-- TOP IMAGE -->
                  <tr>
                      <td align="left">
  <a href="http://jakarta.apache.org"><img src="http://jakarta.apache.org/images/jakarta-logo.gif" border="0"/></a>
  </td>
  <td align="right">
  <a href="http://jakarta.apache.org/commons/"><img src="../images/logo.jpg" alt="Commons" border="0"/></a>
  </td>
                  </tr>
              </table>
              <table border="0" width="100%" cellspacing="4">
                  <tr><td colspan="2">
                      <hr noshade="" size="1"/>
                  </td></tr>
                  
                  <tr>
                      <!-- LEFT SIDE NAVIGATION -->
                      <td width="20%" valign="top" nowrap="true">
                      
      <!-- ============================================================ -->
  
                  <p><strong>About Us</strong></p>
          <ul>
                      <li>    <a href="http://jakarta.apache.org/commons/">Home</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/contributors.html">Contributors</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/license.html">License</a>
  </li>
                      <li>    <a href="../components.html">Components</a>
  </li>
                      <li>    <a href="../sandbox/index.html">Sandbox</a>
  </li>
                  </ul>
              <p><strong>Download</strong></p>
          <ul>
                      <li>    <a href="http://jakarta.apache.org/site/binindex.cgi">Binaries (mirrored)</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/site/sourceindex.cgi">Source Code (mirrored)</a>
  </li>
                      <li>    <a href="http://cvs.apache.org/builds/jakarta-commons/nightly/">Nightly Snapshots</a>
  </li>
                  </ul>
              <p><strong>View CVS</strong></p>
          <ul>
                      <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons/">Components</a>
  </li>
                      <li>    <a href="http://cvs.apache.org/viewcvs/jakarta-commons-sandbox/">Sandbox</a>
  </li>
                  </ul>
              <p><strong>General Information</strong></p>
          <ul>
                      <li>    <a href="http://jakarta.apache.org/commons/charter.html">Charter</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/volunteering.html">Volunteering</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/patches.html">Contributing Patches</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/commons/releases/index.html">Releasing Components</a>
  </li>
                  </ul>
              <p><strong>Jakarta Community</strong></p>
          <ul>
                      <li>    <a href="http://jakarta.apache.org/site/getinvolved.html">Get Involved</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/site/mail.html">Mailing Lists</a>
  </li>
                      <li>    <a href="http://jakarta.apache.org/site/cvsindex.html">Access CVS Repositories</a>
  </li>
                  </ul>
              <p><strong>Commons Resources (Unofficial)</strong></p>
          <ul>
                      <li>    <a href="http://nagoya.apache.org/wiki/apachewiki.cgi?JakartaCommonsProjectPages">Wiki</a>
  </li>
                      <li>    <a href="http://jakarta.terra-intl.com/commons/">Japanese Translation</a>
  </li>
                      <li>    <a href="http://jakarta.apache-korea.org/commons/">Korean Translation</a>
  </li>
                  </ul>
              <p><strong>Related</strong></p>
          <ul>
                      <li>    <a href="http://commons.apache.org/">Apache Commons</a>
  </li>
                      <li>    <a href="http://db.apache.org/commons/">DB Commons</a>
  </li>
                      <li>    <a href="http://xml.apache.org/commons/">XML Commons</a>
  </li>
                  </ul>
                          </td>
                      <td width="80%" align="left" valign="top">
                                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Overview"><strong>Overview</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>This document provides:</p>
                                                  <ul>
      <li>
       a set of guidelines intended to help the Jakarta-Commons
       team balance the need to provide a stable interface to
       clients with the growth and evolution of components over
       time,
      </li>
      <li>
       a language for describing the changes to a component
       and the types of incompatibilities such changes may
       create,
      </li>
      <li>
       and a protocol for communicating those changes and
       incompatibilities to users and developers.
      </li>
     </ul>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Interface Types"><strong>Interface Types</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
      We identify three distinct categories of interfaces or APIs
      within a component: <em>external</em>, <em>internal</em>
      and <em>private</em>.
     </p>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="The External Interface"><strong>The External Interface</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       The <em>external</em> interface of component is composed of the
       public-facing classes, interfaces, methods and attributes
       provided by the component--those that are likely to be
       used by clients to the component.
      </p>
                                                  <p>
       For obvious reasons, we try to avoid or at least
       acknowledge changes to the external interface.
      </p>
                                                  <p>
       The external interface of a component <em>may</em> correspond to
       the <code>public</code> scope classes and members, but this is not
       always the case. For example, a <code>protected</code> method of a class
       designed to be extended by the clients of a component may
       be deemed part of the external interface.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="The Internal Interface"><strong>The Internal Interface</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       The <em>internal</em> interface of a component is composed of the
       classes, methods and attributes that are primarily or
       exclusively intended for use by the component
       implementation itself.  Clients to the component are
       unlikely to use or be concerned with the internal
       interface.
      </p>
                                                  <p>
       The internal interface of a component <em>may</em> correspond to
       the <code>package</code> and <code>private</code> scope classes
       and members of the component, but this is not always the case.
       For example, a component implementation may be split over
       multiple packages and hence require <code>protected</code> scope
       members, or may, for design reasons, include an interface
       intended primarily for internal use.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="The Private Interface"><strong>The Private Interface</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       The <em>private</em> interface of a component is just that--the set
       of classes, methods and attributes that have "package" or
       <code>private</code> scope and hence cannot be used by external clients
       by virtue of the Java Language Specification.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <p>
      Whenever a class, interface or member is considered part of the
      external or internal interface of a component, it should be
      clearly indicated as such in the JavaDoc comments or other
      documentation for the component. (We may want to consider
      adding custom JavaDoc tags for this purpose.)
     </p>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Types of Change"><strong>Types of Change</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
      We can categorize the changes to a component according to
      the degree to which these changes are compatible with
      previous releases of the component.  We define three such
      categories: <em>fully-compatible</em>, <em>interface-compatible</em>,
      and <em>external-interface-compatible</em>.
     </p>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Fully-Compatible Changes"><strong>Fully-Compatible Changes</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       Release <i>B</i> is said to be <em>fully-compatible</em>
       with Release <i>A</i> if <i>B</i> can simply replace <i>A</i>
       in (<a href="#note1">nearly</a>) all circumstances
       and deployments without changing the client code or
       configuration, and without changing the semantics of any
       <code>public</code> or <code>protected</code> member.
      </p>
                                                  <p>Examples of fully-compatible changes include:</p>
                                                  <ul>
       <li>adding a non-<code>abstract</code> method to a class</li>
       <li>adding a class or interface to a component</li>
       <li>
        changing a member from <code>private</code> to
        <code>protected</code>
       </li>
       <li>
        changing a <code>private</code> attribute to
        a <code>private</code> method
       </li>
       <li>
        changing an implementation such that a given external
        library is no longer needed by the component
       </li>
       <li>
        changing a method or class from <code>final</code> to
        non-<code>final</code>
       </li>
       <li>
        deprecating, but not otherwise changing, a class, inteface
        or member
       </li>
       <li>
        changing a component in order to fix a defect (a
        deviation from the documented or reasonably expected
        behavior), assuming no other incompatibilities are
        introduced
       </li>
      </ul>
                                                  <p>Examples of changes which are not fully-compatible include:</p>
                                                  <ul>
       <li>
        a release that no longer supports the same set of JREs,
        or that requires new libraries to be added to the
        classpath
       </li>
       <li>
        changing a <code>public</code> or <code>protected</code> method signature
       </li>
       <li>
        changing the default value of an attribute in a
        behaviour-impacting way
       </li>
       <li>
        removing a class, interface, method or attribute
        from either the internal or external interface of
        the component
       </li>
      </ul>
                                                  <p>
       Note that not every non-fully-compatible change
       will cause compilation or readily apparent
       run-time problems.
      </p>
                                                  <p>
       Generally speaking, a fully-compatible change will at
       most change the private interface of a component, or simply
       add classes, methods and attributes whose use is optional
       to both internal and external interface clients.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Interface-Compatible Changes"><strong>Interface-Compatible Changes</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       Release <i>B</i> is said to be "interface-compatible" with
       Release <i>A</i> if (<a href="#note1">nearly</a>) all clients
       that can be compiled with <i>A</i> in the classpath can
       also be compiled with <i>B</i> in the classpath,
       without changing the semantics of any <code>public</code> or
       <code>protected</code> member.  A configuration or
       classpath change may be required.
      </p>
                                                  <p>
        Examples of interface-compatible changes include:
      </p>
                                                  <ul>
        <li>all fully-compatible changes</li>
        <li>
           changing a component such that it now depends
           upon an additional external library or
           configuration file
        </li>
      </ul>
                                                  <p>
        Examples of changes which are not interface-compatible
        include:
      </p>
                                                  <ul>
        <li>
           changing a public or protected method signature
        </li>
        <li>
           changing the default value of an attribute in a
           behaviour changing way
        </li>
        <li>
           removing a class, interface, method or attribute
           from either the internal or external interface of the
           component
        </li>
      </ul>
                                                  <p>
        Generally speaking, an interface-compatible change
        will at most change the private interface of a
        component, or simply add classes, methods and
        attributes whose use is optional to both
        internal and external interface clients.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="External-Interface-Compatible Changes"><strong>External-Interface-Compatible Changes</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       Release <i>B</i> is said to be "external-interface-compatible"
       with Release <i>A</i> if (<a href="#note1">nearly</a>) all
       clients that depend only on the external interface of a
       component and that can be compiled with <i>A</i> in the
       classpath can also be compiled with <i>B</i> in the classpath,
       without changing the semantics of any member in the
       <em>external</em> interface. A configuration or classpath
       change may be required.
      </p>
                                                  <p>
        Examples of external-interface-compatible changes include:
      </p>
                                                  <ul>
        <li>all interface-compatible changes</li>
        <li>
            removing a class, interface, method or attribute from
            the internal interface of the component
        </li>
        <li>
            a change to the internal or private interface of a
            component that requires a change in configuration
            settings or in the external libraries required to
            use the component
        </li>
        <li>
            changes to the internal or private interface of a
            component without impacting the external interface
        </li>
      </ul>
                                                  <p>
        Examples of changes which are not
        external-interface-compatible include:
      </p>
                                                  <ul>
        <li>
          changing the method signature of any method that is
          part of the external interface of the component
        </li>
        <li>
          changing the default value of any attribute that is
          part of the external interface of the component in a
          behaviour changing way
        </li>
        <li>
          removing a class, interface, method or attribute from
          external interface of the component
        </li>
      </ul>
                                                  <p>
        Generally speaking, external-interface-compatible
        changes correspond to changes to at most the internal
        interface of the component or the addition of
        optional classes, interfaces or members to the
        external interface.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Release Types"><strong>Release Types</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
      We identify five types of releases: "Major", "Minor",
      "Point", "Beta" and "Milestone".
     </p>
                                                  <p>
      Developers are encouraged to "upgrade" a release to a
      stronger type whenever the nature or scope of the change
      warrants it.
     </p>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Major Releases"><strong>Major Releases</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       Major releases signify significant changes to a component.
       Developers <em>may</em> perform a major release if there have been
       substantial improvements to the component.  Developers
       <em>must</em> perform a major release whenever the new release
       is not at least interface-compatible the previous release.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Minor Releases"><strong>Minor Releases</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       Minor releases signify enhancements to a component that do
       not necessitate a major release.  Developers <em>may</em> perform a
       minor release if the release is at least
       external-interface-compatible with the previous release.
      <p>
      </p>
       In other words, whenever a client depends upon at most
       the external interface of a component with a given minor
       release, it will work with all subsequent minor releases
       within that major release.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Point Releases"><strong>Point Releases</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       A point release typically involves simple bug fixes or
       optimizations that do not introduce new features.
       Developers <em>may</em> perform a point release if the release
       is at least interface-compatible with the
       previous release.
      </p>
                                                  <p>
       In other words, whenever a client depends upon a component
       with a given point release, it will work with all
       subsequent point releases within that minor release.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Beta Releases"><strong>Beta Releases</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       Developers may, at their option, perform a beta preview of
       any major, minor or point release.  Beta releases may be
       performed for a variety of purposes such as:
      </p>
                                                  <ul>
       <li>Showcasing new, untested features</li>
       <li>Providing early corrections of critical bugs</li>
       <li>Generating a stable version before large-scale changes</li>
      </ul>
                                                  <p>
       While every effort should be made to ensure the quality of
       released code, "beta" releases are essentially provided
       as-is with no guarantees of stability or maintenance.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Milestone Releases"><strong>Milestone Releases</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       Developers may, at their option, offer a milestone
       preview of any major release.  A milestone release is
       appropriate when part of the overall component is
       fully functioning and the team wants to make it more widely
       available for testing. Those features implemented and those
       remaining to be implemented should be clearly defined and
       documented.
      </p>
                                                  <p>
       While every effort should be made to ensure the quality of
       released code, "milestone" releases are essentially
       provided as-is with no guarantees of stability or
       maintenance.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Release Numbers"><strong>Release Numbers</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                          <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Initial Release Number"><strong>Initial Release Number</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       A component's initial release number is generally
       1.0[.0], unless there have been versioned beta releases.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Dissecting the Release Number"><strong>Dissecting the Release Number</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       A release number is comprised of 3 components: the major
       release number, the minor release number, and an optional
       point release number.  Here is a sample release number:
      </p>
                                                  <p><code>2.0.4</code></p>
                                                  <p>and it can be broken into three parts:</p>
                                                  <ul>
       <li>major release: 2</li>
       <li>minor release: 0</li>
       <li>point release: 4</li>
      </ul>
                                                  <p>
       The next release of this component would increment the
       appropriate part of the release number, depending on the
       type of release (major, minor, or point).  For example, a
       subsequent minor release would be version 2.1, or a
       subsequent major release would be 3.0.
      </p>
                                                  <p>
       Note that release numbers are composed of three _integers_,
       not three <em>digits</em>.  Hence if the current release is
       3.9.4, the next minor release is 3.10.0.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Beta Release Numbers"><strong>Beta Release Numbers</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       Beta releases are denoted by adding
       "B&lt;beta version number&gt;" after the release number.  For
       example, if the current release version is 2.0.4, and a
       developer wished to preview the next major release, the
       release would be labeled 3.0-B1.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Milestone Release Numbers"><strong>Milestone Release Numbers</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       Beta releases are denoted by adding
       "M&lt;milestone version number&gt;" after the release number.  For
       example, if the current release version is 2.0.4, and a
       developer wished to preview the next major release, the
       release would be labeled 3.0-M1.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Development States"><strong>Development States</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
      We identify four possible states: "in development", "beta",
      "released", and "unsupported".
     </p>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="In Development State"><strong>In Development State</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
        When a component is "in development", it is new and still
        relatively unstable. Typically components in this state
        do not have any binary releases available beyond the
        nightly builds.  Users should be made aware that this
        component may change its functionality or interface before
        a stable release is achieved.  A "milestone" release may
        be made while the component is still "in development" to
        make the features currently implemented more widely
        available for testing in a more stable test version.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Beta State"><strong>Beta State</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
        When a component has made significant progress toward
        release-quality code, the committers may vote to perform
        a "beta" release.  At this point, the component state will
        change from "in development" to "beta".  The component will
        remain in this state until it is ready for its first major
        release.
      </p>
                                                  <p>
        Note that developers may skip vote to skip the "beta" state
        and go directly to "released", if the component is
        sufficiently stable.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Released State"><strong>Released State</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       When a new component is finally production-quality, the
       developers may vote to perform the first major release.
       At this point, the component status will be changed from
       "beta" to "released".  In the future this component will
       always be considered to be in the "released" state, even
       when new releases are initiated. The only exception is in
       the case of "unsupported" components.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                      <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#828DA6">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Unsupported State"><strong>Unsupported State</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
       Under rare circumstances, committers may vote to make a
       component "unsupported", if there are no resources to
       maintain the library or if it has been completely
       supplanted by another component.  Only "released"
       components may become "unsupported"; components in other
       states will simply be terminated after a brief warning
       period.
      </p>
                              </blockquote>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="Comments"><strong>Comments</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <p>
        Using this approach it is possible to very precisely and
        concisely define the dependencies between a component and
        its clients.
     </p>
                                                  <p>
        For example, suppose that the application Foo depends
        (only) upon features of the commons-superwidget component
        that are part of the external interface in release 2.3.0.
        Then the maintainers of Foo can state with a high degree of
        certainty that Foo will work with any 2.x release of
        superwidget (x &gt;= 3).
     </p>
                                                  <p>
        Similarly, suppose the application Bar depends upon
        features of superwidget that were part of the internal
        interface of release 2.3.0.  Then the maintainers of Bar
        can state with a high degree of certainty that Bar will
        work with any 2.3.x release of superwidget.  Only once 2.4
        (or 3.0) is released will Bar's developers have to
        re-evaluate.
     </p>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
        <tr><td bgcolor="#525D76">
          <font color="#ffffff" face="arial,helvetica,sanserif">
            <a name="End Notes"><strong>End Notes</strong></a>
          </font>
        </td></tr>
        <tr><td>
          <blockquote>
                                      <dl>
      <dt><a name="note1">Note 1</a></dt>
      <dd>
       We say "nearly" here since there are rare
       or unusual circumstances in which changes that are usually
       "safe" may cause problems for a small number of users.
       For example, adding a new method to a component class
       shouldn't in general cause problems for any clients. But it
       may cause problems for some clients who've extended that
       class and already added a method with the same signature in
       their subclass.
      </dd>
     </dl>
                              </blockquote>
          </p>
        </td></tr>
        <tr><td><br/></td></tr>
      </table>
                                          </td>
                  </tr>
  
                  <!-- FOOTER -->
                  <tr><td colspan="2">
                      <hr noshade="" size="1"/>
                  </td></tr>
                  <tr><td colspan="2">
                      <div align="center"><font color="#525D76" size="-1"><em>
                      Copyright &#169; 1999-2004, The Apache Software Foundation
                      </em></font></div>
                  </td></tr>
              </table>
          </body>
      </html>
  <!-- end the processing -->
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message