Contributing

notch8 edited this page Jun 28, 2012 · 13 revisions
Clone this wiki locally

How To Contribute

  • Always develop on a branch: You should always make your changes in a branch, never on master. Your branch name should be descriptive and be prefixed by the issue number if you are working on a specific issue.

  • Each feature/issue should be its own branch: When starting work on a new feature or issue, you should always start from master. Branching from a branch should be reserved for experimenting on that branch. If you are working on an specific issue number, that should prefix your branch name (e.g., 123-branch-name).

  • Rebase your branch onto upstream/master: Do not merge upstream master into your branch, always use rebase. If you are working on a long issue or feature, be sure to rebase master in regularly to avoid complex merge conflicts.

  • Squash commits into one with a meaningful message: Commit regularly on your own branch with short, appropriate messages. When preparing your branch for a pull, squash your commits and add a final commit message that follow the commit message guidelines.

Workflow Summary

  1. Fork project on GitHub
  2. Clone your fork locally
  3. Setup upstream remote
  4. Create a feature branch off of master
  5. Commit your progress to your branch
  6. Fetch upstream master
  7. Update local master
  8. Rebase feature branch
  9. Push branch to your fork on GitHub
  10. Create pull request

Workflow Detail

0. Set up git and GitHub

If you have not done so already, you will need an account on GitHub and configure your local development environment to work with GitHub.

1. Fork project on GitHub

2. Clone your fork locally

[chris@eames]
$ git clone git@github.com:chriskelly/sdruby.git
$ cd sdruby

3. Setup upstream remote

[(master) chris@eames]
$ git remote add upstream git@github.com:sdruby/sdruby.git

4. Create a feature branch off of master

[(master) chris@eames]
$ git checkout -b 123-descriptive-branch-name

5. Commit your progress to your branch

[(123-descriptive-branch-name) chris@eames]
$ git commit -m "Short descriptive commit message"

6. Fetch upstream master

[(123-descriptive-branch-name) chris@eames]
$ git fetch upstream

7. Update local master

[(123-descriptive-branch-name) chris@eames]
$ git checkout master
# => Switched to branch 'master'

[(master) chris@eames]
$ git merge upstream/master

8. Rebase feature branch

[(master) chris@eames]
$ git checkout 123-descriptive-branch-name
# => Switched to branch '123-descriptive-branch-name'

[(123-descriptive-branch-name) chris@eames]
$ git rebase master

9. Push branch to your fork on GitHub

[(123-descriptive-branch-name) chris@eames]
$ git push origin 123-descriptive-branch-name

10. Create pull request

Select your branch on your fork

Click pull request button

Make sure you submit your pull request to sdruby:master.

Set your feature branch to be pulled into upstream/master

Good Commit Messages

Writing good commit messages will help reviewers understand your contribution and will speed up the pull process. Unlike the running commit messages you use during TDD development, the final commit message should have substantially more content. A good commit messages consists of a clear summary line and an optional detailed explanation of the commit.

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the present tense: "Fix bug" and not "Fixed
bug."  This convention matches up with commit messages generated by
commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, preceded by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent

Squashing Commit Messages

You should commit often on your local branch while developing. These messages should be short and simple, you can set the commit message inline with git commit -m "message here". Sometimes your commit message might not be something you need/want added to the project history, in which case you should rebase your feature branch interactively to squash those messages. By squashing these messages, you leave only the pertinent messages for other contributors to review.

To rebase interactively:

git rebase -i master

Learn more about interactive rebasing.

Other Resources

Credit Where Credit is Due

Some or all of the above ideas where influenced or borrowed from: