[Gnu-arch-users] NEW POLICIES (draft)

[Thomas Lord]

This document refers to some postscript diagrams.   Those can be found
at:

        http://www.gnuarch.org/stds
        http://regexps.srparish.net/www/stds

The archive containing this document is where you would expect to find
it (same as address@hidden with appropriate s/2004/gnu-arch-2004).

Thanks,
-t



Title: Tools and Policies for GNU Arch Release and Source Management
Author: Thomas Lord <address@hidden>
Date: 2004-10-01
Arch-std-id: address@hidden/stds--rel-src-mgt--1.0 (DRAFT)
Arch-std-references:



   Tools and Policies for GNU Arch Release and Source Management
                      Thomas Lord <address@hidden>
                              2004-10-01
      address@hidden/stds--rel-src-mgt--1.0 (DRAFT)



* Objective

  The objective of this memo is to specify a provisional set of 
  tools and policies for the management of the GNU Arch project,
  focusing particularly on issues of release and source code 
  management.

  Long term contributors to arch should come away from this memo with
  (a) knowledge of how best to contribute most effectively, as we move
  forward from today's state; (b) acknowledgement that, unfortunately,
  the new tools and policies represent a slight disruption of
  established practices and will therefore require contributors to
  adapt (such as by porting changes from one branch to another).  On
  the latter point (b), the nearly unanimous consensus is that the
  existing tools and policies have recently failed in an inelegant way
  and while an evolutionary refinement of those might in theory be
  possible, a wholesale switch to the new policies is a practical,
  simple, and immediately executable solution.

  Short term contributors may find this document difficult to follow:
  it presumes that the reader is fairly expert in arch matters
  generally and the GNU arch project specifically.  Nevertheless, this
  document contains information about how short term contributors can
  best participate.  (Perhaps later someone can extract and summarize 
  in a friendly form the information critical to casual contributors.)


* Topics Covered

  ~ Release Naming, Numbering, and Purpose
  ~ Semi-skipped Releases
  ~ Testing Candidate Naming, Numbering, and Purpose
  ~ Development and Distribution Phases and Scheduling
  ~ The Official Project Archives
  ~ Release/Test Candidate -> Arch Namespace Mapping
  ~ Release Components -> Arch Namespace Mapping
  ~ Branching Structures in the Official Archive
  ~ Quality Standards for Development Branches
  ~ Guidelines for Casual (single-shot) Contributions
  ~ Guidelines for Long-term Contributions, Including Integration
    Branches
  ~ Tools


* Release Naming, Numbering, and Purpose

** Historic GNU Releases

  The GNU Arch project has historically produced a series of
  of releases.  The series of releases is titled "tla" and 
  the numbering of releases has been:

       tla-1.1
       tla-1.2pre0
       tla-1.2pre1
       tla-1.2pre2
       tla-1.2pre3
       tla-1.2
       tla-1.2.1

   Recently, a volunteer effort failed to produce tla-1.2.2 and
   considerable confusion, disorganization, and disharmony has 
   resulted.


** New Release Naming and Numbering Policy

  The next release of GNU Arch will be called:

        tla-1.3

  (Calling the next release tla-1.3 both conforms to the
  conventions spelled out below (the name tla-1.2.2 would not).
  Additionally, it avoids any confusion about the status of 
  the now defunct 1.2.2 development effort.)

  In general, all GNU releases will have a name of the form:

        tla-<MAJOR>.<MINOR>[.<ERRATA>]

  where <MAJOR>, <MINOR>, and the optional component <ERRATA>
  are non-negative integers.

  At this time, <MAJOR> is 1 and <MINOR> is 3.

*** Major Releases

  A release of the form:

        tla-X.0

  is called a "major release".   Major releases will be made to 
  introduce:

        a) major new features that change how we expect many
           users to use arch in day to day work

        b) changes to the formats of archives, revision libraries,
           or working directories (very minor changes may be excepted)

        c) the addition of significant new functionality

        d) in general: any changes which suggest that users should
           upgrade with greater-than-usual attention and care


*** Minor Releases

 A major release may be followed by a series of minor releases.
 Following a major release of tla-X.0, there may be releases
 named:

        tla-X.Y

  where, in successive releases, Y is a series of integers, starting
  from 1.

  Minor releases will be made to introduce:

        a) bug fixes
        b) low-impact new features
        c) performance improvements
        d) upward compatible user interface changes


