CustodianGitTrees < U-Boot

---+!! Workflow for Custodian git Repositories

%TOC%

---

<dl>
<dt> [[https://gitlab.denx.de/u-boot/custodians][gitlab.denx.de]] </dt>
<dd> 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 [[U-Boot.Custodians][Custodians]] page.

*Note:* Several of the git commands listed on this page require git version 1.5 or later
</dd>

<dt> [[http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/][Intro to Distributed Version Control (Illustrated)]] </dt>
<dd>
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...
</dd>

<dt> http://wiki.koha-community.org/wiki/Version_Control_Using_Git </dt>
<dd> 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. <br> Koha git motto: _Every time a patch falls on the floor, a kitten dies._ </dd>

<dt> http://www.andrewmoore.com/public/index.php/My_git_workflow </dt>
<dd> 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! </dd>

<dt> http://ktown.kde.org/~zrusin/git/ </dt>
<dd> Git cheat sheets in various sizes </dd>
</dl>

---++ 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.

---++ Upstream and downstream trees

The [[https://gitlab.denx.de/u-boot][u-boot]] tree holds
the mainline code and is the reference for official U-Boot releases.
It is the *upstream* tree of all other trees; custodians of these trees
must submit a pull request to u-boot for their new code to become part
of the mainline and, eventually, of a release.

... well, almost.

ARM trees also form a hierarchy, with the
[[https://gitlab.denx.de/u-boot/custodians/u-boot-arm][u-boot-arm]] tree
'above', and
[[https://gitlab.denx.de/u-boot/custodians/u-boot-atmel][u-boot-atmel]],
[[https://gitlab.denx.de/u-boot/custodians/u-boot-imx][u-boot-imx]],
[[https://gitlab.denx.de/u-boot/custodians/u-boot-marvell][u-boot-marvell]],
[[https://gitlab.denx.de/u-boot/custodians/u-boot-pxa][u-boot-pxa]],
[[https://gitlab.denx.de/u-boot/custodians/u-boot-samsung][u-boot-samsung]],
and [[https://gitlab.denx.de/u-boot/custodians/u-boot-ti][u-boot-ti]] trees 'below'; 
their upstream is u-boot-arm, not u-boot.

Therefore, in the instructions below, when _upstream_ is mentioned, it is
_u-boot-arm_ if the downstream tree is an ARM subtree, and _u-boot_ otherwise.

So from then on, when you see =${upstream}=, you should replace this with
=u-boot-arm= if you are an ARM subrepo custodian, or =u-boot= if not.

Alternatively, you can define a shell environment variable, using either of:

   * =setenv upstream u-boot= or =setenv upstream u-boot-arm=
   * =set upstream=u-boot= or =set upstream=u-boot-arm=

... depending on your actual shell.

---++ 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 [[http://en.wikipedia.org/wiki/OpenRISC][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:

<verbatim>
$ subrepo=or32 # change to your sub-repository name
$ git clone git@gitlab.denx.de:u-boot/custodians/u-boot-${subrepo}.git u-boot-${subrepo}
</verbatim>
or
<verbatim>
$ git clone https://gitlab.denx.de/u-boot/custodians/u-boot-${subrepo}.git u-boot-${subrepo}
</verbatim>

---++ 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&trade; for him.

<verbatim>
$ git push git@gitlab.denx.de:u-boot/custodians/u-boot-${subrepo}
</verbatim>

Note that the accounts do not allow ssh logins on our gitlab server:

<verbatim>
$ ssh gu_or32@gitlab.denx.de
[...]
fatal: protocol error: bad line length character
</verbatim>

Which is just another way of saying

<verbatim>
I'm afraid I cannot do that Dave.
</verbatim>

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://gitlab.denx.de/u-boot/custodians/u-boot-or32.git= for cloning or
updating his local tree, the ssh (git+ssh) access method can *only* be used for
fetching and 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 &lt;keyname&gt;"= 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 &lt;user&gt;@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 upstream
maintainer (Wolfgang Denk &lt;wd {at} denx.de&gt; for u-boot, Albert Aribaud
&lt;albert {dot} u {dot} boot {at} aribaud {dot} net&gt; for u-boot-arm) and
the U-Boot users mailing-list &lt;u-boot {at} lists.denx.de&gt; 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. This can be based above =master=.  It must not be referenced elsewhere as it can and will be rebased as needed.
      * =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 upstream repository).
      * Only push useful branches to the custodian repository on gitlab.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://git@gitlab.denx.de/u-boot/custodians/u-boot-${subrepo}.git :heads/testing-USB=
   * Keep in sync with the upstream repository by pulling it. <br> =$ git fetch ssh://git@gitlab.denx.de/${upstream}.git=
   * Rebase the =master, testing= and any "work in progress" branches to the =${upstream}/master= remote branch (which always reflect the One Repo to Rule Them All). <br> =$ git checkout master= <br> =$ git rebase ${upstream}/master= <br> =$ git checkout next= <br> =$ git rebase master= <br>You can and should also keep the optional branches rebased, preferably on =master=, or on =${upstream}/master=.
      * This allows the upstream custodian to pull the =master= branch without having any merge conflicts because the downstream custodian (you) will have seen and fixed them already.
   * Push the appropriate branch(es) to the denx.de repo: <br> =$ git push ssh://git@gitlab.denx.de/u-boot/custodians/u-boot-${subrepo} master= <br> =$ git push ssh://git@gitlab.denx.de/u-boot/custodians/u-boot-${subrepo} next=
      * 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 <a href="mailto:wd@denx.de,u-boot@lists.denx.de?subject=Pull request: u-boot-${subrepo}">pull</a> request to the email list *and* to the upstream custodian(s)
      * 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). <br> =$ git request-pull ${upstream}/master ssh://git@gitlab.denx.de/u-boot/custodians/u-boot-${subrepo}.git 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 *&lt;Signed-off-by&gt;* entry.  Multiple patch files can be concatenated.  To apply such a patch:
<verbatim>
$ git am --signoff --whitespace=strip < PATCH_FILE
</verbatim>

---+++ 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, %RED% RESOLVE ALL MERGE CONFLICTS %ENDCOLOR%
   * At this point you can request the branch to be merged into the upstream repository. If the upstream 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:
<verbatim>
$ git push ssh://git@gitlab.denx.de/u-boot/custodians/u-boot-${subrepo} <branch>
</verbatim>
Using =git push --all= is __not__ recommended.  It pushes all of your local branches to the custodian repository and results in branch pollution.

---+++ After the upstream custodian merges your changes

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

   1 =$ git fetch ssh://git@gitlab.denx.de/${upstream}.git= to fetch the latest upstream changes.
   1 =$ git checkout master= # Go to your master branch to rebase.
   1 =$ git rebase ${upstream}/master= your =master= is now right above the upstream =master=.

---+++ Fetching changes from a given branch

<verbatim>
$ git fetch ssh://git@gitlab.denx.de/u-boot/custodians/u-boot-${subrepo} <branch>
</verbatim>

Note: this only copies the branch into your repo. You can then merge, rebase, cherry-pick at your leisure.

---+++ Nickname the upstream and frequently fetched repositories

Using =git remote add u-boot-${repo} git@gitlab.denx.de/${repo}.git= allows you to refer to the repo
by its nickname =${repo}= in all fetch operations. For instance, having done once
=git remote add u-boot git@gitlab.denx.de/u-boot/u-boot.git=, fetching the =u-boot= tree is done simply by
=git fetch u-boot=.