Policies about Repository Use
This page is work in progress. These topics will be discussed
at the WR workshop in Madrid, on Nov 27-28 2012.
While still volatile as of 2012-11-01, the page is not specific
to White Rabbit but generic about development on ohwr.org (both
software and gateware). Please link it from other projects when
it makes sense, it's location won't change.
The Resources and the Problem
Unfortunately, the engine that drives ohwr.org only supports one
repository per project. This means that concurrent development
must work on a single repository, where stable releases and unclean
tests coexist.
To be able to freely experiment, people needs to change
history. For example to fix a bug in an already-committed patch,
or to change a commit message to make it more useful to others.
On the other hand, we need persistent commit identifiers, especially
when a project is used as a "git submodule" of another project. If
one commit is used as a submodule, we cannot risk losing it.
The Tools
Development (i.e., volatile commit identifiers) may just happen
on other repositories, outside ohwr. This means github.com,
gitorious.com or one's own machine with ssh access for mates. However,
the overhead for users is not considered worth the effort.
Therefore, we can count on the following tools to implement a
sensible policy. Most users should already know them:
- Named branches. Different names have different meanings: people
should know that names like "master" or "stable-2012-10" are different
from "devel-rubi-121101" or "testing-new-pll".
- Renames. Renaming a branch doesn't change any commit identifier.
- Tags. If a commit is pinned by a tag, it won't disappear until the
tag
is removed. The tag can be like "v2.1" or "projectname-v2.1". The
latter convention allows to tag external projects when needed
(for example, the fine-delay projects used tags in spec-sw and
zio to pin down the commits it relied on).
- Submodules. A submodule makes the supermodule refer to a
specific commit of another project. You must ensure that that
very commit must remain available in the future.
- Merges. When a merge happens, the commit identifiers of both
branches
will remain.
- Rebases. A rebase, interactive or not, changes all commit
identifiers. Previous numbers are lost, and you can't go back
to that specific checkout. This happens even if you only rephrase
a commit message.
The Rules
Based on the above, this is a set of proposed rules to obey.
- Master is holy for normal developers: only the maintainer should
push
to master, or approve others to push specific commits.
- Master is holy for the maintainer: no rebase is ever
permitted. Everybody can base their development or fetch a
submodule from a commit that is an ancestor of master. (I'd add
a special exception, allowing the maintainer to change master right
after a wrong push, like giving a 4-hour window; this means it's
safe to base on commit that are at least a little old).
- All development must happen in private branches.
- Before requesting a merge to master, consider rebasing to the
current tip of master. This is a controversial point, and different
people have strong and differing ideas. Please consider both options
and choose what to follow case by case.
- Git submodules must only refer to master commits, tags or
branches of stable forks (e.g., a backport).
- Nobody can remove branches or tags by other developers, unless
authorized by said developer.
- If your branch or tag needs to be persistent, because it is a
submodule of something else, name it clearly as stable or
important stuff. This will save you from being asked by others
to remove them. You can rename a branch without losing
information or commits.
- Whenever a binary is shipped (software or vhdl), it should
claim which commit it was compiled from -- for example, for
software we can use "git describe" to get a useful string. Binaries
from uncommited code or non-precious commits should be only used
temporarily for experimenting.
- If your repository refers to external binaries, make sure the name
of those binaries is not generic. If later releases of your repository
will refer to different binaries, you can't just overwrite them, or
users running the previous version will get in trouble.
A Few Suggestions
I (Alessandro) strongly suggest to keep a backup if your
development on your personal machines, so any rebase made by
others won't lose your commits (such rebases are errors, for
sure, but they still may happen).
You'll notice that most of my development branches have a date
inside, of the form YYMMDD -- I plan to stop coding before
2100 :) . When I rebase, I push a new branch with a different
date, and delete the previous one(s) when the time is ripe. This
allows me to have a backup of every branch: I have a local
repository for every project, that makes a "git fetch work" every
hour, under cron.
To setup a similar mechanism, you can just do this
cd /path/to/git-backup
mkdir $project
cd $project
git init --bare
git remote add work $HOME/work/$project
If every directory inside /path/to/git-backup
includes a remote
called "work" or some other magic work, you can just fetch them all.
I personally have a few magic names that are fetched by cron
.
Thanks
Thanks to Mathias Kreider for raising the problem on the mailing
list. Thanks to Benoit Rat, Tomasz Wlostowski, Emilio G. Cota
for the points they raised on the list, which I hope to have properly
represented here. Thanks to David Cobas for commanding me to
write this page. Thanks to everybody who'll edit as I hate wiki
editors and wrote this offline.