*** Errata Releases

  An errata release has a name of the form:

        tla-X.Y.Z

  where Z is a natural number (integer greater than or equal to 1).

  The errata release:

        tla-X.Y.1

  is an emergency correction to release:

        tla-X.Y

  and the errata release:

        tla-X.Y.Z       (with Z >= 2)

  is an emergency correction to release:

        tla-X.Y.Z-1

  Errata releases will be made for one reason only:

        a) critical (safety or usability related) bug fixes to the
           corresponding major or minor release, or to the immediately
           preceeding errata release


*** Ordering of Release Timing

  Major and minor releases will be made in strict, version number
  order.

  Errata releases may be made, for any existing release, at any time
  -- however, the GNU Arch project can not *promise* to make *any*
  errata release, regardless of circumstance.


* Semi-skipped Releases

  The process for producing a new release, described below,
  is a multi-step process.   Earlier in the process certain
  arch revision names are defined, thus defining what the 
  contents of the release will be.   Later in the process,
  the actual tar bundle is produced and announcements are made.

  Experience has shown and common sense would predict that, 
  from time to time, the release-making process will hit 
  a glitch in which, _after_ the arch namespace names for the 
  release have been assigned, show-stopper problems are discovered.

  A trivial (and fictional) example might be: during the release of
  tla-1.4, the contents of the release are irrevocably defined by some
  commits to an arch archive.  Unfortunately, immediately after the
  tar bundle is made available, but before announcements have been
  sent out, an early-adopter discovers that, strangely enough, an
  untested but commonly-used option to the `commit' command now fails
  because of a small typo in the argument parser.

  What will happen then?  (1) announcements for tla-1.4 will either
  not be made or will have the form of a warning to not use this
  release.  (2) As quickly as practical an errata release (tla-1.4.1)
  will be prepared.  That errata release will then be announced as-if
  it were the originally intended minor release.  The announcements
  for 1.4.1 will mention the issue with 1.4 and why it should be
  disregarded.

  This approach preserves (perhaps embarassingly) for history the
  mistakes of the project -- but more importantly, it preserves an
  accurate and consistent record of releases and revision control
  history.

  In such cases, a release like a failed tla-1.4 is called
  "semi-skipped" because, although the release has been formally
  defined, it is not promoted and use is discouraged.

  Web sites carrying tar bundles of releases are free to omit or
  otherwise set aside semi-skipped releases.


* Testing Candidate Naming, Numbering, and Purpose

  At any given time, the GNU Arch project may be working on a new
  minor release and/or a new major release and/or 0 or more errata
  releases.

  During those processes, the project may release a series of "test
  candidate" releases (aka "pre-releases" aka "release candidates").

  Testing candidate releases are intended for use by those people who
  volunteer to help test an upcoming release.

  For a release whose name is of the form:

        tla-X.Y[.Z]

  the series of test candidate releases will be named:

        tla-X.Y[.Z]preN

  where N is a non-negative integer.  Test candidates for a given
  release will be given successive "pre" numbers, starting from 0.

  As with major, minor and errata releases, test candidates may also
  be semi-skipped.  Unlike major, minor and errata releases, the
  expected case is that *most* test candidates will be semi-skipped.
  Thus, one might expect to see a series of (announced) test
  candidates followed by a release such as:

        tla-2.0pre38
        tla-2.0pre52
        tla-2.0pre60
        tla-2.0


* Development and Distribution Phases and Scheduling

  It is unrealistic and unwise to impose a strict, calendar based
  schedule on the production of testing candidates and releases.
  In place of such a schedule, the GNU Arch project will attempt 
  to adhere to the following guidelines:

  1) At each point in time, the project will have a declared
     a "next intended release".  For example, at the time of 
     this writing, the next intended release is "tla-1.3".

  2) While development on the next intended release proceeds, assuming
     reasonable rates of integration of changes, testing candidate
     distributions should be made approximately once per month.
     Exceptions to this policy can be expected when: there are too few
     new changes to warrant a testing candidate (no testing candidate
     distribution made); when important bugs have been found in a
     previous testing candidate (testing candidate distributions more
     frequently than 1/mo).

  3) It is a matter of the judgement of the project maintainer when
     releases (rather than testing candidate distributions) are made.



* The Official Project Archives

  The GNU Arch project shall create a sequence of archives.
  The history of releases and testing candidates will be 
  recorded in these archives in such a way that any specific
  release or testing candidate may be accurately reconstructed
  on the basis of these archives alone.

  At any one time, at most one archive (the latest) in this sequence
  will be "active" (i.e., allowing new revisions to be committed).
  All previous archives will be "frozen".

  All such archives will have a name of the form:

        <maintainer-email>--gnu-arch-<year>[<seq>]

  where:

        <maintainer-email> is the maintainer's email address
                           as it appears in his arch user id

        <year> is the year in which the archive is created

        <seq> is a string of lowercase letters, from the sequence:
              "b, c, ... z, ba, bb, ... bz, ca, cb ..."


  Thus, the first official project archive under this policy is:

        address@hidden


      -------------------------------------------
      /-----------------------------------------\

                      NOTE:

        In the remainder of this document, 
        the string "$OFFICIAL" will be used
        to denote the name of the most recent
        (i.e., active) official project archive.

        For example, the arch name:

          $OFFICIAL/dists

        means "the `dists' category in the 
        latest official archive.

      \-----------------------------------------/
      -------------------------------------------



