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 =&gt; Pre-Releases =&gt; Release-Candidates =&gt; 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