Gitpolicies

Overview

Overview

This page is intended to represent a consensus on conventions for users
of the Emulab git repository. If you agree with the guidelines
described here, then please keep them in mind when carrying out Emulab
work; if you disagree, then please edit them or provide feedback
to testbed-dev@flux.utah.edu.

General notes

In general, different policies apply to different repositories:

We should be extremely strict about public release repositories,
and also careful with public stable repositories.

Please attempt to follow our guidelines when pushing to our central
(development) repository, unless there is a good reason not to.

Shared personal repositories (those from which others might pull)
don't need to follow any conventions (although it might make things
easier for other people if you at least try).

And anything goes as far as private personal repositories are concerned.

Policies

Repositories

We provide read-only access to the Emulab git-public repository for
developers at other sites. At the present time, write access is limited
to special circumstances (such as particular directories for administrators
of Emulab installations who have shown an interest
in contributing code). If you fall into this category, send mail to
testbed-ops to request an account
on our git server. Please include an ssh public key when you send
your request.

The git server is git-public.flux.utah.edu, and write access is via
ssh only. ssh access is via public key: passwords are not allowed. This
server is intended for git access only - you'll find it doesn't have
much of anything at all installed.

So, to clone the repository, you would do the following:

git clone git-public.flux.utah.edu:/flux/git/testbed.git

Once you have a git clone, following the instructions for
upgrading
your site.

If you would like to track the daily git commits, there are two
possibilities:

Layout

Branches

Creation and deletion

Branches (and especially local branches) are extremely cheap in git.
Don't be afraid to create branches liberally for your own convenience.
"Topic branches" (branches created solely to collect a series of
logically related or dependent commits) are often very helpful.

However, branches are not free, either: especially those pushed out
to remote repositories. They should be cleaned up when they're no
longer useful ("git branch -d" is perfectly safe, since it will
proceed only if the branch is fully merged).

Long-term branches which are tracked and installed at other sites
are not to be taken lightly. The (explicit or implied) commitment
to testing, maintenance and support overwhelms the relatively
insignificant revision control system overhead.

Merging

git is very good at merging commits. Unfortunately, its power
also means that there are a variety of ways to merge which will
only cause subsequent inconvenience. Using git effectively does
require a certain amount of discipline.

Merging vs. rebasing

Because git merge commits are convenient and often implied by default,
it is sometimes easy to apply them even when they are inappropriate.
Merge commits (those with more than one parent) are sensible when
merging branches which were developed independently over an
extended period and had both been made public previously. They
are sometimes (but not always) appropriate when merging topic
branches. They are not appropriate when making a small private
change public, simply because another independent commit was published
since the last time you synchronised to the public repository.

"git rebase" is a simple way to avoid many useless merge commits.
"git pull --rebase" will often avoid them in the first place. Usually,
rebasing is what you want to do in a private repository and not what
you want to do in a public one.

You may configure a branch to automatically rebase instead of merge when you run "git pull" by setting the rebase config variable for that branch. The following command may be used to do this:

git config branch.<branchname>.rebase true

This setting is especially recommended on your private repository's master branch if you wish to use a more CVS-like workflow with few to no topic branches. However, only set this on branches that other developers aren't pulling from. Otherwise, they will have a difficult time merging your changes with theirs if they pull from your branch after you've rebased.

Commits

We will be giving a number of outside developers commit access to the
Emulab git repository.

General prerequisites to getting commit access to Emulab git:

Submit a number of patches, over a period of time, that are accepted by
the Emulab developers

Follow the general conventions (we don't have rigid rules) found in
existing Emulab code

Show yourself to be careful (see note below)

Expectations for those with commit access:

VERY IMPORTANT: Utah runs on the HEAD of gitmaster - so assume that anything you commit WILL be installed in Utah
within hours, and if you break anything, you will have to deal with some
very cranky people.

Be careful! See # 1.

You will be added to the testbed-dev list at Utah, where many of the
development discussions take place, so that you can let us know what
projects you're working on, and you can see what others are working on.

Discuss non-trivial changes with Utah before committing, or better yet,
before starting on them (the more you commit, the more this expectation
is relaxed).

Quality control

FIXME what expectations should we have about the quality of code
in a repository? How far should we allow code which is known to
be incomplete (or even broken) to get? What level of testing is
expected for code in particular states? (These expectations will
naturally vary depending on the branch and repository to which it
is committed.)

Commit messages

Please follow the
standard git conventions
when writing commit messages (which is really just a matter of starting
messages with a one-line summary).

Keep in mind that commit messages are public. There's no need for them
to be formal, but they should be descriptive. And of course, we should
try to avoid publishing libelous, private, or unnecessarily obscene commit
messages.

Rewriting history

Please do not rewrite history (i.e. commit anything to a branch
unless the new commit is a descendent of the current head) on the
main repository, unless exceptional circumstances apply (discuss
on testbed-dev@flux.utah.edu first). receive.denyNonFastForwards
is set on the main repository, so history rewriting will be rejected by
default.

Rewriting history on a public personal repository is generally
not a big deal, though it is worth considering first the consequences for
anybody who might be tracking you.

Rewriting history on a private personal repository is not only
harmless, but often a good idea. Sometimes, hindsight after a
series of commits will suggest a clearer way to present your
work, in which case rearranging the commits before they are
pushed out can help. ("git rebase --interactive" can be a
good way to clean up before pushing.)

Reverting commits

For shared repositories, please revert commits with "git revert".
This will record the reversion in the history, which is what we want
in this case.

To revert a commit which has never been made public, "git reset"
or similar is often a cleaner approach: this essentially conceals
the fact that the erroneous commit ever existed.

Tags

FIXME do we want to have any policies for tags? Sign tags on
released versions, maybe?