* Release/Test Candidate -> Arch Namespace Mapping

 Beginning with tla-1.3 (and its testing candidates), major, minor,
 and errata releases as well as test candidates can all be
 reconstructed from the contemporary official archive ($OFFICIAL)
 using deterministic procedures:

** Major and Minor Releases

 A major or minor release, 

        tla-X.Y

 can be reconstructed from the archive with:

    % tla get $OFFICIAL/dists--tla--X.Y--version-0 tla
    % cd tla
    % tla buildcfg configs/gnu/This-release


** Errata Releases

  An errata release,

        tla-X.Y.Z

  can be reconstructed from the archive with:

    % tla get $OFFICIAL/dists--tla--X.Y--versionfix-Z tla
    % cd tla
    % tla buildcfg configs/gnu/This-release


** Major and Minor Test Candidates

  A test candidate for a major or minor release:

        tla-X.YpreN

  can be reconstructed from the archive with:

    % tla get $OFFICIAL/dists--tla--X.Y--patch-N tla
    % cd tla
    % tla buildcfg configs/gnu/This-release

    # except that for N==0 releases, the first
    # line is:
    % tla get $OFFICIAL/dists--tla--X.Y--base-0 tla


** Errata Test Candidates

  An errata test candidate:

        tla-X.Y.ZpreN

  can be reconstructed from the archive with:

    % tla get $OFFICIAL/dists--tla-errata-prep--X.Y.Z--patch-N tla
    % cd tla
    % tla buildcfg configs/gnu/This-release

    # except that for N==0 releases, the first
    # line is:
    % tla get $OFFICIAL/dists--tla--X.Y.Z--base-0 tla


* Release Components -> Arch Namespace Mapping

  [See ./branching.fig]

  The rules in the previous section map each release and testing
  candidate name to a revision name for a revision of the 
  top-level directory of a distribution.   For example, 
  release:

        tla-1.5

  corresponds to the top-level directory revision:

        dists--tla--1.5--version-0

  That top-level directory contains a configuration file naming the
  subdirectory components which comprise the distribution.   For
  example, the configuration must specify which revision of the
  subdirectory "src/tla" to use for tla-1.5.

  The question then arises: is there an arch naming convention for
  those component subdirectories?

** Current Components

  It is expected that tla-1.3 will be comprised of this list of
  sub-components:

        subcomponent       location              desc
        ------------       --------              ----
        package-framework  ./src                 configure/build infrastructure
        hackerlab          ./src/hackerlab       hackerlab C library
        tla                ./src/tla             core tla, itself
        docs-hackerlab     ./src/docs-hackerlab  hackerlab documentation
        docs-tla           ./src/docs-tla        the tla tutorial

  Subsequent releases may add or subtract components but this list
  will be used in the examples/illustrations that follow.

