Skip to content. | Skip to navigation

Personal tools

Navigation

You are here: Home / Wiki / Gitpolicies

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:

  1. Visit the online Changelog an a regular basis.
  2. Send a request to testbed operations to place you on the git commit mailing list. Each commit log entry is sent to this list, which sounds like a lot of traffic, but is not that bad, really.

Layout

FIXME what code goes where: which repository, and which directory? Mention conventions, licence constraints, etc.

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:

  1. Submit a number of patches, over a period of time, that are accepted by the Emulab developers
  2. Follow the general conventions (we don't have rigid rules) found in existing Emulab code
  3. Show yourself to be careful (see note below)

Expectations for those with commit access:

  1. VERY IMPORTANT: Utah runs on the HEAD of git master - 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.
  2. Be careful! See # 1.
  3. 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.
  4. 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).
  5. Big changes should be tested using an Emulab in Emulab before committing.

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?

Releases

FIXME document policy here. We should think about release schedules, testing, maintenance, format, tracking...

Support

FIXME more thought needed. What will we support, how, and for how long?

Workflow

A description of the suggested workflow is available, and includes examples of git command lines which conforms to the policies above.