1# How to Contribute 2 3Contributions 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! 4 5## Goals 6 7There 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). 8 9* Remain backwards compatible when possible 10 - If backwards compatibility *must* be broken, use deprecation warnings if at all possible before removing legacy code 11 - This does not apply for security concerns 12* Parse arguments quickly 13 - Parsing of arguments shouldn't slow down usage of the main program 14 - This is also true of generating help and usage information (although *slightly* less stringent, as the program is about to exit) 15* Try to be cognizant of memory usage 16 - Once parsing is complete, the memory footprint of `clap` should be low since the main program is the star of the show 17* `panic!` on *developer* error 18 (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)), 19 exit gracefully on *end-user* error 20 21## General Overview 22 23### Where to Start 24 25- [Discussions](https://github.com/clap-rs/clap/discussions) can be useful for getting help and brainstorming 26- [Issues](https://github.com/clap-rs/clap/issues) work well discussing a need and how to solve it 27 - Focus: requirements gathering and design discussions 28 - Sometimes a branch or Draft PR might be used to demonstrate an idea 29- [PRs](https://github.com/clap-rs/clap/pulls) work well for when the solution has already been discussed as an Issue or there is little to no discussion (obvious bug or documentation fixes) 30 - Focus: implementation discussions 31 32### Compatibility Expectations 33 34Our releases fall into one of: 35- Major releases which are reserved for breaking changes 36 - Aspire to at least 6-9 months between releases 37 - Remove all deprecated functionality 38 - Changes in help/error output that could cause glaring inconsistencies in end-user applications 39 - Try to minimize new breaking changes to ease user transition and reduce time "we go dark" (unreleased feature-branch) 40 - Upon release, a minor release will be made for the previous major that enables `deprecated` feature by default 41- Minor releases which are for minor compatibility changes 42 - Aspire to at least 2 months between releases 43 - Changes to MSRV 44 - Wide-spread help/error output changes that would cause minor inconsistencies in end-user applications 45 - Deprecating existing functionality (behind the `deprecated` feature flag) 46 - Making the `deprecated` feature flag enabled-by-default (only on last planned minor release) 47 - `#[doc(hidden)]` all deprecated items in the prior minor release 48- Patch releases 49 - One for every user-facing, user-contributed PR (i.e. release early, release often) 50 - Changes in help/error output that are one-off or improving consistency so as to not increase inconsistency with end-user applications 51 52If your change does not fit within a "patch" release, please coordinate with the clap maintainers for how to handle the situation. 53 54Some practices to avoid breaking changes 55- Duplicate functionality, with old functionality marked as "deprecated" 56 - Common documentation pattern: `/// Deprecated in [Issue #XXX](https://github.com/clap-rs/clap/issues/XXX), replaced with [intra-doc-link]` 57 - Common deprecation pattern: `#[cfg_attr(feature = "deprecated", deprecated(since = "X.Y.Z", note = "Replaced with `ITEM` in Issue #XXX"))]` 58 - `deprecated` feature flag is to allow people to process them on their 59 time table and allow us to process feedback from early adopters before 60 requiring everyone to process them on the next major version. 61 - Please keep API addition and deprecation in separate commits in a PR to make it easier to review 62- Develop the feature behind an `unstable-<name>` feature flag with a stablization tracking issue (e.g. [Multicall Tracking issue](https://github.com/clap-rs/clap/issues/2861)) 63 64### Version Support Policy 65 66As we work towards [a more flexible architecture](https://github.com/clap-rs/clap/discussions/3476), we hope to support multiple major versions to help ease users through the upgrade churn. 67 68| Version | Status | Support | End-of-Life | 69|------------------------------------------------------|---------------|---------|-------------| 70| [v4](https://github.com/clap-rs/clap/tree/master) | active | Features and bug fixes target `master` by default | TBD | 71| [v3](https://github.com/clap-rs/clap/tree/v3-master) | maintenance | Accepting trivial cherry-picks from `master` (i.e. minimal conflict resolution) by contributors and fixes for ecosystem-wide showstoppers | TBD | 72| [v2](https://github.com/clap-rs/clap/tree/v2-master) | deprecated | Only accepting fixes for ecosystem-wide showstoppers | TBD | 73| v1 | unsupported | \- | \- | 74 75Note: We have not yet determined the End-of-Life schedule for previous major versions. We will give at least a 2 month warning before changing the support status. 76 77### Verifying Changes 78 79A common (sub)set of commands for verifying your change: 80```sh 81$ make test-full 82$ make clippy-full 83$ make doc 84``` 85*(If `make` is not available on your system, you can look up what these expand to in the [Makefile](./Makefile))* 86 87Check out the [Makefile](./Makefile) for more commands run by CI. 88 89### Debugging Clap 90 91A 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: 92 93```console 94$ cargo test --features debug 95 96# Or for individual tests 97$ cargo test --test <test_name> --features debug 98``` 99 100### Preparing the PR 101 1021. `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) 1032. Push your changes back to your fork (`git push origin $your-branch`) 1043. 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.) 105 106PR expectations: 107- Changes are tested and, if needed, documented 108- PRs remain small and focused 109 - If needed, we can put changes behind feature flags as they evolve 110- Commits are atomic (i.e. do a single thing) 111- Commits are in [Conventional Commit](https://www.conventionalcommits.org/) style 112 113We recognize that these are ideals and we don't want lack of comfort with git 114to get in the way of contributing. If you didn't do these, bring it up with 115the maintainers and we can help work around this. 116 117## Conditions for fulfilling a bounty: 118 1191. You should make a pull request which fixes the issue the bounty was promised for 1202. The pull request should be merged by one of the maintainers 121 122### Below are the steps to redeem a bounty: 123 1241. Go to https://opencollective.com/clap/expenses/new. 1252. Select **Invoice**. 1263. Enter **Expense Title** as "Issue Bounty". 1274. In **Description**, link the issue you are redeeming _(Ex: `https://github.com/clap-rs/clap/issues/1464`)_ 1285. In **Amount**, write the amount that the issue promised _(Ex: 10)_ 1296. Fill payment information and submit 1307. Wait for us to approve it 131 132### Can I forgo the bounty? 133 134Yes, you can. In that case, you don't have to do anything except writing a 135comment on the issue saying that I do. The bounty will be reassigned to another 136issue. 137 138## Specific Tasks 139 140### Section-specific CONTRIBUTING 141 142- [Example CONTRIBUTING](./examples/README.md#contributing) 143- [Tutorial (builder) CONTRIBUTING](./examples/tutorial_builder/README.md#contributing) 144- [Tutorial (derive) CONTRIBUTING](./examples/tutorial_derive/README.md#contributing) 145- [clap_derive CONTRIBUTING](./clap_derive/CONTRIBUTING.md) 146 147### Updating MSRV 148 149Search for `MSRV`, for example 150```bash 151$ rg --hidden MSRV 152``` 153And update all of the references 154