Workflow for Custodian git Repositories

Philosophy of custodian trees
How to get a tree
Initial checkout
Pushing changes
- But I am asked for a password...
Notifying the maintainer and the mailing-list
Tips for maintaining custodian trees

git.denx.de: The git trees for custodians are hosted here. They can be accessed from the outside as regular git trees. The available trees and the currently assigned custodians are listed on the Custodians page.
Note: Several of the git commands listed on this page require git version 1.5 or later
Intro to Distributed Version Control (Illustrated): Traditional version control helps you backup, track and synchronize files. Distributed version control makes it easy to share changes. Done right, you can get the best of both worlds: simple merging and centralized releases...
http://wiki.koha.org/doku.php?id=en:development:git_usage: This is a very useful description of a development methodology using the git version control system. This does not exactly match the u-boot methodology, but is very close.
Koha git motto: Every time a patch falls on the floor, a kitten dies.
http://www.andrewmoore.com/public/index.php/My_git_workflow: Andrew Moore explains in extremely lucid detail how to use git to "commit early and commit often" in a local working git repository, then rearrange and squash the incremental changesets into logical changesets and, ultimately, create the right patches at the right level of granularity and in the right sequence. Priceless!
http://ktown.kde.org/~zrusin/git/: Git cheat sheets in various sizes

Philosophy of custodian trees

My idea of a custodian repository is that it is more than just a working tool for collecting patches and preparing these for merge into mainline. My idea is instead that these are pretty much independent incarnations of U-Boot source trees which users (note: users, not only developers) with specific needs or interests can refer to.

For example, in my set of mind somebody interested in the latest 85xx code would clone the 85xx custodian repository, expecting that he finds there the most current code for this family of processors. Probably he will never sync himself against mainline, but instead continue update (pull) from the 85xx custodian repository.

That means, that my idea is that it is the custodian's responsibility to provide a permanently accessible, consistent view of his repository to users. When he collects patches, he will - after sufficient review and testing - decide that these are good enough to go into his repository. And at certain points we will pull all the stuff that has been collected there into mainline.

How to get a tree

As this process is not automated, the first step is to apply for a tree either on the mailing list or at info {at} denx.de directly. All we basically need is the public part of an ssh key, so we can setup authentication for that tree.

For the following example we assume that Dave Bowman takes up custodianship of the U-Boot port for the OpenRISC architecture and provided us with "id_rsa.pub" after he did an "ssh-keygen -t rsa". According to our conventions, he will get write access to the tree with the account name "gu-or32", where gu is the prefix for U-Boot Git custodians.

Initial checkout

To start out, after the account has been setup, Dave simply clones the publicly available tree as usual:

$ git clone git://git.denx.de/u-boot-or32.git u-boot-or32

$ git clone http://git.denx.de/u-boot-or32.git u-boot-or32

Pushing changes

Being the owner of the tree, after having done commits on it, Dave can push the changes upstream via ssh and the ssh public key that he provided in the first step, e.g. doing the following in the repo should Simply Work™ for him.

$ git push ssh://gu-or32@git.denx.de/u-boot-or32

Note that the accounts do not allow logins on our webserver:

$ ssh gu_or32@git.denx.de
[...]
fatal: protocol error: bad line length character

Which is just another way of saying

I'm afraid I cannot do that Dave.

Similar errors result if Dave tries to clone from ssh://gu-or32@git.denx.de/u-boot-or32 - he should really use the "normal" git repository git://git.denx.de/u-boot-or32.git for cloning or updating his local tree, the ssh (git+ssh) access method can only be used for pushing.

But I am asked for a password...

If pushing fails because you are asked for a password, please verify if you really used the public key, either through ssh-agent or through an explicit statement in your .ssh/config file. With the first form you should have told your ssh-agent about the public key. Usually its enough to do a "ssh-add" as long as you don't have multiple keys; otherwise do an "ssh-add <keyname>" explicitely.

If you get an error-message like "Could not open a connection to your authentication agent." then you don't have an agent running. Just do an "ssh-agent bash" and afterwards the key-adding.

You can always check with "ssh-add -L" what keys can be used by the agent. Be sure that the key you want to use is on the list.

In case this does not help, then please send the output of "ssh -vvv <user>@git.denx.de" to wd {at} denx.de .

