aboutsummaryrefslogtreecommitdiff
path: root/clap/.github/CONTRIBUTING.md
diff options
context:
space:
mode:
authorRobin Krahl <robin.krahl@ireas.org>2020-01-07 11:18:04 +0000
committerDaniel Mueller <deso@posteo.net>2020-01-08 09:20:25 -0800
commit5e20a29b4fdc8a2d442d1093681b396dcb4b816b (patch)
tree55ab083fa8999d2ccbb5e921c1ffe52560dca152 /clap/.github/CONTRIBUTING.md
parent203e691f46d591a2cc8acdfd850fa9f5b0fb8a98 (diff)
downloadnitrocli-5e20a29b4fdc8a2d442d1093681b396dcb4b816b.tar.gz
nitrocli-5e20a29b4fdc8a2d442d1093681b396dcb4b816b.tar.bz2
Add structopt dependency in version 0.3.7
This patch series replaces argparse with structopt in the argument handling code. As a first step, we need structopt as a dependency. Import subrepo structopt/:structopt at efbdda4753592e27bc430fb01f7b9650b2f3174d Import subrepo bitflags/:bitflags at 30668016aca6bd3b02c766e8347e0b4080d4c296 Import subrepo clap/:clap at 784524f7eb193e35f81082cc69454c8c21b948f7 Import subrepo heck/:heck at 093d56fbf001e1506e56dbfa38631d99b1066df1 Import subrepo proc-macro-error/:proc-macro-error at 6c4cfe79a622c5de8ae68557993542be46eacae2 Import subrepo proc-macro2/:proc-macro2 at d5d48eddca4566e5438e8a2cbed4a74e049544de Import subrepo quote/:quote at 727436c6c137b20f0f34dde5d8fda2679b9747ad Import subrepo rustversion/:rustversion at 0c5663313516263059ce9059ef81fc7a1cf655ca Import subrepo syn-mid/:syn-mid at 5d3d85414a9e6674e1857ec22a87b96e04a6851a Import subrepo syn/:syn at e87c27e87f6f4ef8919d0372bdb056d53ef0d8f3 Import subrepo textwrap/:textwrap at abcd618beae3f74841032aa5b53c1086b0a57ca2 Import subrepo unicode-segmentation/:unicode-segmentation at 637c9874c4fe0c205ff27787faf150a40295c6c3 Import subrepo unicode-width/:unicode-width at 3033826f8bf05e82724140a981d5941e48fce393 Import subrepo unicode-xid/:unicode-xid at 4baae9fffb156ba229665b972a9cd5991787ceb7
Diffstat (limited to 'clap/.github/CONTRIBUTING.md')
-rw-r--r--clap/.github/CONTRIBUTING.md115
1 files changed, 115 insertions, 0 deletions
diff --git a/clap/.github/CONTRIBUTING.md b/clap/.github/CONTRIBUTING.md
new file mode 100644
index 0000000..2c6f752
--- /dev/null
+++ b/clap/.github/CONTRIBUTING.md
@@ -0,0 +1,115 @@
+# 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 :)
+
+### Testing Code
+
+To test with all features both enabled and disabled, you can run these commands:
+
+```sh
+$ cargo test --no-default-features
+$ cargo test --features "yaml unstable"
+```
+
+Alternatively, 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.
+
+For example, to test the code, as above simply run:
+
+```sh
+$ just run-tests
+```
+
+From here on, I will list the appropriate `cargo` command as well as the `just` command.
+
+Sometimes it's helpful to only run a subset of the tests, which can be done via:
+
+```sh
+$ cargo test --test <test_name>
+
+# Or
+
+$ just run-test <test_name>
+```
+
+### Linting Code
+
+During 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.
+
+In order to check the code for lints run either:
+
+```sh
+$ rustup override add nightly
+$ cargo build --features lints
+$ rustup override remove
+
+# Or
+
+$ just lint
+```
+
+### 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
+
+# The corresponding just command for individual debugging tests is:
+$ just debug <test_name>
+```
+
+### Commit Messages
+
+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)
+
+ * Please format your commit subject line using the following format: `TYPE(COMPONENT): MESSAGE` where `TYPE` is one of the following:
+ - `api` - An addition to the API
+ - `setting` - A new `AppSettings` variant
+ - `feat` - A new feature of an existing API
+ - `imp` - An improvement to an existing feature/API
+ - `perf` - A performance improvement
+ - `docs` - Changes to documentation only
+ - `tests` - Changes to the testing framework or tests only
+ - `fix` - A bug fix
+ - `refactor` - Code functionality doesn't change, but underlying structure may
+ - `style` - Stylistic changes only, no functionality changes
+ - `wip` - A work in progress commit (Should typically be `git rebase`'ed away)
+ - `chore` - Catch all or things that have to do with the build system, etc
+ - `examples` - Changes to existing example, or a new example
+ * 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`.
+
+### Tests and Documentation
+
+1. Create tests for your changes
+2. **Ensure the tests are passing.** Run the tests (`cargo test --features "yaml unstable"`), alternatively `just run-tests` if you have `just` installed.
+3. **Optional** Run the lints (`cargo build --features lints`) (requires a nightly compiler), alternatively `just lint`
+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.)
+
+### Other ways to contribute
+
+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, exit gracefully on *end-user* error