How to Use Git and GitHub

Getting started

If you’ve never used Git and/or GitHub before, GitHub assembled an awesome list of recommendations to get you started.

Below, you can find some additional guidelines on how to work with Git when contributing to the SCION project. If you have never used Git before, we strongly recommend reading it.

Even if you are experienced with Git, we recommend at least skimming it because it includes some additional information on how to write good commit messages and how the code review process works.

Forking the repository

The first step is to make your own personal fork of the main repository. You can do this by going to the SCION repo, and clicking the ‘Fork’ button on the top right, and then choosing your own personal repository.

This gives you a complete copy of the main scion repo in which you are free to make changes without affecting anyone else. The only downside is that you have a little extra work to do to keep it up to date with the main repo. This is covered below.

Setting up github auth

Interacting with GitHub using Git will require you to authenticate every time. To make your life easier, we strongly suggest setting up automated authentication using an SSH-key. GitHub has a nice doc on how to set it up.

Cloning the repository

Now that you have your own fork, follow the steps in the Setting up the Development Environment section to set up your workspace. When you get to the point of cloning the repository, use the directory indicated in the README, but clone your own fork into it instead:

cd "<workspace>"
git clone [email protected]:<username>/scion

(If you have authentication setup correctly, you won’t be prompted for a password.)

This will initialize a Git repository on your local machine and pull everything from your forked personal repository.

Keeping your personal fork up to date

To keep your personal fork in sync with the main repository, you need to add the main repo as new remote repository in your local clone. GitHub’s guide for this is pretty straightforward and can be summarised as follows:

git remote add upstream [email protected]:scionproto/scion.git

Now that you have this setup, the procedure for syncing is pretty straight-forward:

  1. Fetch the changes from the main repo: git fetch upstream

  2. Switch to your master branch: git checkout master

  3. Merge the upstream changes into your main branch: git merge --ff-only upstream/master

  4. Push the changes to your GitHub fork: git push

Submitting a pull request

Pull Requests are a powerful tool provided by GitHub mainly used to review code before it is merged into the main branch.

Preparing your pull request

Before you create your pull request (PR), make sure your code passes the unit testing and linting checks.

To run the tests, use the following command:

make test

The above command runs only the unit tests. As soon as you open your PR, some additional tests will run automatically.

To lint the code, run:

make lint

Good commit messages

We adhere to the rules in the Go Contribution Guide.

Here is an example of a good commit message:

sciond: do not panic on shutdown

SCIOND runs a tcp-messenger in client mode. There was a superfluous
deferred `CloseServer` call that panicked on shutdown.

Changes:
- Remove deferred `CloseServer` call on tcp-messenger in client mode
- Don't panic when calling `CloseServer` on a tcp-messenger with nil listener
- Move deferred `CloseServer` call in CS to the appropriate place

Fixes #3766

  • Starts with <subsystem:>

  • Uses lowercase letters for subject line

  • There is always a reference number to an issue

Submitting your pull request

To submit a pull request, you need to push your branch containing the new code to the GitHub repository (as explained above). This new branch will now appear in the web interface (under ‘branches’ on the main repository page). From there, you can click on ‘New pull request’ to add a description and check what’s included in the pull request.

You can then assign the pull request to one or more reviewers who will be notified to perform a code review.

Code reviews

GitHub’s code review interface is fairly basic and lacks some key features. To compensate for this, we use an external review system, reviewable.io. It integrates with the GitHub PR and keeps track of addressed or unresolved comments. When all issues pointed out by your reviewer are fixed, your code is likely ready to be merged.

Best practices

  • Keep your development branch(es) rebased on the master branch.

  • Squash your contributions into a single commit before sending a PR.

  • Incremental updates to a PR should be separate commits to allow reviewers to see the change.

  • Each PR should be self-contained as much as possible. It should have a description that covers all the changes and leave the codebase in a working state.

  • If you encounter any Git problems, ping someone on the Slack channel for help. Don’t struggle alone :)

Final comments

Git is a very powerful tool, and this tutorial only scratches the surface. It presents the most common use case to get you started. Please explore the vast amount of excellent Git and github resources available on the web..