** Native vs. External Components

  Components of a tla release partition into two sets which can be 
  named the "native" components and the "external" components.
  Native components are those which are specific to arch and which
  are not immediately expected to appear in non-arch distributions.
  External components are those which have "a life of their own" --
  because they are used by other (non-arch) projects and/or because
  they are separately distributed.

  In the current list:

        native components               external components
        -----------------               -------------------
        tla                             package-framework
        docs-tla                        hackerlab
                                        docs-hackerlab


** Release Namespace Mapping for Native Components

  Each native component will be mapped to the arch namespace in a way
  that parallels the mapping used for "dists--tla".

  Specifically, for a major or minor release:

        tla-X.Y

  the native components will have names of the form:

        tla--devo--X.Y--version-0

  For an errata release:

        tla-X.Y.Z

  native components can be found at:

        tla--devo--X.Y--versionfix-Z

  NOTE: no deterministic mapping is given for native components 
  of *testing candidate* distributions.

  NOTE: the rules above imply that errata revisions for each native
  component are committed in parallel.   For example, suppose that 
  after the release of tla-5.3, a critical bug is discovered
  necessitating in the construction and release of tla-5.3.1.
  Also suppose that the change needed for 5.3.1 is a change to the
  "src/tla" subdirectory (component "tla") only.

  The top level directory for tla-5.3.1 is revision:

        dists--tla--5.3--versionfix-1

  The rule stated in this section asserts that the native component
  subdirectories correspond to revisions:


    subdir              component       revision
    ------              ---------       --------
    src/tla             tla             tla--devo--5.3--versionfix-1
    src/docs-tla        docs-tla        docs-tla--devo--5.3--versionfix-1

  That implies that the creation of 5.3.1 requires a commit to
  `docs-tla' even though it need not change for 5.3.1, which might
  be regarded as a drawback.

  The trade-off obtained for that drawback is a deterministic,
  off-line computable mapping from release names to component
  revisions, given only knowledge of the category name of the
  components.  

  For example, a programmer who wants to answer a question such as:
  "Was the `--frob' option to the subcommand `tweak' available in
  `tla-3.14.3'?" can quickly check, without needing to build a full 3.14
  tree, with:

        % tla get $OFFICIAL/tla--devo--3.14--versionfix-3 ,some-tree
        % find ,some-tree -name '*.c' -exec grep [...]


** Release Namespace Mapping for External Components

  For major, minor and errata releases, external components are
  mapped to the arch namespace in a manner similar to that for
  native components, but with the branch name "dists-tla" rather
  than devo.

  For example, the revision of the hackerlab C library in release
  tla-2.4 would be:

        hackerlab--dists-tla--2.4--version-0

  As with native components, no deterministic mapping is provided for
  external components of test candidate distributions.


* Branching Structures in the Official Archive

  Although exceptions are permitted, the official archive will 
  use the following branching structure whenever possible:

** Native Component Development Lines

  The primary development line for a native component for a 
  major or minor release is the same as the version whose 
  version-0 revision will define the component for that 
  release.

  For example, work on the "tla" subcomponent (subdir "src/tla")
  leading up to release:

        tla-X.Y

  takes place on version:

        tla--devo--X.Y

  The "base-0" and "patch-N" revisions of that version are "work
  leading up to a release" and, in the common case, revisions of 
  the tla component distributed in a "tla-X.YpreN" testing candidates
  will be drawn from among those "base-0" and "patch-N" revisions.

** Native Component Branching

  Suppose that work on tla-X.Y has just completed.   Among other
  things, the rules given above imply that, as part of that process,
  a "version-0" revision has been created:

        tla--devo--X.Y--version-0

  When that revision is created, a new branch will also be created
  which starts as a tag of that revision:

        tla--hub--X.Y--base-0
           is a tag of tla--devo--X.Y--version-0

  If work is begun on a follow-up minor release, that will be done
  on the branch starting with:

        tla--devo--X.Y+1--base-0
          is a tag of tla--hub--X.Y--base-0

  If work is begun on a follow-up major release, that will be done
  on the branch starting with:

        tla--devo--X+1.0--base-0
          is a tag of tla--hub--X.Y--base-0

  Thus, the "hub" branch serves as a star-topology patch-flow hub
  between the following minor and major releases, should both 
  happen to exist.

  The development branch of a native component for an errata release
  numbered 1, such as:

        tla-3.2.1

  begins with:

        tla--devo--3.2.1--base-0
          is a tag of tla--devo--3.2--version-0

  Similarly, an errata release against an earlier errata, such as:

        tla-3.2.2

  begins with:

        tla--devo--3.2.2--base-0
          is a tag of tla--devo--3.2--versionfix-1


** External Component Branching

  External component branches, such as:

        hackerlab--dists-tla--X.Y

  or the errata component:

        hackerlab--dists-tla--X.Y.Z

  will be tag-only branches, tagging appropriate revisions in the 
  separately developed external component.


* Quality Standards for Development Branches

  The development lines for native arch components shall be maintained
  in accordance with the following conventions:

  1. Log Message vs. English Usage

     Log message bodies must contain primarily complete english
     sentences, properly punctuated and capitalized.

  2. Log Body Purpose

     The body of a log message should clearly explain why the change
     was made.  It should explain, in high level terms, what the
     change consists of.

     The primary purpose of the body is to aid the understanding of 
     a third party reading the changeset for the change: the log body 
     should eliminate the need to "reverse engineer" the change based
     only on the changeset contents.

     Here is an example of an unacceptable log message body:

                fix cli foo in the commit command

     Here is an example of an acceptable log message body:

        The `--frob' option to `tla commit' was working incorrectly.
        First, the variable `frob_target' was not initialized and was 
        sometimes referenced without being set.  Second, when set,
        the variable was set to an allocated region but the size of 
        that region was computed incorrectly (an off-by-one error).
        This change properly initialized `frob_target' and corrects
        the allocation error.

   3. Log Summary

      Log summaries should usually *not* contain complete sentences.  
      Rather, they should be written in a "telegraphic" style -- using
      just a few words to convey the gist.  For example:

          Summary: fix `commit --frob'

      Certain BugGoo headers are acceptable in summary lines and
      should be used where applicable.   For example, if after a
      change is committed, a particular bug can be closed, the 
      summary should read as in the example:

          Summary: [CLOSE: 423] fix `commit --frob'


   4. Best-effort for Clean, Isolated Changesets

      Although exceptions are permitted, as a general rule, each
      change to any of the official development lines listed above
      should be a "clean, isolated changeset".  In other words:

        ~ each change change should be for a singular and specific
          purpose --- no lumping together of unrelated changes

        ~ correctness (absense of bugs) should be unchanged or
          (ideally) improved by each change --- no introduction of
          known-broken changes with the intention of "fixing them
          later"



