= Ruby 1.8 Branch Policy

== About the 1.8 branch:

The 1.8 branch, or in general, a "stable" branch is developed and
maintained for most casual use by average ruby programmers.
Besides fixes for security problems and run-time bugs, there can
be performance improvements, feature enhancements and library
updates made on the branch. Those kinds of aggressive changes may
occur, however, only on condition that backward compatibilities
and run-time stabilities are retained to a high degree.

To perform continuous quality assurance and encourage wider use of
the code base, point releases are issued from the stable branch.
Each of them is called a stable release and maintained on its own
release branch where only bug fixes after the release would likely
take place.

Note that it is not recommended that you use the cutting edge of a
stable branch for mission critical use, since a "stable" branch
may not always be as stable as point releases are. Use one of
those point release branches for those purposes.

The 1.8 branch is planed to be maintained until the third "stable"
branch (counting from 1.8) starts.

== Development of the 1.8 branch:

Committers are allowed to make a commit on a stable branch without
explicit approval from the branch manager, as long as it does not
break any backward compatibilities, that is, it does not delete or
change any existing features.

A list of exceptions is as follows. A commit may break backward
compatibilities only when all of the following conditions are met:

  • It only affects:

    1. behaviors which contradicts with the document,
    2. internal, unpublicized interface,
    3. undocumented features,
    4. undefined behaviors,
    5. presumable misuses.
  • The new behavior will not change again in nor contradict with
    the next major version series of Ruby.

  • If it is assumed that it may silently affect existing code in
    a subtle way, sufficient information and/or a support tool must
    be supplied with to help users fix their existing code.

  • It is well considered and reviewed in public and approved by
    the branch manager.

  • It is well documented and announced in ChangeLog and NEWS as
    soon as it goes in.

Committers should follow good practices listed as follows:

  • Respect fellow developers and contributors. Make contact with
    the maintainer(s) when touching a piece of code you do not own.
    When in doubt, ask first.

  • Test your changes before committing them. Besides running a
    build, it is mandatory to run test scripts, if any. It is
    always a good idea to add new tests that prove your changes are

  • Changes must first go to a development branch, get tested on the
    branch and ported back to stable branches, unless they are not
    applicable to the development branch. A development branch said
    here is usually the trunk.

  • Related changes must be committed together in a single
    transaction. Cosmetic changes must be separated from
    functional changes.

  • Keep ChangeLog. Keep documents in sync with implementation.

Note that the branch manager can claim any commit to the branch be
immediately backed out.