A language-agnostic base for a new GitHub repository. It holds the community health files, the issue and pull request templates, a pinned toolchain, git hooks, a CI gate, and the documentation convention. Every other template in the blueprints set starts from it.
It holds no application code. A repo made from it adds the language tools and fills in the task contract.
| Tool | Owns |
|---|---|
| Nix with flakes | Tool versions, the dev shell, and the sandboxed checks |
| tabnix | The shared dev shell, git hooks, and checks |
| just | Tasks |
| Zed | The supported editor, with project settings in .zed/ |
| git-hooks.nix | Git hooks |
| cocogitto | Conventional Commits checks |
| rumdl | Markdown lint |
| dprint | JSON, TOML, and YAML format |
| tablint | Prose, comments, and ADRs |
| gitleaks | Secret scan |
| Renovate | Updates to the pinned versions |
-
Install Nix and enable flakes. For the editor, also install Zed, and direnv with nix-direnv. direnv enters the dev shell on
cd, and Zed loads it through direnv. -
Clone the repo and enter the dev shell. The first entry downloads every tool and installs the git hooks:
git clone git@github.com:tabmadi/github-project-template.git cd github-project-template nix develop -
Run the gate:
just check
Open the folder in Zed, and run direnv allow once. Zed suggests its Nix extension when you open flake.nix, so install it once on each machine. Zed then uses the language servers and formatters of the dev shell, formats on save, and lists every recipe under task: spawn. Zed loads the dev shell when it opens the folder. After a change to flake.nix, open the folder again, so Zed loads the new tools. Any other editor works through the same dev shell.
| Recipe | Does |
|---|---|
just setup |
Builds the dev shell and installs the git hooks |
just format |
Applies every formatter |
just lint |
Runs every linter: lint-md and lint-secrets |
just test |
Runs the tests. Here it is a placeholder |
just check |
Runs lint and test. Run it before you finish a change |
just ci |
Runs nix flake check, exactly what CI runs. The pre-push hook runs it too |
.
├── .config/
│ ├── cog.toml Commit types
│ ├── dprint.json JSON, TOML, and YAML format rules
│ ├── gitleaks.toml Secret scan rules
│ └── rumdl.toml Markdown rules
├── .github/
│ ├── ISSUE_TEMPLATE/ Bug, feature, and documentation issue forms
│ ├── workflows/check.yml The CI gate: just ci
│ ├── CODE_OF_CONDUCT.md
│ ├── PULL_REQUEST_TEMPLATE.md
│ ├── SECURITY.md
│ └── renovate.json Updates to the pinned versions
├── .zed/ Zed project settings and tasks
├── docs/adr/ The decisions of the project: foundations, doc conventions, toolchain
├── template/ What only the template needs: its contract, checks, and outputs
├── .envrc Enters the dev shell through direnv
├── flake.nix The dev shell, the git hooks, and the checks
├── flake.lock The pinned nixpkgs and inputs
├── justfile Tasks
├── AGENTS.md Hints for coding agents
├── README.md
└── LICENSE
Make a new project with Nix. It copies every file except the template/ folder, which holds what only the template needs. This is the preferred way:
nix flake new -t github:tabmadi/github-project-template my-projectThen follow the steps that it prints:
- In the new folder, run
git initandgit add -A. A flake sees only the files that git tracks. - Run
nix develop. It downloads the tools and installs the git hooks. - Add your language tools to the dev shell in
flake.nix, and your checks underchecks. - Fill in the
format,lint, andtestrecipes injustfilewith real commands. Keep the recipe names. - Rewrite this README for the project, with the sections that ADR-0001 sets for its kind of repo.
- Update the contacts in
.github/SECURITY.mdand the copyright line inLICENSE. - Install the Renovate app on the new repository.
The button copies every file, the template/ folder included. Remove it in the first commit:
- Clone the new repository, and run
nix developin it. - Run
just init. It prints the first steps, and it removes thetemplate/folder with git. - Commit the removal.
- Follow the printed steps from step 2. Your repository already has git.
The ADRs in docs/adr record every decision and the reason for it. template/adr/0000-template-contract.md records what makes this repo a template. ADR-0001 is the house style for all text.
Follow the Code of Conduct. Commit messages follow Conventional Commits, and the commit-msg hook checks them. Run just check before you open a pull request.
To report a vulnerability, follow SECURITY.md.
Apache License 2.0. See LICENSE.