[dependencies]
template-rs = "0.1"| Feature | Default | What it adds |
|---|---|---|
std |
yes | the standard library |
alloc |
no | the heap types, without the standard library |
With neither feature the crate is no_std and allocates nothing. The two are independent: std
does not imply alloc, and all four combinations are valid builds.
A crate skeleton, and the CI/CD that the author's crates run, ready to be renamed.
- The crate.
Cargo.tomlwith the feature tiers above,[lints], the docs.rs metadata and a criterion bench.src/lib.rsis the house crate root with one item in each tier, so that every tier builds and tests something; its unit tests live in a file of their own,src/tests.rs. The placeholderstests/foo.rs,examples/foo.rsandbenches/foo.rsare there to be replaced. - The merge gate.
ci.ymlruns on Linux only, so that its verdict arrives in tens of minutes. Every slower lane is a workflow of its own, and each can be paused alone. - The release. A tag
vX.Y.Zpublishes through crates.io trusted publishing, with no token stored anywhere, after checking that the commit is onmainand green. - Configuration.
rustfmt.toml;.codecov.yml, informational only, so coverage never blocks a merge;deny.toml, the cargo-deny policy;.github/dependabot.yml; and aCHANGELOG.mdwhose structureci/changelog.shchecks.
| Workflow | What it runs | Pause it |
|---|---|---|
ci.yml |
The merge gate, Linux only: rustfmt; clippy for each feature; build and test for every feature combination; a bare-metal no_std build; the MSRV; docs with -D warnings and the docs.rs configuration; cross builds for 15 targets; the address sanitizer; cargo publish --dry-run; the changelog structure |
No |
macos.yml, windows.yml |
clippy, build and test on those hosts | Yes: their runners queue for hours. The release asks for them |
miri-tb.yml, miri-sb.yml |
Miri under Tree Borrows and under Stacked Borrows, on six Linux targets | Yes: Miri is slow. The release asks for them |
perf.yml |
The criterion bench, run once as a smoke check | Yes |
coverage.yml |
cargo-llvm-cov, uploaded to codecov | Yes |
deny.yml |
cargo-deny against deny.toml: advisories, bans, licenses and sources, weekly as well |
Yes: it is never required, and the release does not ask for it |
release.yml |
The release, described below | No |
loc.yml |
The lines-of-code badge, written to a gist | Yes |
-
Create the repository from the template, with the "Use this template" button on GitHub, and clone it.
-
Rename it.
git grep -n 'template[-_]rs'lists every place the name appears:Cargo.toml:name,repository,homepage,documentation,description,keywordsandcategories;- the crate is called
template_rsintests/foo.rs,examples/foo.rsandbenches/foo.rs; - this README: the title, the badges and the links;
.github/workflows/loc.yml: the file name in the gist.
Also change the copyright holder in the two license files and below.
release.ymlrefuses to release a package that is still namedtemplate-rs. -
Choose what to keep. Each of these is one line to change:
editionandrust-versioninCargo.toml. The template is on edition 2024, which needsrust-version1.85 or later. Themsrvjob readsrust-version, so nothing else moves with it.REQUIRED_WORKFLOWSinrelease.yml: the workflows that must be green on the commit a release tags, which areci.yml, both Miri workflows,macos.ymlandwindows.yml. Drop the name of a lane the crate does not have.allowindeny.toml: the licenses the crate's dependencies may have. It lists the template's own and the one criterion's tree needs; add what your dependencies need.- Delete what the crate has no use for, together with its row in the table above. With no
benches that is
perf.yml,benches/, the[[bench]]entry and thecriteriondev-dependency. With no wish for Miri it ismiri-tb.yml,miri-sb.ymlandci/miri_*.sh, and their names inREQUIRED_WORKFLOWS. Without codecov it iscoverage.yml,.codecov.ymland the badge. Without cargo-deny it isdeny.ymlanddeny.toml.
-
Add the secrets, both optional.
CODECOV_TOKENletscoverage.ymlupload; without it the report is still measured and the job says that it was discarded.loc.ymlneeds a gist: create one, put its id in the workflow, and add a personal access token with the gist scope as the secretGIST_PAT. -
Set up crates.io, once. crates.io can configure a trusted publisher only for a crate that already exists, so the first version is published by hand:
- publish version
0.0.0withcargo login, thencargo publish. It reserves the name, andrelease.ymlrefuses0.0.0on purpose; - on crates.io, open the crate's settings, then Trusted Publishing, and add a GitHub
configuration: this repository, the workflow
release.yml, the environmentcrates-io; - the GitHub environment
crates-iois created on first use. To make a release wait for an approval, add required reviewers underSettings > Environments.
Until this is done, a release fails with a message that says which step is missing; it never skips the publish and reports success.
- publish version
-
Pause what you do not need while you work.
macos.yml,windows.yml,miri-tb.yml,miri-sb.yml, andperf.ymlandcoverage.ymlif you like.ci.ymlkeeps its verdict, which is the one a merge waits for. Pausing is a repository setting, so nothing in the repository changes when you do it:gh workflow disable macos.yml # pause gh workflow enable macos.yml # turn it back on gh workflow run macos.yml --ref main # run it on main, if main moved while it was off
Turn every lane back on before a release, and let it run on
main:release.ymlrequiresci.yml, both Miri workflows,macos.ymlandwindows.ymlto be green on the commit it releases, and a paused workflow has no run for that commit. -
Release. Set
versioninCargo.toml, rename theUnreleasedsection ofCHANGELOG.mdto## X.Y.Z (YYYY-MM-DD)and open a new one above it, and merge tomain. Then:gh workflow run release.yml # optional: check that main is releasable, before tagging git tag -a vX.Y.Z -m vX.Y.Z git push origin vX.Y.Zrelease.ymlchecks the commit, the version against the tag, the changelog and the workflows, publishes, and creates the GitHub Release from the changelog section. Run the optional first command after a lane was paused: it fails naming the required workflow that has no green run on the commit.
template-rs is under the terms of both the MIT license and the
Apache License (Version 2.0).
See LICENSE-APACHE, LICENSE-MIT for details.
Copyright (c) 2021 Al Liu.