diff options
author | Ryan Geary <rtgnj42@gmail.com> | 2020-06-08 11:04:12 -0400 |
---|---|---|
committer | Ryan Geary <rtgnj42@gmail.com> | 2020-06-08 11:10:03 -0400 |
commit | dfbeb102bb38af4f4bbe70c6efa4e1ddfd3b9018 (patch) | |
tree | 87b298b0b69d5d3795a4f9f9fc7e3c5034a6fd32 | |
parent | 0cd42bb4fb82edbef4f01c42ce707dd5e2e1f05a (diff) |
Add CONTRIBUTING.md
-rw-r--r-- | contributing.md | 116 | ||||
-rw-r--r-- | readme.md | 4 |
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> +``` @@ -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 ``` |