blob: fa1f0b71834664590199218033e46781519e23b6 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<meta name="Date-Revision-yyyymmdd" content="20140918"/>
<meta http-equiv="Content-Language" content="en"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Release Guidelines</title>
<link href="//,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css">
<link href="//" rel="stylesheet">
<link href="/css/main.css" rel="stylesheet">
<link href="/css/custom.css" rel="stylesheet">
<link href="/highlighter/github-theme.css" rel="stylesheet">
<script src="//"></script>
<script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script>
<script type="text/javascript" src="/js/community.js"></script>
<a href="" class="github-ribbon">
<img style="position: absolute; right: 0; border: 0;" src="" alt="Fork me on GitHub">
<div role="navigation" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" data-toggle="collapse" data-target="#struts-menu" class="navbar-toggle">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a>
<div id="struts-menu" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Home<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/index.html">Welcome</a></li>
<li><a href="/download.cgi">Download</a></li>
<li><a href="/releases.html">Releases</a></li>
<li><a href="/announce-2021.html">Announcements</a></li>
<li><a href="">License</a></li>
<li><a href="">Thanks!</a></li>
<li><a href="">Sponsorship</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Support<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/mail.html">User Mailing List</a></li>
<li><a href="">Issue Tracker</a></li>
<li><a href="/security.html">Reporting Security Issues</a></li>
<li class="divider"></li>
<li><a href="">Version Notes</a></li>
<li><a href="">Security Bulletins</a></li>
<li class="divider"></li>
<li><a href="/maven/project-info.html">Maven Project Info</a></li>
<li><a href="/maven/struts2-core/dependencies.html">Struts Core Dependencies</a></li>
<li><a href="/maven/struts2-plugins/modules.html">Plugin Dependencies</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Documentation<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/birdseye.html">Birds Eye</a></li>
<li><a href="/primer.html">Key Technologies</a></li>
<li><a href="/kickstart.html">Kickstart FAQ</a></li>
<li><a href="">Wiki</a></li>
<li class="divider"></li>
<li><a href="/getting-started/">Getting Started</a></li>
<li><a href="/security/">Security Guide</a></li>
<li><a href="/core-developers/">Core Developers Guide</a></li>
<li><a href="/tag-developers/">Tag Developers Guide</a></li>
<li><a href="/maven-archetypes/">Maven Archetypes</a></li>
<li><a href="/plugins/">Plugins</a></li>
<li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li>
<li><a href="/tag-developers/tag-reference.html">Tag reference</a></li>
<li><a href="">FAQs</a></li>
<li><a href="">Plugin registry</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Contributing<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/youatstruts.html">You at Struts</a></li>
<li><a href="/helping.html">How to Help FAQ</a></li>
<li><a href="/dev-mail.html">Development Lists</a></li>
<li><a href="/contributors/">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/submitting-patches.html">Submitting patches</a></li>
<li><a href="/builds.html">Source Code and Builds</a></li>
<li><a href="/coding-standards.html">Coding standards</a></li>
<li><a href="">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/release-guidelines.html">Release Guidelines</a></li>
<li><a href="/bylaws.html">PMC Charter</a></li>
<li><a href="/volunteers.html">Volunteers</a></li>
<li><a href="">Source Repository</a></li>
<li><a href="/updating-website.html">Updating the website</a></li>
<li class="apache"><a href=""><img src="/img/apache.png"></a></li>
<article class="container">
<section class="col-md-12">
<a class="edit-on-gh" href="" title="Edit this page on GitHub">Edit on GitHub</a>
<h1 class="no_toc" id="release-guidelines">Release Guidelines</h1>
<ul id="markdown-toc">
<li><a href="#release-process" id="markdown-toc-release-process">Release Process</a></li>
<li><a href="#coding-conventions-and-guidelines" id="markdown-toc-coding-conventions-and-guidelines">Coding Conventions and Guidelines</a></li>
<li><a href="#clarifications" id="markdown-toc-clarifications">Clarifications</a></li>
<p>This document describes the Apache Struts release process and our <a href="#Coding">coding conventions</a>,
which are applicable to all subprojects. Both stable and development releases are
<a href="releases.html">available for download.</a></p>
<h2 id="release-process">Release Process</h2>
<p>A <a href="">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 Apache 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>Additional remarks:</p>
<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:
<li><strong>Rolling</strong> - Issues, 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>
<li>Committers are <strong>required</strong> 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="">release plan</a>,
to help step through the process. The plan may be maintained in the repository or on the
<a href="">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
<li>The test build can be posted to the internal distribution directory ( 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 <strong>must</strong> be mirrored.</li>
<li>After announcing a release, remember to update the Downloads 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="">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>
<h2 id="coding-conventions-and-guidelines">Coding Conventions and Guidelines</h2>
<p>Source code and documentation contributed to the Struts repositories should observe the:</p>
<li>The <a href="">“Code Conventions for the Java Programming Language”</a>,
as published by Oracle.</li>
<h2 id="clarifications">Clarifications</h2>
<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 <em>.*</em>).</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 class="highlighter-rouge">FIXME:</code> and <code class="highlighter-rouge">TODO:</code> tokens to mark follow up notes in code. You may also
include your Apache username and the date.</li>
<li>Omit <code class="highlighter-rouge">@author</code> tags.</li>
<li><code class="highlighter-rouge">@since</code> to document changes between Struts versions, as in <code class="highlighter-rouge">@since Struts 2.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
<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 test case 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 <code class="highlighter-rouge">&lt;head-slap/&gt;</code></li>
<li>As files are updated from year to year, the copyright on each file should be extended to include the current
year. <em>You do not need to change the copyright year unless you change the file.</em> 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="">Design Patterns</a>,
<a href="">Refactoring</a>,
and <a href="">Code Complete</a></li>
<li>Our favorite book about open source development is the
<a href="">The Cathedral and the Bazaar</a></li>
<li>Our favorite science fiction author is
<a href="">Robert Heinlein</a>,
<a href="">TANSTAAFL</a>,
(Except on Friday, when we favor <a href="">Douglas Adams</a>).</li>
<p>Next: <a href="bylaws.html">PMC Charter</a></p>
<footer class="container">
<div class="col-md-12">
Copyright &copy; 2000-2018 <a href="">The Apache Software Foundation </a>.
All Rights Reserved.
<div class="col-md-12">
Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are
trademarks of The Apache Software Foundation.
<div class="col-md-12">Logo and website design donated by <a href="">SoftwareMill</a>.</div>
<script>!function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (!d.getElementById(id)) {
js = d.createElement(s); = id;
js.src = "//";
fjs.parentNode.insertBefore(js, fjs);
}(document, "script", "twitter-wjs");</script>
<script src="" async="async" defer="defer"></script>
<div id="fb-root"></div>
<script>(function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s); = id;
js.src = "//";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>