release-policy.html from net-snmp at Krugle
Show release-policy.html syntax highlighted
<!--#set var="section" value="development" -->
<!--#include virtual="/page-top.html" -->
<!-- CONTENT START -->
<h1>Net-SNMP Release Policy</h1>
<h2>Important Note</h2>
<p>While this policy formally becomes fully active January 1st, 2006,
much of it has already been in operation prior to this time. This
document is merely a formal codification of what has been general
policy for a while now.
Issues with this policy statement should be discussed on the
net-snmp-coders mailing list.</p>
<h2>Net-SNMP Release Ethos</h2>
<p>The Net-SNMP software is being used on a variety of system,
by people with a wide range of experience and expertise, both
"as supplied" and as the basis of assorted network management
extensions. It is also distributed widely by an increasing
number of O/S vendors as part of their distributions.</p>
<p>For all of these users, it is vital that software issued by
the project is reliable and stable, with as smooth a progression
as possible from one release to the next.</p>
<p>To achieve this, a number of basic principles should underly
development of the Net-SNMP software:</p>
<ol>
<li> All releases should be backwards-compatible
with previous versions whenever possible - both in terms of
application behaviour and library APIs (this is further
described below).
</li>
<li> Bug fixes should be applied to <i>all</i> relevant and
active patch branches - not simply the most recent line. The
project actively maintains several branches, and may need to
release earlier versions of the code. Critical (E.G. security
related) fixes need to be applied to closed branches as well,
as it may be necessary to even release code from a closed
branch at some point. It is much easier to maintain
consistency across the CVS tree by applying necessary patches
to each tree at the same time.</li>
<li> All code released should have been properly tested on as
wide a range of systems as possible. A stable code base is
necessary to achieve this, implying that code changes should
be clearly monitored and controlled during the run up to a
new release.</li>
</ol>
<p> This document describes the policy for Net-SNMP development,
designed to support these aims. This policy is intended to
provide guidelines to support the aims listed above, not a
straight-jacket to restrict the development of the project. They
are constructed in such a way as to make the rules always boil
down to human decisions when the more simple rules seem
inappropriate.</p>
<p>The primary final rule in this document always falls to +N
voting. Don't waste time arguing whether something meets the
criteria of a show-stopper bug, a new feature, a simple bug,
etc. - just get the needed +N votes to accept an individual patch
instead. This is more efficient, and focuses the argument on the
technical issue (you know, the important ones) rather than
philosophical debates.</p>
<hr>
<h2>Definitions:</h2>
The following terms are used in this document.
<h3>Developer</h3>
Anyone contributing to the project by submitting code - either
directly to the CVS repository or via patches sent to the mailing
lists or SourceForge tracker databases. If you understand the
issues involved (and can discuss them sensibly), then it's
reasonable for you to submit an opinion. A developer is
considered an <i>active developer</i> if they have been
participating in the last 3 months of the project.
<h3>Release Manager</h3>
<p>The person responsible for producing a particular release.
Release managers are appointed
<!-- XXX: How ? Anwser: by me, of course. -->
and are listed in the
<a href="http://www.net-snmp.org/dev/schedule.html">schedule document</a>.
</p>
<h3>+N:</h3>
<p>Differences in opinion are resolved by a generic voting
mechanism: +N. +N means that at least N more developers
should agree than disagree with a given proposal ("yes votes"
minus "no votes").
</p>
<ul>
<li> A vote discussion should last at least 24 hours, covering
normal working hours (9-5, Monday to Friday) for all <i>active
developers</i>.</li>
<li>Any active developer can vote in such a discussion, but must
be able to demonstrate understanding of the issue and code.</li>
<li>Everyone gets 1 vote on
a subject, except for the person who is currently actively
maintaining/writing the given section of code in question.
They get 1.001 votes.</li>
</ul>
<p>For example, a +3 requirement to include a patch during the RC
release cycle would mean that <i>active developers</i>
indicating support
for applying the patch would need at least 3 votes more than
those who object (e.g. tallies of 3-0, 4-1, 5-2, ...).</p>
<p>Calling for a vote may force a delay in making a scheduled release,
to allow this vote to take place. The Release Manager may need
to issue the release before the end of the voting period which
is a judgment call left to the discretion of the Release
Manager and the other "Resolving Disputes" precedence
discussed below.</p>
<h3>Supported System:</h3>
<p>An OS for which there is an active developer prepared to
ensure that the package works properly on that system.
(The Net-SNMP project is driven by volunteers, and we can't
force developers to work on a platform they're not interested in.)</p>
<p>Note that as active developers come and go, and as their
attention is attracted to and distracted from certain system types
the Net-SNMP project may gain or lose support for a given system.
However, emphasis should always be placed on trying to ensure that
changes do not break a system that was once working.
Portable code is very important to this project and great care
should be taken to make sure that new code doesn't introduce
system incompatibilities.</p>
<h3>Show stopper:</h3>
<ul>
<li>Paramount: A condition that is agreed upon by at least +3
developers when discussed on the coders list.</li>
<li>A condition that results in a security vulnerability.</li>
<li>A condition such that a default
<i>"configure; make; make install"</i>
fails to complete successfully on a supported system.
</li>
<li>A condition such that
<i>"make test"</i> fails to complete successfully on a
supported system, (excluding problems within the test suite
itself).
</li>
</ul>
<h3>Bug Fix / New Feature:</h3>
<p>In practice we've found it impossible to perfectly draw a line
between bug fixes and new features. Most of the time it should be
fairly clear, but in practice we've found that much of the time
patches can frequently lie in the "gray area". Because of this
we do not attempt to provide specific definitions for these.
The gray areas for cases like these should be discussed on
-coders and is subject to the current +N voting required for the
current release cycle phase in progress.
<hr>
<h2>Release Cycle:</h2>
<p> The Net-SNMP project follows the following steps when
releasing a new version of the software:
</p><pre> Open Development => Pre-Releases => Release-Candidates => Final Release
</pre>
<h3>Open Development</h3>
<p> Anyone with write access to the CVS repository can submit
changes at will, including new features (on the main development
trunk) and bug fixes (on the main trunk and on all CVS
branches).
<p> Any incompatible
changes should be clearly documented, and only introduced at
"major" releases (rather than as part of bug-fix patch
versions) and is subject to a minimum requirement of a +3 vote
on the -coders list.</p>
<p>Any other alteration for which a backwards compatibility mode
exists but is off by default should be discussed beforehand on
-coders and is subject to a +1 vote for going forward.</p>
<p>Other changes do not need prior
agreement (although significant new features should probably be
announced afterwards). If challenged the feature will only
exist in future code if it meets a +.001 vote.</p>
<h3>Pre-Releases</h3>
<p> The Pre-Release phase marks the start of the process for
releasing a new version of the software. During the period
between the first pre-release being made available to the
first release-candidate being made available:
</p>
<ul>
<li>Only bug fixes should be applied - no new features.</li>
<li>Significant issues should be discussed on the -coders
list first, but generally patches can be committed to fix
bugs as needed.</li>
<li>A developer that disagrees with a particular patch
should bring up the issue on the -coders list. A vote
of +1 is needed to keep the patch in place.</li>
<li>No new features are allowed.</li>
</ul>
<p>Pre-Release packages use a numbering scheme of
<i>Version.Number</i>.pre<i>N</i> (e.g. 5.3.pre1).
The Pre-Release phase generally lasts for 3-4 weeks, typically
with one pre-release being issued each week. The exact length
of the Pre-Release phase, and the timing of pre-release
versions is at the discretion of the Release Manager.</p>
<h3>Release-Candidates</h3>
<p> The Release Candidate phase is intended to mark the end of
active delopment for a particular release version. The aim is
that the final released version should be ideally identical to the
last Release-Candidate issued. During the period
between the first release-candidate being made available and the
final release being made available:
</p>
<ul>
<li>Only show-stopper bugs should be fixed.</li>
<li>No other bug fixes should be applied.</li>
<li><b>Definitely</b> no new features!</li>
<li>Any code changes require a +3 vote on the -coders list.
This vote <b>MUST</b> take place prior to committing such
changes to the CVS tree.</li>
<li>Documentation may be updated without a vote. Changes to
standalone documentation can be applied right up to 2 hours
before a release manager has indicated they're going to begin
packaging the next release. Changes to documentation embedded
in code files (e.g. 'doxygen' and other comments) should only be
applied if another Release-Candidate is planned.</li>
</ul>
<p> Release-Candidate packages use a numbering scheme of
<i>Version.Number</i>.rc<i>N</i> (e.g. 5.3.rc1).
This phase lasts until the Release Manager judges that
the software is sufficiently stable to be properly
released (i.e. no show-stopper bugs have been reported).</p>
<p> While testing is expected (and encouraged) throughout
the full development and release cycle, it is particularly
important during the Release-Candidate phase. There is
an expectation that "make test" (at the very least) should
have been run (successfully!) on all supported systems - and
as many others as the combined community can lay their
collective hands on.</p>
<p> The length of a release cycle phase should be at least 2-3 RC
releases in length and is subject to the judgment of the Release
Manager. A +1 vote is needed to force another release-candidate
if the release manager wasn't planning on issuing another one.</p>
<h3>Final Release</h3>
<p>Despite the above policy of rigorous, exhaustive and
largely fictional testing, a new final release is invariably
followed by an avalanche of problem reports - some trivial
and/or very specific to a particular environment, others more
widereaching and serious (possibly verging on catastrophic).
During the period immediately following a release, the project
must be ready to respond to such problems, and possibly issue
an updated version of the software with minimal delay.
To this end:</p>
<ul>
<li> Following a final release, the CVS tree continues in a
Release-Candidate style freeze for 1 week (7 days) unless the
release manager for that branch indicates a longer one is
needed.</li>
<li> If a show-stopper bug is reported in the final release, a
vote of +3 on -coders (and a suitable fix) can call for an
immediate "minor minor" release (the Z in W.X.Y.Z). If a
critical bug warranting one of these releases is found after a
code freeze has ended this will typically require the creation
of a special branch in the CVS tree where the minor minor
release can be distributed from containing only the critical
patch.</li>
<li> Following a major release (X.Y), a patch branch should
be created in the CVS repository, labelled (tagged)
V<i>X</i>-<i>Y</i>-patches. The post-release code freeze
applies to this branch - the main trunk becomes open for
active development immediately.</li>
</ul>
<hr>
<h2>Resolving Disputes</h2>
<p>The voting system described above is intended as the primary
mechanism for resolving differences of opinion. If this proves
insufficient, disputes will be resolved based on the following
order of precedence (the later in this list trumping the earlier):</p>
<ul>
<li>+N vote as described above.
If not explicitly specified, voting should be +3</li>
<li>The release manager.</li>
<li>Active project developers with CVS write access. Ordered
by seniority, as listed in the ChangeLog.txt history.
</li>
<li>The Net-SNMP Project Founder.</li>
</ul>
<h2>Acknowledgments</h2>
<p>Much of this document was originally proposed (and edited and
re-edited and made better and ...) by Dave Shield. If it wasn't
for him I would have just written "be good" and you'd have a lot
less to read.</p>
<h2>Warnings</h2>
<p>We're all friends generally, but just to be clear: attempts to
misuse this policy will be severely frowned upon. Don't test this.</p>
<!-- CONTENT END -->
<!--#include virtual="/page-bottom.html" -->
See more files for this project here