Add CONTRIBUTING.md

2 files changed, 120 insertions, 0 deletions

diff --git a/contributing.md b/contributing.md
new file mode 100644
index 0000000..795c007
--- /dev/null
+++ b/contributing.md
@@ -0,0 +1,116 @@
+# Contributing
+
+Thank you for considering contributing to `choose`!
+
+To save your time and mine, I will attempt to maintain brevity in this
+document, adding more details where there are common questions or
+misunderstandings.
+
+## Where To Start
+
+If you have found a bug or would like to request a feature, [open an
+issue](https://github.com/theryangeary/choose/issues/new).
+
+It is best if you get confirmation of your bug or approval for a feature
+request before taking the time to write the code.
+
+## Fork && Create Branch
+
+If you have confirmation/approval and would like to try your hand at making the
+change, [fork `choose`](https://help.github.com/articles/fork-a-repo) and create
+a branch with a descriptive name.
+
+Branch off of `develop`. Bug fix branches should be named
+`hotfix/<descriptive-name>` and feature branches should be named
+`feature/<descriptive-name>`. **Any hotfix or feature branch should only address
+one issue/feature**.
+
+```
+$ git checkout -b <branch-name> develop
+```
+
+## Check The Test Suite
+
+Before making any changes, make sure that both the unit tests and the end-to-end
+tests all work.
+
+```
+$ cargo test
+$ test/e2e_test.sh
+```
+
+If you are planning on making changes that may affect performance, consider
+using the benchmark script `test/bench.sh` as well.
+
+## Implement Your Fix/Feature
+
+### Write tests
+
+Tests are important.
+
+If you are fixing a bug, add tests that identify that bug and any permutations
+of it you can find, so we can ensure it doesn't come back.
+
+If you are creating a feature, add tests that will comprehensively ensure the
+feature works as expected, in conjunction with all other features, switches,
+options, etc.
+
+### Write code
+
+It should be correct. It should be fast. It should be idiomatic. Ask for help if
+you need it, don't be shy.
+
+### Write documentation (if needed)
+
+If your feature adds a new command line switch or option, add that info to the
+readme or any other relevant locations.
+
+## Make a Pull Request
+
+Once you've finished your changes, make sure that your develop branch is up to
+date.
+
+```
+$ git remote add upstream git@github.com:theryangeary/choose.git
+$ git checkout develop
+$ git pull upstream develop
+```
+
+Check that your code is all formatted correctly. If not, commit any changes.
+
+```
+$ git checkout <your-branch>
+$ cargo fmt
+$ git status
+```
+
+Rebase and squash your branch on develop. This will prompt you with a list of
+your commits. Change all but the first commit to "squash". Write a nice
+changelog message in the resulting commit.
+
+```
+$ git rebase -i develop
+```
+
+Push to your fork.
+
+```
+$ git push --set-upstream origin <your-branch>
+```
+
+Go to GitHub and [make a Pull
+Request](https://help.github.com/articles/creating-a-pull-request)! Make sure
+that your Pull Request is against `develop` and not `master`!
+
+## Keep Your Pull Request Updated
+
+After making your Pull Request, you may be asked to make some changes. After
+completing and commiting your changes, you will need to rebase and resquash your
+commits. Each Pull Request will effectively be a single commit added to the
+`develop` branch.
+
+After changing and committing, push like this:
+
+```
+$ git push --force-with-lease <your-branch>
+```
diff --git a/readme.md b/readme.md
index bfcbe5f..0b6faca 100644
--- a/readme.md
+++ b/readme.md
@@ -35,6 +35,10 @@ rather a simple and intuitive tool to reach for when the basics of `awk` or
 `cut` will do, but the overhead of getting them to behave should not be
 necessary.
 
+## Contributing
+
+Please see our guidelines in [contributing.md](contributing.md).
+
 ## Usage
 
 ```