husted 2004/01/13 05:19:48
Modified: doc releases.xml
Log:
Tidy XML markup (-i -m -wrap 0 -xml). No content changes
Revision Changes Path
1.6 +104 -270 jakarta-struts/doc/releases.xml
Index: releases.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/releases.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- releases.xml 13 Jan 2004 13:18:06 -0000 1.5
+++ releases.xml 13 Jan 2004 13:19:48 -0000 1.6
@@ -1,283 +1,117 @@
<?xml version="1.0"?>
<document url="./releases.xml">
-
-<!--
-// ======================================================================== 78
--->
-
-<properties>
+ <!--
+ // ======================================================================== 78
+ -->
+ <properties>
<title>Release Guidelines - The Apache Struts Web Application Framework</title>
<author>Ted Husted</author>
-</properties>
-
-<body>
+ </properties>
+ <body>
<section href="status" name="Release Guidelines">
-
- <p>
- This document describes the Struts <a href="#Releases">release process</a> and
our <a href="#Coding">coding
- conventions</a>. Both stable and development releases are <a
href="acquiring.html">available for download</a>.
- </p>
-
+ <p>This document describes the Struts
+ <a href="#Releases">release process</a>and our
+ <a href="#Coding">coding conventions</a>. Both stable and development
releases are
+ <a href="acquiring.html">available for download</a>.</p>
</section>
-
<section href="Releases" name="Release Guidelines">
-
- <p>
- A <a href="http://jakarta.apache.org/commons/versioning.html";>point
release</a>
- should be made before and after any product change that is not a
"fully-compatible change"
- (see link). This includes moving a dependency from an internal package
to an external product,
- including products distributed through the Jakarta Commons.
- We should place any fully-compatible changes in the hands of the
community
- before starting on a change that is only "interface" or
"external-interface" compatible.
- </p>
- <p>
- A fully-compatible point release does not always need a "preview" beta
or milestone release.
- If appropriate, a Release Candidate can be cut, uploaded to the Release
Manager's home directory
- on cvs.apache.org (~/public_html), and voted to be released to the
general public from there.
- </p>
-
- <p>
- Any release should follow the same general process used by the Jakarta
Commons
- and the Apache HTTP Server project.
- </p>
-
- <ul>
- <li>
- <a href="http://jakarta.apache.org/commons/releases/";>Releasing
Common Components</a>
- </li>
- <li>
- <a
href="http://nagoya.apache.org/wiki/apachewiki.cgi?SigningReleases";>Signing a release
version</a>
- <ul>
- <li>
- <small>The MD5 tool is installed on daedalus, and you can
create the digests for Struts releases
- there.</small>
- </li>
- </ul>
- </li>
- <li>
- <a href="http://httpd.apache.org/dev/release.html";>Apache HTTPD
Server Release Guidelines</a>
- </li>
- </ul>
-
- <p>
- Additional remarks:
- </p>
-
- <ul>
- <li>
- The release process can seem daunting when you review it for the
first time.
- But, essentially, it breaks down into three phases of just a few
steps each:
- <ul>
- <li>Building - Bugzilla, dependencies, release notes, JAR
manifest, licenses, copyrights, and build
- (using the release target).</li>
- <li>Testing - JUnit, Cactus, web apps (for all "supported"
containers). </li>
- <li>Distributing - Checksum, sign, mirror, release, update
Struts site, update Jakarta site,
- announce.</li>
- </ul>
- </li>
- <li>
- Our dependencies on external JARs (including Commons JARs) should
- be in line with our own release status.
- Our nightly build can be dependant on another nightly build.
- Our beta can be dependant on another beta,
- but should avoid a dependance on a nightly build.
- Our release candidate can have a dependance on another RC,
- but should not have a dependance on a beta (and certainly
<strong>not</strong> a nightly build).
- Our final release can only have dependencies on other final
releases.
- </li>
- <li>
- Use your own discretion as to detail needed by the Release Notes.
- A high-level description of the changes is more important than
providing uninterpreted detail.
- At a minimum, new features and deprecations should be summarized,
- since these are commonly asked questions.
- Ideally, the release notes should be maintained continuously for
the nightly build
- so that we do not need to quickly assembled them on the eve of a
Release.
- </li>
- <li>
- Test building the distribution under prior version of J2SE, if
possible,
- to ensure that we are still backwardly-compatible.
- But, our Release distribution should be built using the
<strong>latest release of J2SE</strong>,
- to take advantage of all available compiler enhancements.
- </li>
- <li>
- Before building the release, run the JUnit and Cactus tests using
the same
- configuration used that will be used to build the Release
distribution.
- </li>
- <li>
- There is a "release" target in the buildfile that will zip and tar
the releases.
- Before uploading the release, extract the sample web applications
and deploy the WARs under
- each of the "supported" containers.
- Play test each application under each container to be sure they
operate nominally.
- </li>
- <li>
- Be sure to copy the [EMAIL PROTECTED] list on any release
announcement.
- </li>
- <li>
- Remember to update the <a href="status.html">Status section of the
Roadmap page</a>
- once a release is available.
- </li>
- <li>
- By the way, the nightly builds are being created on a machine of
Craig McClanahan's.
- If there are problems with a nightly build that seem infrastructure
related,
- Craig is the one to contact.
- </li>
- </ul>
-
- </section>
-
-
-<section href="Coding" name="Coding Conventions and Guidelines">
-
- <p>
- Source code and documentation contributed to the Struts repositories
- should observe the:
- </p>
-
- <ul>
-
- <li>
- <a href="http://jakarta.apache.org/site/source.html";>Jakarta project
- guidelines</a>,
- </li>
-
- <li>
- <a href="http://www.ambysoft.com/elementsJavaStyle.html";>Elements of
- Java Style</a>, and
- </li>
-
- <li>
- <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/";>How to
- write Doc Comments</a>
- </li>
-
- </ul>
-
- <p>
- as core references regarding the formatting of code and documentation.
- </p>
-
- <p>
- <strong>Clarifications</strong>
- </p>
-
- <ul>
-
+ <p>A
+ <a href="http://jakarta.apache.org/commons/versioning.html";>point
release</a>should be made before and after any product change that is not a
"fully-compatible change" (see link). This includes moving a dependency from an
internal package to an external product, including products distributed through the
Jakarta Commons. We should place any fully-compatible changes in the hands of the
community before starting on a change that is only "interface" or "external-interface"
compatible.</p>
+ <p>A fully-compatible point release does not always need a "preview" beta or
milestone release. If appropriate, a Release Candidate can be cut, uploaded to the
Release Manager's home directory on cvs.apache.org (~/public_html), and voted to be
released to the general public from there.</p>
+ <p>Any release should follow the same general process used by the Jakarta
Commons and the Apache HTTP Server project.</p>
+ <ul>
<li>
- First, "Observe the style of the original".
- Resist the temptation to make stylistic changes for their own sake.
- But, if you must reformat code, commit style changes separately from
- code changes.
- Either change the style, commit, and then change the code, or vice-
- versa.
+ <a href="http://jakarta.apache.org/commons/releases/";>Releasing Common
Components</a>
</li>
-
<li>
- Set editors to replace tabs with spaces and do not trim trailing
- spaces. Tabs confound the CVS email alerts. Trimming trailing spaces
- creates unnecessary changes.
- </li>
-
- <li>
- Specify imported classes (do not use <code>.*</code>).
- </li>
-
- <li>
- Write all if/else statements as full blocks with each clause within braces,
- unless the entire statement fits on the same line.
- </li>
-
- <li>
- Use <code>:FIXME:</code> and <code>:TODO:</code> tokens to mark follow up
- notes in code.
- You may also include your Apache username and the date.
- </li>
-
- <li>
- Omit <code>@author</code> tags.
- </li>
-
- <li>
- Use <code>@since</code> to document changes between Struts versions,
- as in <code>@since Struts 1.1</code>.
- </li>
-
- <li>
- Wrap lines of code and JavaDoc at column 78.
- You can include a "comment rule" in the source to help with this.<br />
- <small>
- // ------------------------------------------------------------------------
78
- </small>
- </li>
-
- <li>
- Please do your best to provide high-quality Javadocs for all source code
- elements.
- Package overviews (aka "Developer Guides") are also encouraged.
- </li>
-
- <li>
- When working on a bugfix, please first write a
- <a href="http://www.junit.org";>JUnit</a> test that proves the bug exists,
- and then use the test to prove the bug is fixed. =:0)
- </li>
-
- <li>
- When working on an enhancement, please feel free to use test-driven design
- and write the test first <head-slap/>.
- For more about TDD, see the
- <a href="http://sourceforge.net/projects/mockobjects";>MockObjects project
- </a>.
- </li>
-
- <li>
- As files are updated from year to year, the copyright on each file should
- be extended to include the current year.
- <b>You do not need to change the copyright year unless you change the
file.</b>
- Every source file should include the ASF copyright notice and current
- Apache License and copyright.
- </li>
-
- <li>
- Provide high-level API compatibility for any changes made within the same
- major release series (#.x).
- Changes which adversely affect compatibility should be slotted for the
- next major release series (++#.x).
- </li>
-
- <li>
- Our favorite books about programming are
- <a
href="http://www.amazon.com/exec/obidos/ISBN=0201633612/hitchhikeguidetoA/";>
- Design Patterns</a> and
- <a
href="http://www.amazon.com/exec/obidos/ISBN=0201485672/hitchhikeguidetoA/";>
- Refactoring</a>.
- </li>
-
- <li>
- Our favorite book about open source development is the
- <a
href="http://www.amazon.com/exec/obidos/ISBN=1565927249/hitchhikeguidetoA/";>
- The Cathedral and the Bazaar</a>.
+ <a
href="http://nagoya.apache.org/wiki/apachewiki.cgi?SigningReleases";>Signing a release
version</a>
+ <ul>
+ <li>
+ <small>The MD5 tool is installed on daedalus, and you can create the
digests for Struts releases there.</small>
+ </li>
+ </ul>
</li>
-
<li>
- Our favorite science fiction author is
- <a href="http://www.nitrosyncretic.com/rah/";>Robert Heinlein</a>.
- <a href="http://www.tuxedo.org/~esr/jargon/html/entry/TANSTAAFL.html";>
- TANSTAAFL</a>.<br />
- (Except on Friday, when we favor
- <a href="http://carbon.cudenver.edu/~mstilman/zaphod/";>Douglas
- Adams</a>.
- <a href="http://news.bbc.co.uk/1/hi/uk/1326657.stm";>
- SLATFATF</a>.)
+ <a href="http://httpd.apache.org/dev/release.html";>Apache HTTPD Server
Release Guidelines</a>
</li>
-
- </ul>
-
-</section>
-
-<section>
- <p class="right">
- Next: <a href="news/index.html">News and Status</a>
- </p>
-</section>
-
-</body></document>
+ </ul>
+ <p>Additional remarks:</p>
+ <ul>
+ <li>The release process can seem daunting when you review it for the first
time. But, essentially, it breaks down into three phases of just a few steps each:
+ <ul>
+ <li>Building - Bugzilla, dependencies, release notes, JAR manifest,
licenses, copyrights, and build (using the release target).</li>
+ <li>Testing - JUnit, Cactus, web apps (for all "supported"
containers).</li>
+ <li>Distributing - Checksum, sign, mirror, release, update Struts site,
update Jakarta site, announce.</li>
+ </ul></li>
+ <li>Our dependencies on external JARs (including Commons JARs) should be in
line with our own release status. Our nightly build can be dependant on another
nightly build. Our beta can be dependant on another beta, but should avoid a
dependance on a nightly build. Our release candidate can have a dependance on another
RC, but should not have a dependance on a beta (and certainly
+ <strong>not</strong>a nightly build). Our final release can only have
dependencies on other final releases.</li>
+ <li>Use your own discretion as to detail needed by the Release Notes. A
high-level description of the changes is more important than providing uninterpreted
detail. At a minimum, new features and deprecations should be summarized, since these
are commonly asked questions. Ideally, the release notes should be maintained
continuously for the nightly build so that we do not need to quickly assembled them on
the eve of a Release.</li>
+ <li>Test building the distribution under prior version of J2SE, if
possible, to ensure that we are still backwardly-compatible. But, our Release
distribution should be built using the
+ <strong>latest release of J2SE</strong>, to take advantage of all available
compiler enhancements.</li>
+ <li>Before building the release, run the JUnit and Cactus tests using the
same configuration used that will be used to build the Release distribution.</li>
+ <li>There is a "release" target in the buildfile that will zip and tar the
releases. Before uploading the release, extract the sample web applications and deploy
the WARs under each of the "supported" containers. Play test each application under
each container to be sure they operate nominally.</li>
+ <li>Be sure to copy the [EMAIL PROTECTED] list on any release
announcement.</li>
+ <li>Remember to update the
+ <a href="status.html">Status section of the Roadmap page</a>once a release
is available.</li>
+ <li>By the way, the nightly builds are being created on a machine of Craig
McClanahan's. If there are problems with a nightly build that seem infrastructure
related, Craig is the one to contact.</li>
+ </ul>
+ </section>
+ <section href="Coding" name="Coding Conventions and Guidelines">
+ <p>Source code and documentation contributed to the Struts repositories
should observe the:</p>
+ <ul>
+ <li>
+ <a href="http://jakarta.apache.org/site/source.html";>Jakarta project
guidelines</a>,</li>
+ <li>
+ <a href="http://www.ambysoft.com/elementsJavaStyle.html";>Elements of Java
Style</a>, and</li>
+ <li>
+ <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/";>How to
write Doc Comments</a>
+ </li>
+ </ul>
+ <p>as core references regarding the formatting of code and documentation.</p>
+ <p>
+ <strong>Clarifications</strong>
+ </p>
+ <ul>
+ <li>First, "Observe the style of the original". Resist the temptation to
make stylistic changes for their own sake. But, if you must reformat code, commit
style changes separately from code changes. Either change the style, commit, and then
change the code, or vice- versa.</li>
+ <li>Set editors to replace tabs with spaces and do not trim trailing
spaces. Tabs confound the CVS email alerts. Trimming trailing spaces creates
unnecessary changes.</li>
+ <li>Specify imported classes (do not use
+ <code>.*</code>).</li>
+ <li>Write all if/else statements as full blocks with each clause within
braces, unless the entire statement fits on the same line.</li>
+ <li>Use
+ <code>:FIXME:</code>and
+ <code>:TODO:</code>tokens to mark follow up notes in code. You may also
include your Apache username and the date.</li>
+ <li>Omit
+ <code>@author</code>tags.</li>
+ <li>Use
+ <code>@since</code>to document changes between Struts versions, as in
+ <code>@since Struts 1.1</code>.</li>
+ <li>Wrap lines of code and JavaDoc at column 78. You can include a "comment
rule" in the source to help with this.
+ <br />
+ <small>//
------------------------------------------------------------------------
78</small></li>
+ <li>Please do your best to provide high-quality Javadocs for all source
code elements. Package overviews (aka "Developer Guides") are also encouraged.</li>
+ <li>When working on a bugfix, please first write a
+ <a href="http://www.junit.org";>JUnit</a>test that proves the bug exists,
and then use the test to prove the bug is fixed. =:0)</li>
+ <li>When working on an enhancement, please feel free to use test-driven
design and write the test first <head-slap/>. For more about TDD, see the
+ <a href="http://sourceforge.net/projects/mockobjects";>MockObjects
project</a>.</li>
+ <li>As files are updated from year to year, the copyright on each file
should be extended to include the current year.
+ <b>You do not need to change the copyright year unless you change the
file.</b>Every source file should include the ASF copyright notice and current Apache
License and copyright.</li>
+ <li>Provide high-level API compatibility for any changes made within the
same major release series (#.x). Changes which adversely affect compatibility should
be slotted for the next major release series (++#.x).</li>
+ <li>Our favorite books about programming are
+ <a
href="http://www.amazon.com/exec/obidos/ISBN=0201633612/hitchhikeguidetoA/";>Design
Patterns</a>and
+ <a
href="http://www.amazon.com/exec/obidos/ISBN=0201485672/hitchhikeguidetoA/";>Refactoring</a>.</li>
+ <li>Our favorite book about open source development is the
+ <a
href="http://www.amazon.com/exec/obidos/ISBN=1565927249/hitchhikeguidetoA/";>The
Cathedral and the Bazaar</a>.</li>
+ <li>Our favorite science fiction author is
+ <a href="http://www.nitrosyncretic.com/rah/";>Robert Heinlein</a>.
+ <a
href="http://www.tuxedo.org/~esr/jargon/html/entry/TANSTAAFL.html";>TANSTAAFL</a>.
+ <br />(Except on Friday, when we favor
+ <a href="http://carbon.cudenver.edu/~mstilman/zaphod/";>Douglas Adams</a>.
+ <a href="http://news.bbc.co.uk/1/hi/uk/1326657.stm";>SLATFATF</a>.)</li>
+ </ul>
+ </section>
+ <section>
+ <p class="right">Next:
+ <a href="news/index.html">News and Status</a></p>
+ </section>
+ </body>
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
