| <?xml version="1.0"?> |
| <document url="./releases.xml"> |
| |
| <!-- |
| // ======================================================================== 78 |
| --> |
| |
| <properties> |
| <title>Release Guidelines - The Apache Struts Web Application Framework</title> |
| </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://wiki.apache.org/incubator/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 <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> |
