<?xml version="1.0"?>
<!--
Copyright 1999-2006 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.
-->
<!--
// ======================================================================== 78
-->
<document>

    <properties>
        <title>Release Guidelines</title>
    </properties>
    <body>

        <a name="status"/>
        <section name="Release Guidelines">
            <p>This document describes the Apache Struts
                <a href="#Releases">release process</a>
                and our
                <a href="#Coding">coding conventions</a>
                ,
                which are applicable to all subprojects.
                Both stable and development releases are
                <a href="downloads.html">available for download</a>
                .
            </p>

            <a name="Releasing"/>
            <subsection name="Release Process">
                <p>A
                    <a href="http://jakarta.apache.org/commons/releases/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>
                    Any release should follow the same general process used by
                    the
                    <a href="http://jakarta.apache.org/site/decisions.html">
                        Jakarta Tomcat</a>
                    team
                    and must observe the
                    <a href="http://apache.org/dev/mirrors.html">Apache
                        Mirroring guidelines</a>
                    .
                    See also
                    <a href="http://wiki.apache.org/incubator/SigningReleases">
                        Signing Releases</a>
                    .
                </p>
                <p>Additional remarks:</p>
                <ul>
                    <li>Every committer is encouraged to participate in the
                        release process, either as the release manager or a
                        helper. Committers may also share the release manager
                        role.</li>
                    <li>The release process can seem daunting when you review
                        it for the first time. But, essentially, it breaks
                        down into four phases of just a few steps each:
                        <ul>
                            <li>
                                <strong>Rolling</strong>
                                - Bugzilla, dependencies, release notes, JAR
                                manifest, licenses, copyrights, and build
                                (using the release target).
                            </li>
                            <li>
                                <strong>Testing</strong>
                                - JUnit, Cactus, web apps (for all "supported"
                                containers).
                            </li>
                            <li>
                                <strong>Voting</strong>
                                - Upload test build to internal directory,
                                post majority vote on DEV list as to release
                                grade: Alpha, Beta, General Availability.
                            </li>
                            <li>
                                <strong>Distributing</strong>
                                - Checksum, sign, mirror, update download
                                page, announce.
                            </li>
                        </ul>
                    </li>
                    <li>Committers are
                        <b>required</b>
                        to post a release plan before tagging the repository
                        and should wait the traditional 72 hours before
                        proceeding.
                    </li>
                    <li>A checklist format can be used for the
                        <a href="http://wiki.apache.org/struts/StrutsReleasePlans">
                            release plan</a>
                        , to help step through the process. The plan may be
                        maintained in the repository or on the
                        <a href="http://wiki.apache.org/struts/">Struts
                            wiki</a>
                        .
                    </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 (or
                        "release candidate"), but should avoid a dependance on
                        a nightly build.
                        Our General Availability release may only have
                        dependencies on other GA, final, or stable
                        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 they do
                        not need to be assembled at the last minute.</li>
                    <li>Try building the distribution under prior version of
                        J2SE, if possible, to ensure that we are still
                        backwardly-compatible. But, our distributions should
                        be built using the
                        <strong>latest production release of J2SE</strong>
                        , to take advantage of all available compiler
                        enhancements.
                    </li>
                    <li>If you have multiple J2SE versions configured, run the
                        JUnit and Cactus tests using the same configuration
                        that will be used to build the distribution.</li>
                    <li>There is a "release" target in the buildfile that will
                        zip and tar the distribution. Before uploading the
                        distribution, extract the sample web applications and
                        deploy the WARs under each of the "supported"
                        containers (if you can). Play test each application
                        under each container to be sure they operate
                        nominally.</li>
                    <li>The test build can be posted to the internal
                        distribution directory (svn.apache.org/struts/) and
                        announced to the Struts DEV and PMC lists (only!). Do
                        not announce a test build on any other Apache lists or
                        link to it from an Apache website.</li>
                    <li>If the test build is voted to Alpha, Beta, or GA
                        status, the release can announced to the User list and
                        linked from the website.</li>
                    <li>Any formal release may be submitted for mirroring. All
                        GA releases
                        <b>must</b>
                        be mirrored.
                    </li>
                    <li>After announcing a release, remember to update the
                        Acquiring and Announcements pages. If the release is
                        to be mirrored, wait at least 24 hours after submittal
                        before making public announcements (as stated in the
                        <a href="http://apache.org/dev/mirrors.html">Apache
                            Mirroring guidelines</a>
                        ).
                    </li>
                    <li>If a serious flaw if found in a test build or release,
                        it may be withdrawn by a majority vote of the PMC and
                        removed from ASF distribution channels.</li>
                </ul>
            </subsection>
            <a name="Coding"/>
            <subsection name="Coding Conventions and Guidelines">
                <p>Source code and documentation contributed to the Struts
                    repositories should observe the:</p>
                <ul>
                    <li>
                        The
                        "
                        <a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">
                            Code Conventions for the Java Programming
                            Language</a>
                        ",
                        as published by Sun.
                    </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 version
                        control 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 &lt;head-slap/&gt;.
                        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.x).
                        Changes which adversely affect compatibility should be
                        slotted for the next major release series
                        (++#.x.x).</li>
                    <li>Our favorite books about programming are
                        <a href="http://www.amazon.com/exec/obidos/ISBN=0201633612/apachesoftwar-20/">
                            Design Patterns</a>
                        ,
                        <a href="http://www.amazon.com/exec/obidos/ISBN=0201485672/apachesoftwar-20/">
                            Refactoring</a>
                        , and
                        <a href="http://www.amazon.com/exec/obidos/ISBN=0735619670/apachesoftwar-20/">
                            Code Complete</a>
                        (2d).
                    </li>
                    <li>Our favorite book about open source development is the
                        <a href="http://www.amazon.com/exec/obidos/ISBN=1565927249/apachesoftwar-20/">
                            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://jargon.net/jargonfile/t/TANSTAAFL.html">
                            TANSTAAFL</a>
                        .
                        <br/>
                        (Except on Friday, when we favor
                        <a href="http://news.bbc.co.uk/1/hi/uk/1326657.stm">
                            Douglas Adams</a>
                        ).
                    </li>
                </ul>
            </subsection>
        </section>
        <section>
            <p class="right">Next:
                <a href="javadoc.html">Javadoc Index</a>
            </p>
        </section>
    </body>
</document>