chore: add a lot more information in readme

.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 ]

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 code<sup>1</sup> |
+| `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)<sup>1</sup> |
+| `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 |
+
+<sup>1</sup> : 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).