From baef1a06b0dda4cd381b25ce64ac5db0e9071b0c Mon Sep 17 00:00:00 2001 From: Robin Krahl Date: Mon, 20 Jul 2020 10:23:28 +0200 Subject: [PATCH] Extend contributing guide This patch extends the CONTRIBUTING.md file with more information on possible tasks, the test suite and the code checks. --- CONTRIBUTING.md | 55 +++++++++++++++++++++++++++++++++++++++++-------- README.md | 10 +++++---- 2 files changed, 52 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c36ae12..93d0fea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,21 +14,58 @@ services: - [lists.sr.ht/~ireas/rusty-man-dev][ml]: mailing list - [builds.sr.ht/~ireas/rusty-man][ci]: build server for continuous integration +## How to contribute + +### Writing code + +Have a look at the [issues][todo] in rusty-man’s issue tracker, especially +those with the label [good first issue][], to find an issue to work on. + +### Writing documentation + +You can help by proofreading and extending the documentation in the readme file +and the contributing and installation guides. Also, rusty-man is lacking a man +page and a usage guide – contributions are welcome! + +### Testing + +If you are using rusty-man and are encountering any issues, please let me know. +I’m especially interested in reports from other operating systems than Linux. +You can also help by writing unit tests, especially for the HTML documentation +parser. + ## Submitting patches -There are two ways to submit patches for rusty-man: +Please submit patches by sending a mail to the mailing list +[~ireas/rusty-man-dev@lists.sr.ht][list]. There are three ways to do that: + +1. Use [`git send-email`][] to send your patches. If you are not familiar with + the `git send-email` workflow, have a look at [this step-by-step + guide][guide] or [contact me][] for more information. +2. Or push your changes to a public repository, for example hosted on your own + Git server, sourcehut.org, Gitlab or GitHub, and use [`git request-pull`][] + to send a pull request to the mailing list. +3. If options one and two don’t work for you, just use your mail client to send + a mail with a link to your changes and a short description to the mailing + list. + +## Testing and checking the code -1. Use `git send-email` to send your patches to the mailing list - [~ireas/rusty-man-dev@lists.sr.ht][list]. If you are not familiar with the - `git send-email` workflow, have a look at [this step-by-step - guide](https://git-send-email.io) and feel free to [contact - me](mailto:robin.krahl@ireas.org) for more information. -2. Push your changes to a public repository, for example hosted on your own Git - server, sourcehut.org, Gitlab or GitHub, and use `git request-pull` to send - a pull request to the mailing list [~ireas/rusty-man-dev@lists.sr.ht][list]. +- rusty-man currently has a very small test suite. You can execute it using + `cargo test`, but make sure to generate rusty-man’s documentation with `cargo + doc` before running the tests! +- Use `cargo fmt` for code formatting. +- Fix all warnings and errors reported by `clippy`. [git]: https://git.sr.ht/~ireas/rusty-man [todo]: https://todo.sr.ht/~ireas/rusty-man [ml]: https://lists.sr.ht/~ireas/rusty-man-dev [ci]: https://builds.sr.ht/~ireas/rusty-man + +[good first issue]: https://todo.sr.ht/~ireas/rusty-man?search=label:%22good%20first%20issue%22%20status%3Aopen + [list]: mailto:~ireas/rusty-man-dev@lists.sr.ht +[`git send-email`]: https://git-scm.com/docs/git-send-email +[`git request-pull`]: https://git-scm.com/docs/git-request-pull +[guide]: https://git-send-email.io +[contact me]: mailto:robin.krahl@ireas.org diff --git a/README.md b/README.md index e9036e2..9e06ba2 100644 --- a/README.md +++ b/README.md @@ -53,8 +53,8 @@ rusty-man to other platforms, please let me know. ## Contributing Contributions to this project are very welcome! You can contribute by writing -code or documentation or by testing. See the -[`CONTRIBUTING.md`](./CONTRIBUTING.md) file for more information. +code or documentation or by testing. See the [`CONTRIBUTING.md`][] file for +more information. If you are looking for a good starting point, have a look at the [issues with the label “good first issue”][issues] in rusty-man’s issue tracker. @@ -67,8 +67,8 @@ This crate supports Rust 1.40 or later. For bug reports, patches, feature requests or other messages, please send a mail to the mailing list [~ireas/rusty-man-dev@lists.sr.ht][] ([public -archive][]). You can also use the rusty-man [issue tracker][] for bug reports -or features requests. +archive][]) or [contact me directly][]. You can also use the rusty-man [issue +tracker][] for bug reports or features requests. ## License @@ -77,8 +77,10 @@ This project is licensed under the [MIT License][]. `rusty-man` complies with [version 3.0 of the REUSE specification][reuse]. [`termion`]: https://lib.rs/termion +[`CONTRIBUTING.md`]: ./CONTRIBUTING.md [issues]: https://todo.sr.ht/~ireas/rusty-man?search=label:%22good%20first%20issue%22%20status%3Aopen [~ireas/rusty-man-dev@lists.sr.ht]: mailto:~ireas/rusty-man-dev@lists.sr.ht +[contact me directly]: mailto:robin.krahl@ireas.org [public archive]: https://lists.sr.ht/~ireas/rusty-man-dev [issue tracker]: https://todo.sr.ht/~ireas/rusty-man [MIT license]: https://opensource.org/licenses/MIT