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
5Another 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 :)
6
7### Testing Code
8
9To test with all features both enabled and disabled, you can run these commands:
10
11```sh
12$ cargo test --no-default-features
13$ cargo test --features "yaml unstable"
14```
15
16Alternatively, if you have [`just`](https://github.com/casey/just) installed you can run the prebuilt recipes. *Not* using `just` is perfectly fine as well, it simply bundles commands automatically.
17
18For example, to test the code, as above simply run:
19
20```sh
21$ just run-tests
22```
23
24From here on, I will list the appropriate `cargo` command as well as the `just` command.
25
26Sometimes it's helpful to only run a subset of the tests, which can be done via:
27
28```sh
29$ cargo test --test <test_name>
30
31# Or
32
33$ just run-test <test_name>
34```
35
36### Linting Code
37
38During the CI process `clap` runs against many different lints using [`clippy`](https://github.com/rust-lang-nursery/rust-clippy). In order to check if these lints pass on your own computer prior to submitting a PR you'll need a nightly compiler.
39
40In order to check the code for lints run either:
41
42```sh
43$ rustup override add nightly
44$ cargo build --features lints
45$ rustup override remove
46
47# Or
48
49$ just lint
50```
51
52### Debugging Code
53
54Another 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:
55
56```sh
57$ cargo test --features debug
58
59# Or for individual tests
60$ cargo test --test <test_name> --features debug
61
62# The corresponding just command for individual debugging tests is:
63$ just debug <test_name>
64```
65
66### Commit Messages
67
68I use a [conventional](https://github.com/ajoslin/conventional-changelog/blob/a5505865ff3dd710cf757f50530e73ef0ca641da/conventions/angular.md) changelog format so I can update my changelog automatically using [clog](https://github.com/clog-tool/clog-cli)
69
70 * Please format your commit subject line using the following format: `TYPE(COMPONENT): MESSAGE` where `TYPE` is one of the following:
71    - `api`  - An addition to the API
72    - `setting` - A new `AppSettings` variant
73    - `feat` - A new feature of an existing API
74    - `imp`  - An improvement to an existing feature/API
75    - `perf` - A performance improvement
76    - `docs` - Changes to documentation only
77    - `tests` - Changes to the testing framework or tests only
78    - `fix` - A bug fix
79    - `refactor` - Code functionality doesn't change, but underlying structure may
80    - `style` - Stylistic changes only, no functionality changes
81    - `wip` - A work in progress commit (Should typically be `git rebase`'ed away)
82    - `chore` - Catch all or things that have to do with the build system, etc
83    - `examples` - Changes to existing example, or a new example
84 * The `COMPONENT` is optional, and may be a single file, directory, or logical component. Parenthesis can be omitted if you are opting not to use the `COMPONENT`.
85
86### Tests and Documentation
87
881. Create tests for your changes
892. **Ensure the tests are passing.** Run the tests (`cargo test --features "yaml unstable"`), alternatively `just run-tests` if you have `just` installed.
903. **Optional** Run the lints (`cargo build --features lints`) (requires a nightly compiler), alternatively `just lint`
914. Ensure your changes contain documentation if adding new APIs or features.
92
93### Preparing the PR
94
951. `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)
962. Push your changes back to your fork (`git push origin $your-branch`)
973. 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.)
98
99### Other ways to contribute
100
101Another 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 :)
102
103### Goals
104
105There 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).
106
107* Remain backwards compatible when possible
108  - If backwards compatibility *must* be broken, use deprecation warnings if at all possible before removing legacy code
109  - This does not apply for security concerns
110* Parse arguments quickly
111  - Parsing of arguments shouldn't slow down usage of the main program
112  - This is also true of generating help and usage information (although *slightly* less stringent, as the program is about to exit)
113* Try to be cognizant of memory usage
114  - Once parsing is complete, the memory footprint of `clap` should be low since the  main program is the star of the show
115* `panic!` on *developer* error, exit gracefully on *end-user* error
116