contributing.md

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.

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 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! 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>