From 4d1b730631dc05700f66b52451c91e847980c764 Mon Sep 17 00:00:00 2001 From: Jimmy Zelinskie Date: Wed, 28 Jan 2015 23:37:02 -0500 Subject: [PATCH] docs: update CONTRIBUTING.md This includes more information about style and the PR process. [skip ci] --- CONTRIBUTING.md | 72 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 55 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40b5467..06953e4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,3 @@ -## Code conventions - -The project follows idiomatic [Go conventions] for style. - -[Go conventions]: https://github.com/jzelinskie/conventions - ## Communication Currently, real time conversation happens on [#chihaya] on [freenode]. @@ -18,22 +12,66 @@ Please don't write massive patches without prior communication, as it will most likely lead to confusion and time wasted for everyone. However, small unannounced fixes are always welcome! -Pull requests should be targeted at the `master` branch. Before pushing to your -Github repo and issuing the pull request, please do two things: - -1. [Rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) your - local changes against the `master` branch. Resolve any conflicts - that arise. - -2. Run the test suite with the `godep go test -v ./...` command. - Pull requests will be treated as "review requests", and we will give -feedback we expect to see corrected on [style] and substance before pulling. +feedback we expect to see corrected on [style] and substance before merging. Changes contributed via pull request should focus on a single issue at a time, like any other. We will not accept pull-requests that try to "sneak" unrelated changes in. +The average contribution flow is as follows: + +- Create a topic branch from where you want to base your work. This is usually master. +- Make commits of logical units. +- Make sure your commit messages are in the [proper format] +- Push your changes to a topic branch in your fork of the repository. +- Submit a pull request. +- Your PR will be reviewed and merged by one of the maintainers. + + Any new files should include the license header found at the top of every source file. -[style]: https://github.com/jzelinskie/conventions +[style]: https://github.com/chihaya/chihaya/blob/master/CONTRIBUTING.md#style +[proper format]: https://github.com/chihaya/chihaya/blob/master/CONTRIBUTING.md#commit-messages + +## Style + +### Go + +The project follows idiomatic [Go conventions] for style. If you're just +starting out writing Go, you can check out this [meta-package] that documents +style idiomatic style decisions you will find in open source Go code. + + +[Go conventions]: https://github.com/golang/go/wiki/CodeReviewComments +[meta-package]: https://github.com/jzelinskie/conventions + +### Commit Messages + +We follow a rough convention for commit messages that is designed to answer two +questions: what changed and why. The subject line should feature the what and +the body of the commit should describe the why. + +``` +scripts: add the test-cluster command + +this uses tmux to setup a test cluster that you can easily kill and +start for debugging. + +Fixes #38 +``` + +The format can be described more formally as follows: + +``` +: + + + +