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/` and feature branches should be named +`feature/`. **Any hotfix or feature branch should only address +one issue/feature**. + +``` +$ git checkout -b 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 +$ 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 +``` + +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 +``` 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 ```