mirror of
https://github.com/clap-rs/clap
synced 2024-11-10 14:54:15 +00:00
110 lines
4.7 KiB
Markdown
110 lines
4.7 KiB
Markdown
# How to Contribute
|
|
|
|
Contributions are always welcome! And there is a multitude of ways in which you can help depending on what you like to do, or are good at. Anything from documentation, code cleanup, issue completion, new features, you name it, even filing issues is contributing and greatly appreciated!
|
|
|
|
Another really great way to help is if you find an interesting, or helpful way in which to use `clap`. You can either add it to the [examples/](examples) directory, or file an issue and tell me. I'm all about giving credit where credit is due :)
|
|
|
|
## Goals
|
|
|
|
There are a few goals of `clap` that I'd like to maintain throughout contributions. If your proposed changes break, or go against any of these goals we'll discuss the changes further before merging (but will *not* be ignored, all contributes are welcome!). These are by no means hard-and-fast rules, as I'm no expert and break them myself from time to time (even if by mistake or ignorance :P).
|
|
|
|
* Remain backwards compatible when possible
|
|
- If backwards compatibility *must* be broken, use deprecation warnings if at all possible before removing legacy code
|
|
- This does not apply for security concerns
|
|
* Parse arguments quickly
|
|
- Parsing of arguments shouldn't slow down usage of the main program
|
|
- This is also true of generating help and usage information (although *slightly* less stringent, as the program is about to exit)
|
|
* Try to be cognizant of memory usage
|
|
- Once parsing is complete, the memory footprint of `clap` should be low since the main program is the star of the show
|
|
* `panic!` on *developer* error
|
|
(e.g. [apps](https://github.com/clap-rs/clap/blob/62eff1f8d3394cef819b4aa7b23a1032fc584f03/src/build/app/debug_asserts.rs) and [args](https://github.com/clap-rs/clap/blob/62eff1f8d3394cef819b4aa7b23a1032fc584f03/src/build/arg/debug_asserts.rs)),
|
|
exit gracefully on *end-user* error
|
|
|
|
## General Overview
|
|
|
|
### Testing Code
|
|
|
|
To test with all features both enabled and disabled, you can run this command:
|
|
|
|
```sh
|
|
$ cargo test --features "wrap_help yaml regex unstable-replace"
|
|
```
|
|
|
|
Sometimes it's helpful to only run a subset of the tests, which can be done via:
|
|
|
|
```sh
|
|
$ cargo test --test <test_name>
|
|
```
|
|
|
|
### Linting Code
|
|
|
|
During the CI process `clap` runs against many different lints using [`clippy`](https://github.com/rust-lang/rust-clippy).
|
|
|
|
In order to check the code for lints and to format it run:
|
|
|
|
```sh
|
|
$ cargo clippy --features "wrap_help yaml regex unstable-replace" -- -D warnings
|
|
$ cargo fmt -- --check
|
|
```
|
|
|
|
### Debugging Code
|
|
|
|
Another helpful technique is to see the `clap` debug output while developing features. In order to see the debug output while running the full test suite or individual tests, run:
|
|
|
|
```sh
|
|
$ cargo test --features debug
|
|
|
|
# Or for individual tests
|
|
$ cargo test --test <test_name> --features debug
|
|
```
|
|
|
|
### Tests and Documentation
|
|
|
|
1. Create tests for your changes
|
|
2. **Ensure the tests are passing.** Run the tests as specified above.
|
|
3. **Ensure linting is passing** Run the lints as specified above.
|
|
4. Ensure your changes contain documentation if adding new APIs or features.
|
|
|
|
### Preparing the PR
|
|
|
|
1. `git rebase` into concise commits and remove `--fixup`s or `wip` commits (`git rebase -i HEAD~NUM` where `NUM` is number of commits back to start the rebase)
|
|
2. Push your changes back to your fork (`git push origin $your-branch`)
|
|
3. Create a pull request against `master`! (You can also create the pull request first, and we'll merge when ready. This a good way to discuss proposed changes.)
|
|
|
|
## Conditions for fulfilling a bounty:
|
|
|
|
1. You should make a pull request which fixes the issue the bounty was promised for
|
|
2. The pull request should be merged by one of the maintainers
|
|
|
|
### Below are the steps to redeem a bounty:
|
|
|
|
1. Go to https://opencollective.com/clap/expenses/new.
|
|
2. Select **Invoice**.
|
|
3. Enter **Expense Title** as "Issue Bounty".
|
|
4. In **Description**, link the issue you are redeeming _(Ex: `https://github.com/clap-rs/clap/issues/1464`)_
|
|
5. In **Amount**, write the amount that the issue promised _(Ex: 10)_
|
|
6. Fill payment information and submit
|
|
7. Wait for us to approve it
|
|
|
|
### Can I forgo the bounty?
|
|
|
|
Yes, you can. In that case, you don't have to do anything except writing a
|
|
comment on the issue saying that I do. The bounty will be reassigned to another
|
|
issue.
|
|
|
|
## Specific Tasks
|
|
|
|
### Section-specific CONTRIBUTING
|
|
|
|
- [Example CONTRIBUTING](./examples/README.md#contributing)
|
|
- [Tutorial (builder) CONTRIBUTING](./examples/tutorial_builder/README.md#contributing)
|
|
- [Tutorial (derive) CONTRIBUTING](./examples/tutorial_derive/README.md#contributing)
|
|
- [clap_derive CONTRIBUTING](./clap_derive/CONTRIBUTING.md)
|
|
|
|
### Updating MSRV
|
|
|
|
Search for `MSRV`, for example
|
|
```bash
|
|
$ rg --hidden MSRV
|
|
```
|
|
And update all of the references
|