SourceCodeRepositories

Embedded code for our PIC-based boards is currently being versioned in a number of Git repositories at the biomimetics GitHub organization.

Create a GitHub account

To work with the lab's GitHub repositories, first create a free GitHub account. All your public repos (incl. your forks of the biomimetics' repos) will live under your user account. Please send your username to fgb so that he can list you as an organization member. This doesn't necessarily give you any special commit rights, but is very useful when trying to track down the work of other members.

Download and install Git

You'll then need to download and install Git. If you'd like a GUI client, we recommend SmartGit (cross-platform), SourceTree (mac), or Gitg (linux), which are featured enough for regular Git usage. The GitHub clients for mac and windows allow one-click cloning of GitHub repositories, but are otherwise very limited in functionality.

Set up your commit credentials

A commit in Git can be thought of as an e-mail. You're required to sign it with your credentials, so you should set up your name and e-mail on every Git installation you plan to use. You'll also need a commit message, the first line of which could be thought of as the subject of the e-mail (and should be about 50 characters long with no period). Longer messages should leave an empty line after the first and be wrapped at about 72 characters from then on. The message should be written in the present tense. For more info, check this short blog post.

Understand the development workflow

As you might have inferred by now, even though you can become a member of the biomimetics organization, you don't necessarily have any commit rights to its repos or to any of the repos of its other members. Since everything is public, you can fork any of these repos and push your changes to these public forks. This will enable you to submit your commits to the originating repository as a pull request. Code review and testing can then take place before the code is merged into the master tree.

This type of development can be thought of as two-steps removed from the stable/official repos (the ones under the biomimetics organization). An official repo can be forked into the user's account and then cloned into the user's computer. Development happens locally on the computer, isolating broken/in-development code from the public as much as possible. When that code is further improved, it can be pushed to the user's public fork where a pull request can be issued. Code review and testing as part of the pull-request process ensures that the merged code works well and that it includes standard headers and follows the lab's code styling guidelines. At least one other member must review the code and sign-off on it before it can be merged into master or any other integration branch.

General guidelines:

• Keep master clean, so you can pull from the origin remote frequently without conflicts.
• New development happens in feature branches, which should branch from an integration branch and be limited to one feature/idea.
• If you rely on two or more feature branches for your project, you should create a temporary/disposable integration branch where you merge them all (although commits only take place in the feature branches).
• Pull requests to the originating repository should be issued from the relevant feature branch. Note that further commits to the feature branch will dynamically update the pull request.

This development workflow is loosely based on git-flow and the related yet simpler flows that the matplotlib and GitHub developers follow.

Learn Git and its terminology

• gitref is a great reference of the basic Git concepts and its command line interface.
• Pro Git is an in-depth treatise by Scott Chacon on everything git.