<?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>
    <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>

    </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 svn.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 pmc@jakarta.apache.org 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.
        </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 &lt;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">
        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>
