From 6f76bd0a07e8b7419b391243ab2d6687cd8a9c5f Mon Sep 17 00:00:00 2001 From: Kevin K Date: Fri, 29 May 2015 13:13:17 -0400 Subject: [PATCH] docs: adds contributing guidelines --- CONTRIBUTING.md | 39 +++++++++++++++++++++++++++++++++++++++ README.md | 24 +++++++++++++++++++----- 2 files changed, 58 insertions(+), 5 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..f29ea1db7a2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# How to Contribute + +Contributions are always welcome! Please use the following guidelines when contributing to `clap` + +1. Fork `clap` +2. Clone your fork (`git clone https://github.com/$YOUR_USERNAME/clap-rs && cd clap-rs`) +3. Create new branch (`git checkout -b new-branch`) +4. Make your changes, and commit (`git commit -am "your message"`) + * I use a [conventional](https://github.com/ajoslin/conventional-changelog/blob/master/CONVENTIONS.md) changelog format so I can update my changelog using [clog](https://github.com/thoughtram/clog) + * Format your commit subject line using the following format: `TYPE(COMPONENT): MESSAGE` where `TYPE` is one of the following: + - `feat` - A new feature + - `imp` - An improvement to an existing feature + - `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 + * The `COMPONENT` is optional, and may be a single file, directory, or logical component. Can be omitted if commit applies globally +5. Run the tests (`cargo test && make -C clap-tests test`) +6. `git rebase` into concise commits and remove `--fixup`s (`git rebase -i HEAD~NUM` where `NUM` is number of commits back) +7. Push your changes back to your fork (`git push origin $your-branch`) +8. Create a pull request! (You can also create the pull request first, and we'll merge when ready. This a good way to discuss proposed changes.) + +## Goals + +There are a few goals of `clap` that I'd like to maintain throughout contributions. + +* 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 diff --git a/README.md b/README.md index e4861a86207..1d03edde898 100644 --- a/README.md +++ b/README.md @@ -315,13 +315,27 @@ There's also the video tutorial series [Argument Parsing with Rust](https://www. 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! -1. Fork the project +1. Fork `clap` 2. Clone your fork (`git clone https://github.com/$YOUR_USERNAME/clap-rs && cd clap-rs`) 3. Create new branch (`git checkout -b new-branch`) -4. Make your changes, and commit (`git commit -am "your message"`) (I use a [conventional](https://github.com/ajoslin/conventional-changelog/blob/master/CONVENTIONS.md) changelog format so I can update my changelog using [clog](https://github.com/thoughtram/clog)) -5. If applicable, run the tests (See below) -6. Push your changes back to your fork (`git push origin your-branch`) -7. Create a pull request! (You can also create the pull request right away, and we'll merge when ready. This a good way to discuss proposed changes.) +4. Make your changes, and commit (`git commit -am "your message"`) + * I use a [conventional](https://github.com/ajoslin/conventional-changelog/blob/master/CONVENTIONS.md) changelog format so I can update my changelog using [clog](https://github.com/thoughtram/clog) + * Format your commit subject line using the following format: `TYPE(COMPONENT): MESSAGE` where `TYPE` is one of the following: + - `feat` - A new feature + - `imp` - An improvement to an existing feature + - `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 + * The `COMPONENT` is optional, and may be a single file, directory, or logical component. Can be omitted if commit applies globally +5. Run the tests (`cargo test && make -C clap-tests test`) +6. `git rebase` into concise commits and remove `--fixup`s (`git rebase -i HEAD~NUM` where `NUM` is number of commits back) +7. Push your changes back to your fork (`git push origin $your-branch`) +8. Create a pull request! (You can also create the pull request first, and we'll merge when ready. This a good way to discuss proposed changes.) 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/` directory, or file an issue and tell me. I'm all about giving credit where credit is due :)