src/vendor/clap/.github/CONTRIBUTING.md

   1 # How to Contribute
   2
   3 Contributions are always welcome! Please use the following guidelines when contributing to `clap`
   4
   5 ## Goals
   6
   7 There are a few goals of `clap` that I'd like to maintain throughout contributions.
   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   - `clap` officially supports the current stable version of Rust, minus two releases (i.e. if 1.13.0 is current, `clap` must support 1.11.0 and beyond)
  13 * Parse arguments quickly
  14   - Parsing of arguments shouldn't slow down usage of the main program
  15   - This is also true of generating help and usage information (although *slightly* less stringent, as the program is about to exit)
  16 * Try to be cognizant of memory usage
  17   - Once parsing is complete, the memory footprint of `clap` should be low since the  main program is the star of the show
  18 * `panic!` on *developer* error, exit gracefully on *end-user* error
  19
  20 ### Commit Messages
  21
  22 I 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)
  23
  24  * Please format your commit subject line using the following format: `TYPE(COMPONENT): MESSAGE` where `TYPE` is one of the following:
  25     - `api`  - An addition to the API
  26     - `setting` - A new `AppSettings` variant
  27     - `feat` - A new feature of an existing API
  28     - `imp`  - An improvement to an existing feature/API
  29     - `perf` - A performance improvement
  30     - `docs` - Changes to documentation only
  31     - `tests` - Changes to the testing framework or tests only
  32     - `fix` - A bug fix
  33     - `refactor` - Code functionality doesn't change, but underlying structure may
  34     - `style` - Stylistic changes only, no functionality changes
  35     - `wip` - A work in progress commit (Should typically be `git rebase`'ed away)
  36     - `chore` - Catch all or things that have to do with the build system, etc
  37     - `examples` - Changes to existing example, or a new example
  38  * 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`.
  39
  40 ### Tests and Documentation
  41
  42 1. Create tests for your changes
  43 2. **Ensure the tests are passing.** Run the tests (`cargo test --features "yaml unstable"`), alternatively `just run-tests` if you have `just` installed.
  44 3. **Optional** Run the lints (`cargo build --features lints`) (requires a nightly compiler), alternatively `just lint`
  45 4. Ensure your changes contain documentation if adding new APIs or features.
  46
  47 ### Preparing the PR
  48
  49 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)
  50 2. Push your changes back to your fork (`git push origin $your-branch`)
  51 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.)
  52
  53 ### Other ways to contribute
  54
  55 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 :)
  56