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

[James Blackwell]

On Sat, Oct 02, 2004 at 03:11:47PM -0700, Thomas Lord wrote:
> 
> 
> 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).

Can we see this in text? 

> 
> 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)
> 
> 
> 
> _______________________________________________
> Gnu-arch-users mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/gnu-arch-users
> 
> GNU arch home page:
> http://savannah.gnu.org/projects/gnu-arch/

-- 
James Blackwell          Try something fun: For the next 24 hours, give
Smile more!              each person you meet a compliment!

GnuPG (ID 06357400) AAE4 8C76 58DA 5902 761D  247A 8A55 DA73 0635 7400