Notifying the maintainer and the mailing-list

After pushing the changes into your repository, please notify the maintainer (Wolfgang Denk <wd {at} denx.de>) and the U-Boot users mailing-list <u-boot {at} lists.denx.de> about the changes you recently made. Please use the command git request-pull to generate a summary for this purpose.

Tips for maintaining custodian trees

Branch usage convention:
- master - Changes that the repository owner wishes to be pulled into the master u-boot repository.
- next - Hold changesets waiting for the next merge window to open.
- uboot - Optional: pull changes from the main u-boot repository into this branch so that it can be used to rebase working and master branches, applying master repository changes to the work in progress.
  - Note: This will be a local branch - there is no need to push it back to denx.de.
  - Tip: I removed the "-" in "u-boot" because I'm lazy and git makes you use "--" if there is a dash in the branch name — JerryVanBaren).
- testing - Optional: changes that are in work, published on the u-boot email list, but not ready for the mainline u-boot repository yet. When the patch(es) are mature, they can be "cherry-picked" or merged into the master or next branch and pulled from there into the master u-boot repository.
- (Of course there may be other branches for local work in progress, but they should not be pushed to the denx.de u-boot repository).
- Only push useful branches to the custodian repository on git.denx.de and delete branches when they become obsolete.
  - To see what branches are hanging around:
    - $ git branch -r # only remote branches
    - $ git branch -a # local and remote branches
  - To remove an obsolete branch on the master server (in this example, testing-USB):
    - $ git push ssh://gu-<subrepo>@git.denx.de/u-boot-<subrepo>.git :heads/testing-USB
Keep the uboot branch in sync with the master u-boot repository by pulling it.
$ git checkout uboot
$ git pull git://git.denx.de/u-boot.git
Rebase the master, testing and any "work in progress" branches to the uboot to move work in progress changes "after" the uboot branch (which should always reflect the One Repo to Rule Them All).
$ git checkout master
$ git rebase uboot
$ git checkout testing
$ git rebase uboot
- This allows Wolfgang to pull the master branch without having any merge conflicts because the custodian will have seen and fixed them already.
Push the appropriate branch(es) to the denx.de repo:
$ git push ssh://gu-<subrepo>@git.denx.de/u-boot-<subrepo> master
$ git push ssh://gu-<subrepo>@git.denx.de/u-boot-<subrepo> testing
- Pushing the testing and/or rebased master branches often requires the -f force flag. This is because the state/content/order of the patches in the branch changed due to the rebase operations.
- Tip: I do not use the -f flag the first time just in case it isn't needed.
Send a pull request to the email list and Wolfgang
- Use an email subject line that includes "Pull request:"
- Use git request-pull to show what changes will be pulled and includes a convenient reference to the custodian repository (from the git request-pull parameters).
  $ git request-pull uboot <url-to-subrepo> master

Applying patches

The easiest way to apply patches requires them to be in the format of an e-mail message with a descriptive subject and <Signed-off-by> entry. Multiple patch files can be concatenated. To apply such a patch:

$ git am --signoff --whitespace=strip < PATCH_FILE

BEFORE Requesting a Pull

Before you request a pull, make sure there are no merge conflicts with the mainline. See above for the recommended way of pulling the u-boot master repository tip and rebase the master branch.

As part of the rebase, RESOLVE ALL MERGE CONFLICTS
At this point you can request the branch to be merged into the mainline. If the mainline has more changes before the merge occurs, repeat the above steps to fix any bit rot in the subrepo master branch.

Pushing

To push changes in a single branch:

$ git push ssh://gu-<subrepo>@git.denx.de/u-boot-<subrepo> <branch>

Using git push --all is not recommended. It pushes all of your local branches to the custodian repository and results in branch pollution.

After Wolfgang merges your changes

Since you cloned the custodian subrepo tree, not the mainline, you need to explicitly pull from the mainline.

$ git checkout master # Go to the master branch to pull the latest u-boot (mainline) changes.
$ git pull git://git.denx.de/u-boot.git
$ git branch -d <branch> # remove the now unnecessary branch (assuming branches are used and the given branch is no longer desired)

Pulling changes from a given branch

$ git pull git://git.denx.de/u-boot-<subrepo> <branch>