* Guidelines for Casual (single-shot) Contributions

  A "Casual [source code] Contribution" to GNU Arch is defined 
  as a single change, submitted in isolation from other changes,
  generally by a person or group who do not expect to submit code
  changes frequently.

  A casual change is generally expected to be an "all or nothing
  change": in other words, the change can be added with a single merge 
  and no "follow-up" merges are expected.


** Casual Change Archive and Branching Structure

  Although exceptions may be permitted at the discretion of the
  maintainer, or with the cooperation of an integration engineer who
  will submit a casual change by proxy for a third party, normally
  casual contributions must be branched as follows:

  First, casual changes must be presented in the form of arch
  revisions.   Simple "diff-style" patch submissions are strongly
  discouraged.

  Second, casual changes must exist on a branch of their own and
  that branch should be a branch from the current development 
  mainline.    For example, supposing that the archive name of 
  the casual contributor is $CONTRIBUTOR, a contribution 
  should be in a development line:

        $CONTRIBUTOR/tla--FEATURE--X.Y

        where the string FEATURE is replaced with an appropriate
        short name for the contribution.

  The `base-0' revision of that version should be a tag of:

        $OFFICIAL/tla--devo--patch-N

  The contributed change should be the *only* difference between
  the contributors version and the mainline.  In particular,
  casual contributions should be mergable with the commands:

        % tla get $OFFICIAL/tla--devo--patch-N tla
        % cd tla
        % tla star-merge $CONTRIBUTOR/tla--FEATURE--X


** Casual Changes and Patch Log Entries

  NOTE: When casual changes are merged into the mainline

        NO PATCH LOG ENTRIES FROM THE CONTRIBUTOR WILL BE
        INCLUDED IN THE MERGE.

  In the illustrations above, after performing the merge:

        % tla get $OFFICIAL/tla--devo--patch-N tla
        % cd tla
        % tla star-merge $CONTRIBUTOR/tla--FEATURE--X

  contributors should assume the maintainer will perform:

        % tla remove-log-version $CONTRIBUTOR/tla--FEATURE--X

  and also remove any other patch log entries added by the merge.

  Therefore, casual contributions *must* include the addition of 
  a file:

        ./CONTRIBUTION-LOG

  which contains a draft patch log entry to be used during the commit
  of the change to the GNU mainline.

  The draft patch log entry is subject to the rules given earlier for
  patch log entries (see "Quality Standards for Development Branches").


** Casual Changes, Signatures, and Copyright Assignments

  Small and relatively simple changes may be freely accepted without
  any special requirements that submitters identify themselves,
  validate that they are the authors of the changes, or provide 
  copyright assignments.   As a rough guideline, a change of fewer than
  20 lines is likely to qualify as small;  a change of more than 1000
  lines is likely to not qualify as small; in between, judgement is
  called for.  A change which introduces a clever new algorithm, even
  if it is smaller than 1000 lines, is likely to not be considered
  simple; a change which corrects help message text or adds a needed
  memory deallocation is likely simple;  in between, judgement is
  called for.  [NOTE: these guidelines are subject to review by the FSF
  and may be adjusted accordingly.]

  Other changes will, in the relatively near future, require paperwork
  in the form of a copyright assignment to the FSF.   Policies and
  procedures for managing this paperwork will be announced as the
  conversion from (primarily) Tom Lord's copyright to FSF copyright
  takes place.

  Regardless of the handling of copyrights, casual contributions
  must ordinarilly satisfy the following properties:

   1. Valid and appropriate email address

      The email address portion of the contribution's archive must be
      valid and suitable for contacting the contributor.   Exceptions
      are possible for those who can not currently construct such
      archive names but, in those cases, a valid email address must
      be included in the ./CONTRIBUTION-LOG file.

   2. Signed archives are *strongly* preferred

      Normally, casual contribution archives should be signed
      archives and the submitter's public key must be separately
      made available to the maintainer.



* Guidelines for Long-term Contributions, Including Integration
  Branches

  A "Long-term Contribution" is a collection of changes which are
  expected to be merged "piecemeal".

  One example of a long-term contribution would be work on
  "librification".  The project has a long-term, multi-step plan for
  converting arch into a well-behaved C library.   Each step in the
  plan is a correctness-preserving-transformation, meaning that while
  the earlier steps do not complete the task, nevertheless, they may
  be merged early, even before the complete project of librification
  is done.

  Another example of a long-term contribution is an "integration
  branch".  An integration branch is formed when an appointed
  integration manager agrees to accept contributions from third
  parties and to do most of the work of merging in those contributions
  on a branch owned by the integration manager.  The appointment of
  integration managers is a way to increase the bandwidth and decrease
  the latency with which 3rd party contributions are processed.


** The Problem with Long Term Branches

  Long term branches are comprised of a sequence of changes with 
  the intention that contiguous subsequences will be merged into
  the mainline, in order.

  Between merges back to mainline, a long term branch might merge
  *from* the mainline multiple times, in order to keep up to date.

  It is naively tempting to say that long term branches should
  be, simply, arch versions branched from the GNU mainline
  and this is illustrated in ./naive-long-term.ps.

  (Referring to the diagram:) In this example, a long term branch
  has been prepared, progressed for a long while, and twice 
  udpated from the mainline using star-merge.   The GNU maintainer's
  goal here is to merge back from the long-term branch but
  not all at once.  Rather, we wish to merge each logical change 
  (such as the changes between base-0 and patch-A) in separate
  steps.   By merging in separate steps, the mainline patch log 
  will retain separate documentation for each logical change and
  the mainline will be more usefully suitable for "cherry-picking".

  The problem with the naive approach is mostly to do with conflict
  resolution:  At each star-merge-style update of the contributor
  branch from the mainline, the contributor resolves any conflicts 
  that have arisen between the mainline and earlier changes on the
  contribution branch.   No merge command exists (or could, even in
  principle exist) that would allow the logical patch
  (base-0...patch-A) to be applied to the mainline in such a way as to
  benefit from any subsequent conflict-resolution work done by the 
  contributor.


** The Solution: Cascade Branches

  There is a simple and elegant solution to the problem with 
  long term branches and that is to use "cascade branches",
  as illustrated in ./cascade.ps.

  The gist of the idea is that the logical steps of a long-term 
  branch each occupy a separate arch version, each step branched
  from the earlier steps.

  Thus, from the upstream-maintainer's perspective, the long-term
  (logical) branch is comprised of a series of arch versions, each of
  which behaves, for merging purposes, roughly like a casual
  contribution branch.

  From the contributor's perspective, each successive version in the
  cascade stands in an immediate-descended star-topology relationship
  to the previous, with the first step descended from the GNU
  mainline.

  One "cost" of this approach is that the contributor must explicitly
  plan out the logical steps and must go through the mechanics of
  making separate arch versions for each step.   To call this a "cost"
  is misleading, however: the "extra work" it implies is not "extra"
  at all and, in fact, the cascade arrangement provides a natural
  mechanism for performing the needed work.

  The primary benefit of this approach for contributors is that
  corrections can be made to earlier steps of a long-lived branch
  without winding up with "out of order" changes.   In effect, the
  contributor is maintaining the series of merge steps he advocates to
  upstream, with opportunity to revise earlier steps even as later
  steps proceed.

  Note that the diagram illustrates one pattern of merging that can be
  used to keep versions in the cascade up-to-date.   Many little
  variations are possible and appropriate in some circumstances -- it
  is assumed that those maintaining long-lived branches can either
  find these variations themselves (when needed) or that they know
  where to find help from other experts.


** Naming Conventions for Cascade Branches

  As the diagram implies, each version in a cascade should be numbered
  after its upstream version, with an added fourth element to the
  version id.   The sort-order of the resulting version ids should
  reflect the intended order of the steps.


** The Proper Use of Integration Branches

  Integration branches are collection points for contributions from
  other sources.   Cascade branches are collection points for
  *serialized* contributions.

  Thus, it is appropriate to use a set of cascade branches to prepare
  the integration of overlapping or otherwise interfering
  contributions, but it would be a waste of effort to use cascade
  branches for independent, unordered contributions.

  Therefore, integration managers who are vetting 3rd party
  contributions should take care not to make more work for themselves
  than necessary:  prepare ordinary casual contribution branches for
  isolated and order-independent changes;  prepare cascade branches
  only for changes upon which an order ought to be imposed.


** Reordering the Elements of a Cascade

  [This section intentionally left blank for this draft.   The
   mechanics of re-ordering a cascade are left to be explored and
   explained.  [It doesn't seem difficult, only tedious -t]]


** Patch Logs and Long-Lived Branches

  As with casual contribution branches, each version in a cascade
  should add a file containing a draft log message for the mainline
  merge.   In order to avoid conflicts, this file should be called:

        ./CONTRIBUTION-LOG.$BRANCH--$VERSION

        where $BRANCH--$VERSION is the branch label and version id
        of the version.

  The id tag for that file should include the fully qualified name
  of its version.

  For each cascade being merged into the mainline, the patch log of
  the most recently merged step will be retained in the mainline, and 
  all earlier patch logs from the same version will be removed.

  When a cascade is complete (no further steps (i.e., no further
  versions) are expected), the last remaining patch log for the 
  cascade will be removed.

  If a step in a cascade is the integration of a change from a third
  party, then the ./CONTRIBUTION-LOG file *must* identify the
  contributor of the change and the name and location of a public
  archive from which the change originated.   As procedures for
  collecting copyright assignments are created, integration managers
  processing 3rd party patches will become responsible for verifying
  and documenting -- before submitting a change for merger into
  mainline -- that paperwork (if needed) from the committer has been
  obtained and processed by the FSF.


* Tools

  [This section intentionally left blank for this draft.   It would be 
   helpful to assemble some scripts that help put a friendly and
   convention-aware interface on these policies.]


; arch-tag: Tom Lord Sat Oct  2 13:53:34 2004 (rel-src-mgt/rel-src-mgt.txt)