Skip to content

Latest commit

 

History

History
83 lines (64 loc) · 3.47 KB

CONTRIBUTING.md

File metadata and controls

83 lines (64 loc) · 3.47 KB
Raw

Contributing

Overview

  • Clone your fork locally and configure the upstream repo: git clone [email protected]:<your-github-username>/<repo> git remote add upstream git://github.com/7digital/<repo>
  • Make sure your line-endings are configured correctly: git config core.autocrlf false
  • Create a local branch: git checkout -b my-branch
  • Work on your feature, spiking/prototyping as required
  • Rebase as required (see below)
  • Push the branch up to GitHub: git push origin my-branch
  • Send a Pull Request on GitHub

You should never work on master, and you should never send a pull request from master - always from a branch. The reasons for this are detailed below.

Guidelines for creating a pull request and notes on style

Following these guidelines will make it much easier for us to appraise and merge your pull requests.

  • Please make sure you follow the git blessed conventions for all your commit messages.
  • Please do make sure each individual commit is a discrete piece of functionality and that each commit lints ok and passes all the tests and any new functionality is accompanied by tests. This is not optional!
  • Please try to explain why you are suggesting a particular change in as much detail as possible. Preferably with real world examples.
  • Fixing deviations from coding style and whitespace policy is also encouraged, but if these are slipping through jshint then consider adjusting the rules to automate preventing these issues happening in the future.

Please do not merge your own pull requests!

Basic Git workflow

While you are working away in your branch it is quite possible that your upstream master may be updated. If this happens you should:

Stash any un-committed changes you need to

git checkout master
git pull upstream master
git checkout my-branch
git rebase master my-branch
git push origin master

This ensures that your history is "clean" i.e. you have one branch off from master followed by your changes in a straight line. Failing to do this ends up with several "messy" merges in your history, which we would rather avoid. This is the reason why you should always work in a branch and you should never be working in or sending pull requests from master.

If you are working on a long running feature then you may want to do this quite often, rather than run the risk of potential merge issues further down the line. When you are ready to go you should confirm that you are up to date and rebased with upstream/master (see "Handling Updates from Upstream/Master" above), and then:

git push origin my-branch

Note that it is important to rebase as described above off master before asking for a pull request to be merged, we will just ask you to do this anyway if you have forgotten - make sure you mention this in the pull request in case people have cloned your fork.

If you have already published your branch in your own fork, you will have to force push your branch as git (rightly) will warn you that you are about to rewrite history on a branch that has already been shared.

git push -f origin my-branch

When you are happy to share the code, send a descriptive Pull Request on GitHub (see notes above).

Finally, it is perfectly ok and in fact welcomed to submit pull requests on experimental branches for the purposes of a design discussion or to show off a spike of some implementation. Please be clear about this in the pull request message.