Github workflow

(If you are a total beginner to git, you might also want to check The beginner's guide to rebasing and squashing)

You will need to fork the servo/servo repository in order to be able to publish your changes. In these instructions <mozilla> is the name of the remote pointing to the remote atgit@github.com:servo/servo.git and <fork> is the remote pointing at your fork of the repository.

1. Fetch the latest code and create a local branch:

$ git fetch <mozilla>

$ git checkout -b <local_branch> <mozilla>/master

2. Code/hack/do stuff then commit:

$ git commit -a

See Git tips below for helpful tips on using git.

3. Push local branch to your cloned repository:

$ git push --set-upstream <fork> <local_branch>

(git push -u <fork> <local_branch>[:remote_name] should work if you want to publish your changes to a branch with a different name than [local_branch].)

4. Create a PR in GitHub. If you know who should code review this PR, you can write r? @username in the text of the PR and they will automatically be assigned to it. If not, don't worry: a reviewer will be randomly selected and notified.

5. Wait for reviewers' feedback - if something needs to be fixed, either amend the existing commits if the changes are minor, or fix it in a new commit on the same branch, optionally using --fixup:

$ git commit --fixup=<sha1_of_relevant_commit_on_branch>

Alternatively, add the following to your .gitconfig and simply use git fixup:

[alias]
	fixup = !sh -c 'git commit -m \"fixup! $(git log -1 --format='\\''%s'\\'' $@ | sed \"s/fixup\\! //\")\"' -
	ri = rebase --interactive --autosquash

6. Use git push to update the Pull Request. Repeat steps 5-6 until the review is accepted. If existing commits were amended, a force push will be necessary (see step 8).

7. When you know there is a substantive change on master that affects your patch, update <mozilla> and rebase your local branch to make sure your patch still applies correctly:

$ git fetch <mozilla>

$ git rebase <mozilla>/master

You may have to fix merge conflicts on the way.

8. Force-push your changes:

$ git push -f <fork> <local_branch>

9. Once your patch is accepted and based on a recent master, squash the commits together for a cleaner history (if requested):

   $ git rebase -i --autosquash <mozilla>/master

10. Force push the squashed commits to github (see step 8).

11. When the reviewer thinks the code is ready, they will leave a comment saying "r+", meaning "review granted." Then our Homu bot will automatically test and merge your PR. Congratulations!

Git tips

Test-tidy commit hook

All commits to servo must pass a source code tidiness check (run with ./mach test-tidy). This is automatically run by our CI infrastructure, but to save time you should run this check locally before submitting or updating a pull request.

You can have Git can do the heavy lifting of remembering to do this by creating a pre-commit (recommended) or pre-push Git hook. A pre-commit hook will run test-tidy before each commit; a pre-push hook will do it before each push.

Put the following in either /path/to/your/servo/checkout/.git/hooks/pre-commit or /path/to/your/servo/checkout/.git/hooks/pre-push and make it executable (via chmod +x):

#!/bin/sh
./mach test-tidy
if [ $? != 0 ]; then
    printf >&2 "\`./mach test-tidy\` failed: please fix the errors above\n"
    exit 1
fi

If you try this and it doesn't suit your workflow, simply remove the file to get rid of the hook.