[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gnu-arch-users] NEW POLICIES (draft)
From: |
Thomas Lord |
Subject: |
[Gnu-arch-users] NEW POLICIES (draft) |
Date: |
Sat, 2 Oct 2004 15:11:47 -0700 (PDT) |
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)
- [Gnu-arch-users] NEW POLICIES (draft),
Thomas Lord <=
Re: [Gnu-arch-users] NEW POLICIES (draft), Jeremy Shaw, 2004/10/02
Re: [Gnu-arch-users] NEW POLICIES (draft), Andrew Suffield, 2004/10/02