cargo-generate templates in one repository:
a Typst package, a Python project and a Rust crate, each with its toolchain wired up, its checks
run locally as CI runs them, a Nix flake, and a release flow.
- typst: a Typst package -- a library, or a template package
typst initstarts projects from -- held to Typst Universe's rules. - python: a Python project on uv -- a package with its command, a library, or a uv workspace.
- rust: a Rust crate under a strict lint policy -- a binary, a library, both, or a workspace.
cargo install --locked cargo-generate # 0.25 or later (the templates refuse older)
cargo generate --git https://github.com/veralvx/templates typst
cargo generate --git https://github.com/veralvx/templates python
cargo generate --git https://github.com/veralvx/templates rustEach command names its template's folder; with none named, cargo-generate asks which (under
--silent, it takes the first). It generates from the default branch, main, which CI checks.
nixpkgs' cargo-generate is built without its git feature and refuses --git: generate from a
clone instead, as each template's documentation shows, with its prompts, what it generates and how
to answer them all non-interactively.
- A
justfilethat runs locally what CI runs remotely:just checks, its formatter (just format, rust'sjust fmt),just release. - GitHub Actions workflows, every action pinned to a commit and moved by Dependabot, as are the
flake's inputs, monthly, every tool with them (python's and rust's
just pins-updatemoving the pins that follow them). - Conventional Commits, enforced by cocogitto and opt-in git hooks; a changelog written by git-cliff at each release, never by hand.
- A release tag publishes: python's packages to PyPI and rust's crates to crates.io, through Trusted Publishing (no token stored with the repository), rust's binaries through dist; typst's prepares its Typst Universe submission. Each makes its GitHub release, the changelog's section its notes.
- A Nix flake: the development shell,
nix fmt, the checks as derivations. - The workflows audited by zizmor, offline; the links checked by lychee (
just links: the local ones injust checks, every one monthly); python's and rust's code mutated against its tests (just mutation: mutmut;just mutants: cargo-mutants), each surviving mutant a failure. - Optionally, a
CITATION.cff(GitHub's "Cite this repository", Zenodo's archive), held to its schema by the flake. - dprint for the Markdown and TOML, an
.editorconfigfor the shell, and the community documents:CONTRIBUTING.md,AGENTS.md,SECURITY.md,CODE_OF_CONDUCT.md, issue and pull request templates.
A release tags every template at once, v<version>, and writes its section of CHANGELOG.md (from
the first release on); its GitHub release carries every tracked file as a tarball, which cargo generate --path <unpacked> <template> generates from.
Each check below is run, not reasoned about; what was verified of each template is its
dev/<template>/README.md (typst, python,
rust).
- Generation. Once the templates had moved here, every kind and option each smoke test covers
generated, from this repository, byte for byte -- contents and modes -- what the template's own
repository generated, but for a few comments of the shared workflows, reworded here; by
--pathand by--git, from a branch and from a tag. What changed since is this repository's history. And with no network at all -- each in a network namespace of its own, by cargo-generate's release build and by nixpkgs' kind (nogitfeature) -- every combination the smoke tests generate, each project the same as with it; what the projects need of the network after, eachdocs/<template>.mdsays, each claim run offline, from cold caches and warm, but Nix's and the package-check image's, which nothing here can fetch. - Each template. render-check renders every templated file for each template's answer
combinations and parses the result, and catches each defect planted in it; the smoke test's own
steps -- every answer combination generated, the answers it must refuse refused, every kind's
project -- run as written;
just smokepasses for every kind, with Nix stood in where nothing can be built here: eachnix developthe dev shell's own packages at their versions and nothing else -- but git, awk, valgrind, Python's and Rust's patch releases and stdenv's other tools, this machine's -- each in the generated project's own shell, Miri's tests run natively,nix fmtandnix flake checkleft to CI. Every kind's flake evaluates on every system, and its format, shell and workflows checks -- and python's and rust's pins (a rust library has none) -- pass as their derivations run them, git and awk aside. - The shared files.
just sync --checkfails on each drift planted: every copy changed, its executable bit flipped or missing, every line of every shared recipe, a dprint plugin apart, a template root missing from the lists that must name it, and Liquid in a root original wherever cargo-generate itself renders it. Its reading of a template's exclude list matches cargo-generate 0.25.0's own, fuzzed against the libraries cargo-generate uses. - CI. The template selection (
dev/changes.sh) and the one gate,smoke-gate, run as their workflow holds them, over merge commits made as GitHub makes them and every job result -- a failed or cancelled job, a template added with no job; every required check reports on every pull request; every workflow passes actionlint and zizmor's audit. - This repository's own tooling. The root flake evaluates on every system, with its lock as
committed, and its checks pass, emulated here as their derivations run them, with the same tool
versions but git's and awk's; every step of
just checkspasses but the last, the flake's checks, which build -- and in the root's dev shell too, Nix stood in as above;just generatemakes what the smoke tests make; four releases against a bare remote tag, write the changelog, push the commit and the tag together and refuse what they should. - The lock updates.
just lock-updatemoves back to the shipped tree, exactly, each staleness planted -- python's pins, rust's MSRV prompt andcargo-dist-version, the lock's three copies -- names each dev-shell tool the lock moved, and leaves an idle tree as it is;locks.yml's own scripts open, update, keep or refuse each pull request as they should, against a bare remote.nix flake update, unreachable here, is stood in for. No tool version is written by hand (just tool-versions-check, which refuses each form planted). - The dprint plugins' update.
just dprint-updatemoves everydprint.jsonalike, formats the root's Markdown and TOML and writes the shared files' copies anew, says each plugin moved (a move to npm too) and each file formatted, fails on dprint's own failure warning but its npm fallback, notes what it skipped, leaves an idle tree as it is and refuses a change outsidedev/dprint.files. Its pull request is the locks' script's (dev/propose.sh), which refuses a change that rewrites its matcher, widens its list or does more than change tracked files' content, against a bare remote.dprint config update, unreachable here, is stood in for.
The rest of each smoke workflow -- the git hooks' refusals, typst's lint-warning, just floor and
bundler steps, the changelogs and packages, the images, the releases, clippy on the latest stable,
Miri, the Nix builds -- the lock and plugin updates' workflows, and GitHub's side of CI run on
GitHub.
CONTRIBUTING.md (the tools, the checks, the release, adding a template), AGENTS.md (the rules), SECURITY.md, CODE_OF_CONDUCT.md.
The repository's tooling -- the workflows, the justfiles' shape, cliff.toml, cog.toml, the
hooks, the community documents -- is adapted from the three repositories below, which took it,
directly or through ffsuite, from
veralvx/imi (MIT OR Apache-2.0); each template's own attribution
is its documentation's.
The templates were typst-template,
python-template and
rust-template, which stay online with their releases
and changelogs:
typst-template's (0.1.0,
0.1.1), python-template's
(0.1.0) and rust-template's
(0.1.0, 0.1.1). This repository's CHANGELOG.md begins with its first release, v0.1.0.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
The generated projects are yours: their licence is the one you choose at generation.