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