Author: craigmcc
Date: Tue Nov 22 12:57:00 2005
New Revision: 348249
URL: http://svn.apache.org/viewcvs?rev=348249&view=rev
Log:
Add website page documenting API stability expectations.
Move canonical website subdirectory from "shale" to "struts-shale" for
consistency with other subprojects.
Added:
struts/shale/trunk/xdocs/api-stability.xml (with props)
Modified:
struts/shale/trunk/build/project.xml
struts/shale/trunk/xdocs/navigation.xml
Modified: struts/shale/trunk/build/project.xml
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/build/project.xml?rev=348249&r1=348248&r2=348249&view=diff
==============================================================================
--- struts/shale/trunk/build/project.xml (original)
+++ struts/shale/trunk/build/project.xml Tue Nov 22 12:57:00 2005
@@ -47,7 +47,7 @@
<url>http://struts.apache.org/</url>
<issueTrackingUrl>http://issues.apache.org/bugzilla/</issueTrackingUrl>
<siteAddress>people.apache.org</siteAddress>
- <siteDirectory>/www/struts.apache.org/shale/</siteDirectory>
+ <siteDirectory>/www/struts.apache.org/struts-shale/</siteDirectory>
<distributionDirectory>
/www/svn.apache.org/builds/struts
</distributionDirectory>
Added: struts/shale/trunk/xdocs/api-stability.xml
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/xdocs/api-stability.xml?rev=348249&view=auto
==============================================================================
--- struts/shale/trunk/xdocs/api-stability.xml (added)
+++ struts/shale/trunk/xdocs/api-stability.xml Tue Nov 22 12:57:00 2005
@@ -0,0 +1,276 @@
+<?xml version="1.0"?>
+<document>
+
+ <properties>
+ <title>Shale API Target Audiences and Stability Ratings</title>
+ </properties>
+
+ <body>
+
+ <a name="stability"/>
+ <section name="Shale API Target Audiences and Stability Ratings">
+
+ <a name="stability-introduction"/>
+ <subsection name="Introduction">
+
+ <p>The core services provided by Shale are packaged in a series of
+ JAR files, so that applications not utiizing some of the optional
+ services need not include them. For each service, the APIs in
+ particular Java packages are intended for public use by application
+ developers, while other packages represent the internal implementation
+ of Shale features, and would only be accessed directly if you intend to
+ modify Shale's standard functionality. In the tables below, the
+ intended target audience of each package is described by one of the
+ following terms:</p>
+
+ <ul>
+ <li><em>Application</em> - Applications based on Shale may
+ depend on APIs provided by this package. In general,
+ such APIs will focus on avoiding backwards incompatble
+ changes as they evolve.</li>
+ <li><em>Framework</em> - Developers who wish to extend or
+ modify the default implementation of Shale features
+ may depend on APIs provided by this package. Stability
+ of APIs across releases will still be a goal, but
+ ongoing evolution will likely lead to some incompatible
+ changes.</li>
+ <li><em>Private</em> - This package is not intended for public
+ use by developers, and its APIs are subject to change
+ in later releases at any time.</li>
+ </ul>
+
+ <p>In addition to the intent described above, each package is also
+ annotated with a stability rating, which is an indication of the
+ expected rate of future change, described by one of the following
+ terms:</p>
+
+ <ul>
+ <li><em>Private</em> - This package is not intended for public
+ use by developers, and its APIs are subject to change
+ in later releases at any time.</li>
+ <li><em>Developing</em> - This package is under active development,
+ and changes (including backwards incompatible changes) are likely
+ in future versions.</li>
+ <li><em>Evolving</em> - This package is continuing to be developed,
+ but changes will generally add new features only, while maintaing
+ backwards compatibility.</li>
+ <li><em>Stable</em> - This package may continue to be developed,
+ but offers the highest possible assurance of backwards
compatibility
+ in both public API and in functionality.</li>
+ <li><em>Deprecated</em> - This package contains API that was available
+ in previous versions, and is maintained (for a short while) for
+ backwards compatibility purposes. However, dependencies on these
+ APIs should be migrated appropriately, as at some point in time
+ the package will be subject to removal.</li>
+ </ul>
+
+ </subsection>
+
+ <a name="stability-core"/>
+ <subsection name="Packages Delivered in shale-core.jar">
+
+ <table border="1">
+ <thead>
+ <tr>
+ <th width="30%">Package Name</th>
+ <th width="10%">Target</th>
+ <th width="10%">Stability</th>
+ <th width="50%">Comments</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/application/package-summary.html">
+ org.apache.shale.application</a></td>
+ <td>Framework</td>
+ <td>Developing</td>
+ <td>---</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/component/package-summary.html">
+ org.apache.shale.component</a></td>
+ <td>Application</td>
+ <td>Evolving</td>
+ <td>---</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/dialog/package-summary.html">
+ org.apache.shale.dialog</a></td>
+ <td>Application</td>
+ <td>Developing</td>
+ <td>Expect further development to support multiple active
+ dialogs in the same page.</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/dialog/config/package-summary.html">
+ org.apache.shale.dialog.config</a></td>
+ <td>Framework</td>
+ <td>Developing</td>
+ <td>---</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/dialog/faces/package-summary.html">
+ org.apache.shale.dialog.faces</a></td>
+ <td>Framework</td>
+ <td>Developing</td>
+ <td>---</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/dialog/impl/package-summary.html">
+ org.apache.shale.dialog.impl</a></td>
+ <td>Framework</td>
+ <td>Developing</td>
+ <td>---</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/faces/package-summary.html">
+ org.apache.shale.faces</a></td>
+ <td>Framework</td>
+ <td>Developing</td>
+ <td>---</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/remote/package-summary.html">
+ org.apache.shale.remote</a></td>
+ <td>Application</td>
+ <td>Developing</td>
+ <td>Consider the current APIs to be experimental.</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/renderer/package-summary.html">
+ org.apache.shale.renderer</a></td>
+ <td>Framework</td>
+ <td>Evolving</td>
+ <td>Functionality should be accessed indirectly via
+ components in <code>org.apache.shale.component</code>.</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/taglib/package-summary.html">
+ org.apache.shale.taglib</a></td>
+ <td>Application</td>
+ <td>Evolving</td>
+ <td>---</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/util/package-summary.html">
+ org.apache.shale.util</a></td>
+ <td>Application</td>
+ <td>Developing</td>
+ <td>---</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/validator/package-summary.html">
+ org.apache.shale.validator</a></td>
+ <td>Framework</td>
+ <td>Developing</td>
+ <td>---</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/view/package-summary.html">
+ org.apache.shale.view</a></td>
+ <td>Application</td>
+ <td>Evolving</td>
+ <td>---</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/view/impl/package-summary.html">
+ org.apache.shale.view.impl</a></td>
+ <td>Framework</td>
+ <td>Developing</td>
+ <td>---</td>
+ </tr>
+ </tbody>
+ </table>
+
+ </subsection>
+
+ <a name="stability-spring"/>
+ <subsection name="Packages Delivered in shale-spring.jar">
+
+ <table border="1">
+ <thead>
+ <tr>
+ <th width="30%">Package Name</th>
+ <th width="10%">Target</th>
+ <th width="10%">Stability</th>
+ <th width="50%">Comments</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/spring/package-summary.html">
+ org.apache.shale.spring</a></td>
+ <td>Framework</td>
+ <td>Developing</td>
+ <td>Functionality should be accessed indirectly via
+ evaluating value binding and method binding expressions.</td>
+ </tr>
+ </tbody>
+ </table>
+
+ </subsection>
+
+ <a name="stability-test"/>
+ <subsection name="Packages Delivered in shale-test.jar">
+
+ <table border="1">
+ <thead>
+ <tr>
+ <th width="30%">Package Name</th>
+ <th width="10%">Target</th>
+ <th width="10%">Stability</th>
+ <th width="50%">Comments</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><a
href="shale-test/apidocs/org/apache/shale/test/base/package-summary.html">
+ org.apache.shale.test.base</a></td>
+ <td>Application</td>
+ <td>Evolving</td>
+ <td>Use these classes as base classes for your own
+ JUnit test cases</td>
+ </tr>
+ <tr>
+ <td><a
href="shale-test/apidocs/org/apache/shale/test/mock/package-summary.html">
+ org.apache.shale.test.mock</a></td>
+ <td>Application</td>
+ <td>Evolving</td>
+ <td>Use these classes in your JUnit test cases
+ to simulate container behavior</td>
+ </tr>
+ </tbody>
+ </table>
+
+ </subsection>
+
+ <a name="stability-tiles"/>
+ <subsection name="Packages Delivered in shale-tiles.jar">
+
+ <table border="1">
+ <thead>
+ <tr>
+ <th width="30%">Package Name</th>
+ <th width="10%">Target</th>
+ <th width="10%">Stability</th>
+ <th width="50%">Comments</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><a
href="shale-core/apidocs/org/apache/shale/tiles/package-summary.html">
+ org.apache.shale.tiles</a></td>
+ <td>Framework</td>
+ <td>Developing</td>
+ <td>---</td>
+ </tr>
+ </tbody>
+ </table>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
Propchange: struts/shale/trunk/xdocs/api-stability.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: struts/shale/trunk/xdocs/api-stability.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Modified: struts/shale/trunk/xdocs/navigation.xml
URL:
http://svn.apache.org/viewcvs/struts/shale/trunk/xdocs/navigation.xml?rev=348249&r1=348248&r2=348249&view=diff
==============================================================================
--- struts/shale/trunk/xdocs/navigation.xml (original)
+++ struts/shale/trunk/xdocs/navigation.xml Tue Nov 22 12:57:00 2005
@@ -13,6 +13,7 @@
<item name="Issue Tracking"
href="index.html#Shale_Issue_Tracking"/>
<item name="Using Shale" href="using.html"/>
<item name="Building Shale" href="building.html"/>
+ <item name="API Stability" href="api-stability.html"/>
</menu>
<menu name="Features">
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
