Add CONTRIBUTING.md

This commit is contained in:
Ryan Geary 2020-06-08 11:04:12 -04:00
parent 0cd42bb4fb
commit dfbeb102bb
2 changed files with 120 additions and 0 deletions

116
contributing.md Normal file
View file

@ -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>
```

View file

@ -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
```