Git workflows

Important: A lot of ROS assumes that the various machines that are talked to have roughly the same idea of messages, services, resource files, etc, etc. We use git to keep everything synchronised between machines. It is important that a well defined workflow is used.

We use something akin to GitHub flow. Read about it. Also watch one of the many videos on YouTube about branching and merging in git.

Rule 1: master is always good

Everything in the master branches in our repos should be runnable. Except for rare occasions, see making local changes on Q.bo below, the Q.bo will only ever have the master branch checked out. If you make a change to one of the qbo_... repos, only changes in the master branch will make it onto the robot long-term.

However, never commit directly to master. Everything must end up on master either via git merge or, far preferably, via a pull request on GitHub.

Making a change on your machine

Always work on feature branches. The very first thing you should do after cloning a repository from GitHub is to create a feature branch and always branch from master. The best way to do this is to explicitly give master as the branch point in git branch.

$ git clone [email protected]:sigproc/the-repo
$ cd the-repo
$ git branch feature-branch-name master   # create branch 'feature-branch-name' from 'master'
$ git checkout feature-branch-name        # move to the branch, commits will now be on this branch

Branches are always named like-this, never likeThis, LikeThis, likethis or like this.

Making a local change on Q.bo

Firstly: do you really need to make the change on Q.bo first, rather than making the change on your own machine, testing it, committing it and pulling on Q.bo? Think carefully. An example of where changes must necessarily be made on the Q.bo are when files are updated on it by nodes, e.g. when calibrating the cameras.

Secondly: read how to create and apply a patch with Git.

Thirdly: the Q.bo will need to be able to access the Internet. Make sure the wired connection is plugged in.

The motivation for the indirect way we do the changes (create a branch on the Q.bo, manually transfer to your machine, push to GitHub and then pull back to the Q.bo) is that it makes sure that all changes on the Q.bo which are in master branches must be backed up on GitHub and must be annotated with who made the changes. Both of these things are important if we ever want to re-install the robot.

If you have thought carefully, and read the article above, the first thing to do is to work on a separate branch:

(on Q.bo)
$ roscd package_name
$ git checkout master
$ git checkout -b feature-branch-name

Make your changes, making sure to git commit early and often. You should then have a branch which is one or more commits ahead of master. Create a series of patches:

(on Q.bo)
$ git format-patch --stdout master >my-changes.mbox

This will print out the names of the patch file(s). Copy them to your machine:

(on your machine)
$ scp qbo:~/cued-masters/path/to/my-changes.mbox  .

Now, on your machine, create a new branch:

(on your machine)
$ roscd package_name
$ git checkout master
$ git checkout -b feature-branch-name

Apply each patch:

(on your machine)
$ git am --signoff < path/to/my-changes.mbox

The --signoff is there to add Signed-off-by tags to each commit. That way you can note that you've made the changes and think they're OK.

Now merge the branch and push as usual:

(on your machine)
$ git checkout master
$ git merge --no-ff feature-branch-name
$ git push

Finally, update the Q.bo:

(on Q.bo)
$ git checkout master
$ git pull
$ git branch -d feature-branch-name    # you may need to use '-D' and not '-d'