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.
- Fork project on GitHub
- Clone your fork locally
- Setup upstream remote
- Create a feature branch off of master
- Commit your progress to your branch
- Fetch upstream master
- Update local master
- Rebase feature branch
- Push branch to your fork on GitHub
- Create pull request
0. Set up git and GitHub
1. Fork project on GitHub
2. Clone your fork locally
[chris@eames] $ git clone firstname.lastname@example.org:chriskelly/sdruby.git $ cd sdruby
3. Setup upstream remote
[(master) chris@eames] $ git remote add upstream email@example.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
To rebase interactively:
git rebase -i master
Learn more about interactive rebasing.
Credit Where Credit is Due
Some or all of the above ideas where influenced or borrowed from: