Pilgrim Commit Policy

  This page is monitored by the OLPC team.

  For Developers

PATCHES WELCOME!

The document below attempt to describe the branches used in our pilgrim repository and some guidelines for commits on these branches. If this looks daunting, don't despair! Patches are always welcome (sent to devel@, cscott@, or dennis@ laptop.org), and we'll worry through the arcana for you.

Master

The 'master' branch is reserved for clean commits (no merges!) of installation-independent code. If there are hard-coded paths in the patch, it doesn't belong in 'master'. C. Scott is the current master branch maintainer; please check with him before committing to master. Whenever possible, commit messages should start with the trac bug # which is being resolved by the commit, for example:

  Trac #3359: Time sync for XOs.

Every commit which adds an additional package should also include a description of what the package is and why it is being added to the build, for example:

  Trac #5434/#5435: use util-linux-ng instead of util-linux for rtcwake.
  
  util-linux is currently pulled into our builds as a hal dependency.
  We explicitly request util-linux-ng to replace it.  util-linux-ng
  contains the rtcwake command used to wake from suspend at intervals.

This avoids problems in the future where we have, say, added 'compat-libstc++-33' and can't remember why or what for or whether it's safe to remove.

The master branch is what we recommend to people who want to set up their own builds. It is kept up-to-date with the latest package, but kept free of the intertwingled machinery of our automated builds.

Autobuild

The 'autobuild' branch contains the customizations necessary to integrate pilgrim into our automated build system. These changes have hard coded paths, account and machine names, etc, and are not appropriate for master. Only commit directly to the 'autobuild' branch if you are making changes to the autobuild system and want those changes to propagate to all the build stream branches. Usually, you will git-merge master into autobuild to keep it up to date; from time to time we may rebase autobuild on master to keep the version history readable.

Stable branches

The stable branches ('ship.2', 'update.1', etc) are maintained by the stable build maintainer; that's currently Dennis. They are branched from the 'joyride' branch at string freeze, resynced with joyride at code freeze, and thereafter are git-cherry-pick'ed from master or joyride. Every commit to this branch should include a trac bug # and approval. The git history of stable branches should never be rewritten! Every stable build will record the git commit hashes for pilgrim and the repos used to create it, ensuring that we can reproduce the build exactly in the future.

All stable builds (actually, all builds) occur from a clean source pull. No edits are done on the build machines so that there is no chance that a build is done with uncommitted or unpublished code.

Joyride

The joyride branch is our dogfood branch. Please fix any breakage you cause promptly! Changes proposed for stable branches should in general by applied to joyride first and tested before being cherry-picked into the stable branch. The sole exception are ugly workarounds for bugs discovered during code freeze for which a quick-and-dirty pilgrim patch is the least-risk fix. These band-aids in general should only be committed to the stable branch; they should never land on joyride or master.

Unlike stable branches, the git history in joyride may be rewritten. (Care must be taken at the moment when doing so, since the autobuilder currently does a 'git-pull origin $BRANCH', and history rewrites may cause this to fail.)

A typical development cycle is:

1. a proposed build change is committed to joyride for testing.
2. bugs in the commit are fixed in joyride either with new commits or by amending the original commit.
3. When the commit has aged sufficiently on the joyride tree, it is cherry-picked into master and master is merged into autobuild and other trees. If it is appropriate for a stable branch, it is cherry-picked into it.
4. At intervals, joyride is rebased on autobuild to clean up the history. The git log will then show joyride picking up the patch from master. (This step may be done immediately when the patch is cherry-picked into master.)

Suggestions about step 4 are welcome. If we don't rebase joyride at intervals, the git log for joyride shows each patch twice: once when it was committed to joyride, and again when it was cherry-picked into master, since master is (via autobuild) eventually merged into joyride. The merge seems to go fine, so this problem seems to be purely cosmetic.

Other Branches

There are a number of other build streams, current & historical:

• Meshtest, for the mesh test bed. Based on joyride, with minor emendations: the meshtest package is added to run tests & reporting, and ohm is disabled (since our meshtest are currently B4 machines).
• XTest, for Bernie's X testing.
• Rainbow, for disruptive security testing.

These are branched from autobuild, and get updates by merging from there. Generally speaking, as long as you take care to keep master up-to-date, autobuild and the rest of the branches can take care of themselves.