husted 2003/08/29 09:49:28
Added: doc releases.xml
Log:
+ Create releases page from lower portion of status page.
Revision Changes Path
1.1 jakarta-struts/doc/releases.xml
Index: releases.xml
===================================================================
<?xml version="1.0"?>
<document url="./releases.xml">
<!--
// ======================================================================== 78
-->
<properties>
<title>Release Guidelines - The Apache Struts Web Application Framework</title>
<author>Ted Husted</author>
</properties>
<body>
<chapter href="status" name="Release Guidelines">
<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>.
</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>
Remember to update the <a href="news/index.html">Status section of
the News page</a> when cutting any milestone.
For a final release, also update the /doc/project.xml with the
current release number.
</li>
<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 <b>not</b>
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 <b>latest
release of J2SE</b>,
to take advantage of all available compiler enhancements.
</li>
<li>
Before building the final 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>
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.
</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.
<code>:FIXME: we need to do this sometime (husted 2002-11-14)</code>
</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.
You do not need to change the copyright year unless you change the file.
Every source file should include the 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";>
<font size="-1">TANSTAAFL</font></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";>
<font size="-1">SLATFATF</font></a>.)
</li>
</ul>
</section>
<section>
<p align="right">
Next: <a href="news/index.html">News and Status</a>
</p>
</section>
</chapter></body></document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
