Rust project template

This is a simple template repository for Rust projects that includes some default workflows and configuration files.

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
3. Run cargo init to create a Rust project at the repository root
   OR
   Run cargo new <project> from the repository root to create a new Rust project, then create a root Cargo.toml to setup a workspace
4. Adjust workflows as required
   • In particular, in order to have code coverage work, set up your project on codecov.io and create a CODECOV_TOKEN secret for your repository's actions
     • Also make sure you create a Dependabot secret for the token - see this warning
5. Adjust/add/remove status badges in this README
6. Adjust links in CONTRIBUTING.md, DEVELOPMENT.md, SECURITY.md and 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 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 (command runner, a make of sorts)
• cargo-tarpaulin (code coverage tool)
• cargo-hack (CI helper, used by other tools)
• cargo-minimal-versions (MSRV helper tool)
• cargo-msrv-prep (MSRV helper tool)
• cargo-msrv (tool to determine MSRV)

just

The template uses the 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 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

¹ : 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:

just toolchain=nightly test

There are other variables as well; check out the beginning of the justfile for details.

Workflows

The template includes some GitHub workflows to perform common CI/CD tasks.

File	Triggers on...	Purpose
audit-check.yml	push, schedule (every day)	Run security audits on the project's dependencies using cargo-audit
ci.yml	push	All CI-related tasks: linting, running tests, checking MSRV, etc.
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.

Renovate

The template includes a Renovate config file that can be used with the Renovate bot to check your project's dependencies for updates. By default, the config file points to a shared config preset, but you can change it for your needs if required (or delete the file if you don't use Renovate).

rustfmt

The template includes a rustfmt.toml file to configure the rustfmt tool. This tool is a Rust code formatter; it can be executed via

just fmt

or in combination with clippy via

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. The tool uses the 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

just tarpaulin

The ci.yml workflow also includes support for uploading coverage results to codecov.io. Coverage settings are controlled through the 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. (Also see this warning 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.

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

just msrv-minimal

This Rust version can then be configured in the CI workflow (see 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

just msrv

This Rust version can then be configured in the CI workflow (see 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

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 (bug report, feature request)
• Pull request template
• CODEOWNERS file (see About code owners on GitHub)
• Code of Conduct (uses the Contributor Covenant Code of Conduct)
• Contributing guidelines
• Development guide (for people who want to contribute to the project)
• License (MIT license)
• Security policy (including a list of versions that are still supported and for which updates might be released to fix vulnerabilities)
• .gitignore file (with some Rust-oriented ignores)
• .dockerignore skeleton file (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.