From a9ae8dc95fe088806958e7a8fd565bf575c6ccd8 Mon Sep 17 00:00:00 2001 From: Charles Lechasseur Date: Sat, 9 Mar 2024 20:58:33 -0500 Subject: [PATCH] chore: add a lot more information in readme --- .github/workflows/release.yml | 2 +- README.md | 177 +++++++++++++++++++++++++++++++++- 2 files changed, 177 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4c2c0eb..6c232ba 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -9,7 +9,7 @@ on: jobs: build-release-files: name: Build release files for ${{ matrix.arch }}-${{ matrix.platform }} with Rust ${{ matrix.toolchain }} - if: github.repository_owner == 'clechasseur' # Don't build on forks # TODO replace with your GitHub username + if: github.repository_owner == 'clechasseur' # Don't build on forks strategy: matrix: toolchain: [ stable ] diff --git a/README.md b/README.md index de9c2db..2870a07 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This is a simple template repository for Rust projects that includes some default workflows and configuration files. -## Usage +## TL;DR 1. Create a new repository using this template (_Note_: do not include all branches, unless you want to end up with the test branch) 2. Clone your new repository @@ -18,3 +18,178 @@ This is a simple template repository for Rust projects that includes some defaul 6. Adjust links in [CONTRIBUTING.md](./CONTRIBUTING.md), [DEVELOPMENT.md](./DEVELOPMENT.md), [SECURITY.md](./SECURITY.md) and [PULL_REQUEST_TEMPLATE.md](./.github/PULL_REQUEST_TEMPLATE.md) 7. ??? 8. Profit! + +## More info + +This template is of course opinionated, but the following sections present how it is meant to be used. +(This documentation assumes that you are familiar with Rust development; if not, you can refer to the [Cargo book](https://doc.rust-lang.org/cargo/) for more information on how to setup and manage Rust projects.) + +### Required tools + +In addition to a stable Rust toolchain, the template uses the following tools: + +* A Nightly Rust toolchain +* [`just`](https://github.com/casey/just) (command runner, a `make` of sorts) +* [`cargo-tarpaulin`](https://github.com/xd009642/tarpaulin) (code coverage tool) +* [`cargo-hack`](https://github.com/taiki-e/cargo-hack) (CI helper, used by other tools) +* [`cargo-minimal-versions`](https://github.com/taiki-e/cargo-minimal-versions) (MSRV helper tool) +* [`cargo-msrv-prep`](https://github.com/clechasseur/msrv-prep) (MSRV helper tool) +* [`cargo-msrv`](https://github.com/foresterre/cargo-msrv) (tool to determine MSRV) + +### `just` + +The template uses the [`just`](https://github.com/casey/just) command runner to define some build commands. +This makes it easier to run common commands without having to remember any project-specific flags that might need to be passed. +`just` commands are stored in a [`justfile`](./justfile) and are called _recipes_. + +Running `just` without argument will print the list of available recipes. +The following table lists the most interesting ones. + +| Command | Purpose | +|---------|---------| +| `just tidy` | Run `clippy` and `rustfmt` on the project's code1 | +| `just check` | Run `cargo check` on all workspace projects | +| `just build` | Run `cargo build` on all workspace projects | +| `just test` | Run `cargo test` for all tests in workspace | +| `just tarpaulin` | Run `cargo tarpaulin` to execute tests with code coverage (see below) | +| `just update` | Run `cargo update` | +| `just doc` | Generate documentation with `rustdoc`; when run locally, opens the resulting doc when done (with `--open`) | +| `just doc-coverage` | Produce a doc coverage report (an experimental `rustdoc` feature)1 | +| `just msrv` | Determine the entire project's MSRV using `cargo-msrv` (see below) | +| `just msrv-minimal` | Determine the MSRV of `lib` and `bin` crates only using `cargo-msrv` (see below) | +| `just check-minimal` | Validate the minimal MSRV determined with `just msrv-minimal` (see below) | +| `just test-package` | Run `cargo publish --dry-run` to test package publication | + +1 : these commands use Nightly Rust. + +The `justfile` also uses variables to determine what to run and what arguments to pass. +These can be overridden when calling `just`, however. +For example, you can override `toolchain` to run a command with another Rust toolchain: + +```sh +just toolchain=nightly test +``` + +There are other variables as well; check out the beginning of the [`justfile`](./justfile) for details. + +### Workflows + +The template includes some GitHub workflows to perform common CI/CD tasks. + +| File | Triggers on... | Purpose | +|------|----------------|---------| +| [`audit-check.yml`](./.github/workflows/audit-check.yml) | `push`, `schedule` (every day) | Run security audits on the project's dependencies using [`cargo-audit`](https://rustsec.org/) | +| [`ci.yml`](./.github/workflows/ci.yml) | `push` | All CI-related tasks: linting, running tests, checking MSRV, etc. | +| [`release.yml`](./.github/workflows/release.yml) | `release` (`created` only) | Build release binaries and attach them to a GitHub release | + +By default, workflows are disabled (except for manual triggering). +To enable them, edit the corresponding file to uncomment the appropriate event at the top of the file. +There are also places where you will need to edit the files depending on your project's Rust version, etc. + +If you don't need one of the workflow (such as `release.yml` if your project does not publish binaries), you can simply delete the file. + +### Dependabot + +The template includes a [Dependabot config file](./.github/dependabot.yml) that instructs Dependabot to check your project's dependencies for updates. +By default, Rust dependencies will be checked daily and GitHub actions will be checked weekly. +You can modify the file to adapt it to your needs (or delete it if you don't use Dependabot). + +### `build.rs` + +The template include a Rust build script (see the [`build.rs`](./build.rs) file). +This script will be compiled and executed before your crate's code is built and allows you to set some arguments or configuration values. +For more details, see the appropriate [Cargo book section](https://doc.rust-lang.org/cargo/reference/build-scripts.html). + +If you do not need a build script, you can simply delete the file. + +### `rustfmt` + +The template includes a [`rustfmt.toml`](./rustfmt.toml) file to configure the `rustfmt` tool. +This tool is a Rust code formatter; it can be executed via + +```sh +just fmt +``` + +or in combination with `clippy` via + +```sh +just tidy +``` + +The file contains configuration values that deviate from the defaults, but they require the use of a Nightly Rust toolchain to use them. +If you do not use `rustfmt`, you can simply delete the config file. + +### Code coverage + +The template includes support for running tests with coverage using [`cargo-tarpaulin`](https://github.com/xd009642/tarpaulin). +The tool uses the [`tarpaulin.toml`](./tarpaulin.toml) file to read configuration values; you can edit the file to adapt it to your needs as required. +It's possible to run tests with coverage locally using + +```sh +just tarpaulin +``` + +The [`ci.yml`](./.github/workflows/ci.yml) workflow also includes support for uploading coverage results to [codecov.io](https://codecov.io/). +Coverage settings are controlled through the [`codecov.yml`](./codecov.yml) file (the coverage target, for example). +In order to use this, you will need to link Codecov with your GitHub account; for more information, see Codecov's [GitHub tutorial](https://docs.codecov.com/docs/github-tutorial). +(Also see [this warning](https://github.com/codecov/codecov-action?tab=readme-ov-file#dependabot) in order to allow proper coverage checks in Dependabot-created PRs.) + +### MSRV + +MSRV stands for _Minimum Supported Rust Version_. +Lots of crates advertise their MSRV so that users can determine whether they can use the dependency in their own projects. +It's also possible to specify the project's MSRV in your `Cargo.toml` file through the [`rust-version` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field). + +The template includes support for determining and validating the project's MSRV. + +#### Determining the MSRV for crate users + +In order to determine the minimal Rust version needed to build your crate from a user perspective, you need to check `lib` and `bin` crates only. +If you installed all required tools, this can be determined by running + +```sh +just msrv-minimal +``` + +This Rust version can then be configured in the CI workflow (see [`ci.yml`](./.github/workflows/ci.yml)'s `msrv-check` job). + +#### Determining the MSRV for the project iself + +In order to determine the minimal Rust version that can be used to build the project _itself_ (including any tests, examples, etc.), you can use + +```sh +just msrv +``` + +This Rust version can then be configured in the CI workflow (see [`ci.yml`](./.github/workflows/ci.yml)'s `build` job). + +#### Validating the MSRV locally + +To validate the project's MSRV locally, you can use the `check-minimal` recipe. +Assuming your project's MSRV is Rust 1.63.0, run + +```sh +just toolchain=1.63.0 check-minimal +``` + +### Other stuff + +The template comes with a few more files to set you up for publishing an open-source Rust project, including: + +* [Issue templates](./.github/ISSUE_TEMPLATE) ([bug report](./.github/ISSUE_TEMPLATE/bug_report.md), [feature request](./.github/ISSUE_TEMPLATE/feature_request.md)) +* [Pull request template](./.github/PULL_REQUEST_TEMPLATE.md) +* [`CODEOWNERS` file](./.github/CODEOWNERS) (see [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) on GitHub) +* [Code of Conduct](./CODE_OF_CONDUCT.md) (uses the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/)) +* [Contributing guidelines](./CONTRIBUTING.md) +* [Development guide](./DEVELOPMENT.md) (for people who want to contribute to the project) +* [License](./LICENSE) (MIT license) +* [Security policy](./SECURITY.md) (including a list of versions that are still supported and for which updates might be released to fix vulnerabilities) +* [`.gitignore` file](./.gitignore) (with some Rust-oriented ignores) +* [`.dockerignore` skeleton file](./.dockerignore) (in case you need to build Docker files for your project) + +You can remove any file you do not need; those that you keep might need to be adapted, especially those containing project links. + +## Questions? Comments? + +If you notice a problem in the template or would like to suggest an improvement, you can create an [issue](https://github.com/clechasseur/rust-template/issues/new).