Skip to content

Commit 83be1e6

Browse files
clechasseurclechasseur
committed
chore: add a lot more information in readme
1 parent 4de67ed commit 83be1e6

File tree

2 files changed

+160
-2
lines changed

2 files changed

+160
-2
lines changed

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ on:
99
jobs:
1010
build-release-files:
1111
name: Build release files for ${{ matrix.arch }}-${{ matrix.platform }} with Rust ${{ matrix.toolchain }}
12-
if: github.repository_owner == 'clechasseur' # Don't build on forks # TODO replace with your GitHub username
12+
if: github.repository_owner == 'clechasseur' # Don't build on forks
1313
strategy:
1414
matrix:
1515
toolchain: [ stable ]

‎README.md‎

Lines changed: 159 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

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

7-
## Usage
7+
## TL;DR
88

99
1. Create a new repository using this template (_Note_: do not include all branches, unless you want to end up with the test branch)
1010
2. Clone your new repository
@@ -18,3 +18,161 @@ This is a simple template repository for Rust projects that includes some defaul
1818
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)
1919
7. ???
2020
8. Profit!
21+
22+
## More info
23+
24+
This template is of course opinionated, but the following sections present how it is meant to be used.
25+
(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.)
26+
27+
### Required tools
28+
29+
In addition to a stable Rust toolchain, the template uses the following tools:
30+
31+
* A Nightly Rust toolchain
32+
* [`just`](https://github.com/casey/just) (command runner, a `make` of sorts)
33+
* [`cargo-tarpaulin`](https://github.com/xd009642/tarpaulin) (code coverage tool)
34+
* [`cargo-hack`](https://github.com/taiki-e/cargo-hack) (CI helper, used by other tools)
35+
* [`cargo-minimal-versions`](https://github.com/taiki-e/cargo-minimal-versions) (MSRV helper tool)
36+
* [`cargo-msrv-prep`](https://github.com/clechasseur/msrv-prep) (MSRV helper tool)
37+
* [`cargo-msrv`](https://github.com/foresterre/cargo-msrv) (tool to determine MSRV)
38+
39+
### `just`
40+
41+
The template uses the [`just`](https://github.com/casey/just) command runner to define some build commands.
42+
This makes it easier to run common commands without having to remember any project-specific flags that might need to be passed.
43+
`just` commands are stored in a [`justfile`](./justfile) and are called _recipes_.
44+
45+
Running `just` without argument will print the list of available recipes.
46+
The following table lists the most interesting ones.
47+
48+
| Command | Purpose |
49+
|---------|---------|
50+
| `just tidy` | Run `clippy` and `rustfmt` on the project's code<sup>1</sup> |
51+
| `just check` | Run `cargo check` on all workspace projects |
52+
| `just build` | Run `cargo build` on all workspace projects |
53+
| `just test` | Run `cargo test` for all tests in workspace |
54+
| `just tarpaulin` | Run `cargo tarpaulin` to execute tests with code coverage (see below) |
55+
| `just update` | Run `cargo update` |
56+
| `just doc` | Generate documentation with `rustdoc`; when run locally, opens the resulting doc when done (with `--open`) |
57+
| `just doc-coverage` | Produce a doc coverage report (an experimental `rustdoc` feature)<sup>1</sup> |
58+
| `just msrv` | Determine the entire project's MSRV using `cargo-msrv` (see below) |
59+
| `just msrv-minimal` | Determine the MSRV of `lib` and `bin` crates only using `cargo-msrv` (see below) |
60+
| `just check-minimal` | Validate the minimal MSRV determined with `just msrv-minimal` (see below) |
61+
| `just test-package` | Run `cargo publish --dry-run` to test package publication |
62+
63+
<sup>1</sup> : these commands use Nightly Rust.
64+
65+
The `justfile` also uses variables to determine what to run and what arguments to pass.
66+
These can be overridden when calling `just`, however.
67+
For example, you can override `toolchain` to run a command with another Rust toolchain:
68+
69+
```sh
70+
just toolchain=nightly test
71+
```
72+
73+
There are other variables as well; check out the beginning of the [`justfile`](./justfile) for details.
74+
75+
### Workflows
76+
77+
The template includes some GitHub workflows to perform common CI/CD tasks.
78+
79+
| File | Triggers on... | Purpose |
80+
|------|----------------|---------|
81+
| [`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/) |
82+
| [`ci.yml`](./.github/workflows/ci.yml) | `push` | All CI-related tasks: linting, running tests, checking MSRV, etc. |
83+
| [`release.yml`](./.github/workflows/release.yml) | `release` (`created` only) | Build release binaries and attach them to a GitHub release |
84+
85+
By default, workflows are disabled (except for manual triggering).
86+
To enable them, edit the corresponding file to uncomment the appropriate event at the top of the file.
87+
There are also places where you will need to edit the files depending on your project's Rust version, etc.
88+
89+
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.
90+
91+
### Dependabot
92+
93+
The template includes a [Dependabot config file](./.github/dependabot.yml) that instructs Dependabot to check your project's dependencies for updates.
94+
By default, Rust dependencies will be checked daily and GitHub actions will be checked weekly.
95+
You can modify the file to adapt it to your needs (or delete it if you don't use Dependabot).
96+
97+
### `build.rs`
98+
99+
The template include a Rust build script (see the [`build.rs`](./build.rs) file).
100+
This script will be compiled and executed before your crate's code is built and allows you to set some arguments or configuration values.
101+
For more details, see the appropriate [Cargo book section](https://doc.rust-lang.org/cargo/reference/build-scripts.html).
102+
103+
If you do not need a build script, you can simply delete the file.
104+
105+
### `rustfmt`
106+
107+
The template includes a [`rustfmt.toml`](./rustfmt.toml) file to configure the `rustfmt` tool.
108+
This tool is a Rust code formatter; it can be executed via
109+
110+
```sh
111+
just fmt
112+
```
113+
114+
or in combination with `clippy` via
115+
116+
```sh
117+
just tidy
118+
```
119+
120+
The file contains configuration values that deviate from the defaults, but they require the use of a Nightly Rust toolchain to use them.
121+
If you do not use `rustfmt`, you can simply delete the config file.
122+
123+
### Code coverage
124+
125+
The template includes support for running tests with coverage using [`cargo-tarpaulin`](https://github.com/xd009642/tarpaulin).
126+
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.
127+
It's possible to run tests with coverage locally using
128+
129+
```sh
130+
just tarpaulin
131+
```
132+
133+
The [`ci.yml`](./.github/workflows/ci.yml) workflow also includes support for uploading coverage results to [codecov.io](https://codecov.io/).
134+
Coverage settings are controlled through the [`codecov.yml`](./codecov.yml) file (the coverage target, for example).
135+
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).
136+
(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.)
137+
138+
### MSRV
139+
140+
MSRV stands for _Minimum Supported Rust Version_.
141+
Lots of crates advertise their MSRV so that users can determine whether they can use the dependency in their own projects.
142+
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).
143+
144+
The template includes support for determining and validating the project's MSRV.
145+
146+
#### Determining the MSRV for crate users
147+
148+
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.
149+
If you installed all required tools, this can be determined by running
150+
151+
```sh
152+
just msrv-minimal
153+
```
154+
155+
This Rust version can then be configured in the CI workflow (see [`ci.yml`](./.github/workflows/ci.yml)'s `msrv-check` job).
156+
157+
#### Determining the MSRV for the project iself
158+
159+
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
160+
161+
```sh
162+
just msrv
163+
```
164+
165+
This Rust version can then be configured in the CI workflow (see [`ci.yml`](./.github/workflows/ci.yml)'s `build` job).
166+
167+
#### Validating the MSRV locally
168+
169+
To validate the project's MSRV locally, you can use the `check-minimal` recipe.
170+
Assuming your project's MSRV is Rust 1.63.0, run
171+
172+
```sh
173+
just toolchain=1.63.0 check-minimal
174+
```
175+
176+
## Questions? Comments?
177+
178+
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).

0 commit comments

Comments
 (0)