- When you start working on an existing GitHub issue (or you plan on doing that in the immediate future), assign it to yourself, so that others can see it and don’t start working on it in parallel.
- When you create a branch to work on something, use the naming scheme described further down in this document.
- Never push directly to the
masterbranch for any changes to the source code itself.
- As soon as you want others to review your changes, or even just discuss them, create a pull request. Don’t forget to explain roughly what it is you’re doing in that branch, i.e. what the problem/idea is and what the result is supposed to be, when merging the changes. If necessary or helpful, mention related discussions from other issues.
- A pull request can be merged as soon as at least two people with commit access to the repo have given a +1, meaning they reviewed and tested the changes and have no further improvements to suggest.
Using common branch names, that include topics and issue IDs, makes everyone’s lives much easier, and keep the repo clean. Branches on our organization repositories should be created using the following scheme:
So for example, if you want to work on fixing a bug with let’s say initial sync, that is described in issue #423, the branch should look something like:
And if it’s an enhancement to the widget it could look like this e.g.:
If there’s no issue yet, create one first!
--rebase when pulling code from the org repo. That way
your local changes are added on top of the current history, avoiding
merge commits and the mixing up the commit history. You can set up Git
to use rebase by default by running
git config --global branch.autosetuprebase always once.
The easiest way to update your local repository with all remote changes,
including all branches – old and new – is a tool called
git-up. With that installed you
can just run
git up instead of
git pull [options], which will
fetch all branches from all remotes and rebase your commits on top of
them (as well as stash and unstash uncommitted code, if necessary).
- The first line of the message (aptly called “subject line” in Git terminology) should not be longer than 72 characters.
- If the subject line is not enough to describe the changes properly, add a blank line after the subject line and then as much text as you want, using normal language with capitalization, punctuation, etc.
- Always use messages that describe roughly what the change does and, if not obvious, why this change leads to the desired result.
- Leave out any text that isn’t directly associated with the changes, that the commit introduces. Examples: “as suggested by @chucknorris”, “lol wtf was that”, “not sure if this fixes it”.
- Commit as much and often as possible locally (and with any message
that helps you during your work), and then clean up the history and
merge commits that belong together before pushing to the org repo.
You can do that with
git rebase -i [ref](learn more).
- You can reference issues from commit messages by adding keywords with
issue numbers. Certain keywords will even close the issue
automatically, once a branch is merged into master. For example
Fix widget flickering when opening bubble (fixes #423)will close issue #423 when appearing on the master branch at GitHub.
Reviewing pull requests¶
- Check if it works, if it has unit tests, if the tests pass, and if JSHint and CodeClimate are happy.
- Check if the code is understandable, with clear and unambiguous names for functions and variables, and that it has JSDoc comments and a changelog entry.
- If you use
git up, like recommended above, it will automatically create tracked branches for all remote branches. So in order to review/test a branch on the org repo, just do
git checkout [branchname]. You can then also add new commits to that branch and push them in order to add your changes to the pull request.
- If the pull request was issued from a user’s own repository, you’ll
have to fetch the code from there, of course. If you haven’t pulled
from that user yet, you can add a new remote for the user with
git remote add [username] [repo-url]. After that,
git upwill fetch code from that remote as well, so you can then check it out using
git checkout [username]/branchname.
(This will put you in a so-called ‘detached HEAD’ state, but don’t
worry, everything is fine! If you want to work on that code, just create
a new branch from there with the command Git shows you then, or just go
back to your code with e.g.
git checkout master later.)
Merging pull requests¶
- Once a pull request has two +1s for the latest changes from collaborators, you can either merge it yourself or wait for somebody to do it for you (which will happen very soon).
- If the new commits and their commit messages in that branch all make sense on their own, you can use the merge button on GitHub directly.
- If there are a lot of small commits, which might not make sense on
their own, or pollute the main project history (often the case with
long running pull requests with a lot of additions during their
lifetime), fetch the latest changes to your local machine, and either
do an interactive rebase to clean up branch and merge normally, or
git merge --squashto squash them all into one commit during the merge.
- Whenever you squash multiple commits with either
git rebase -ior
git merge --squash, make sure to follow the commit message guidelines above. Don’t just leave all old commit messages in there (which is the default), but delete them and create a new meaningful message for the whole changeset.
- When squashing/editing/amending other peoples’ commits, use
--authorto set them as the original author. You don’t need full names for that, but just something that Git can find in the history. It’ll tell you if it can’t find an author and let you do it again.