Skip to content

About

The language-agnostic base: community files, issue and PR forms, the pinned toolchain, git hooks, the CI gate, and the doc rules

Topics

Resources

Code of conduct

Security policy

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

GitHub Project Template

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.

Stack

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

Getting started

  1. 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.

  2. 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
  3. Run the gate:

    just check

Editor

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.

Tasks

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

Layout

.
├── .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

Starting a project

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-project

Then follow the steps that it prints:

  1. In the new folder, run git init and git add -A. A flake sees only the files that git tracks.
  2. Run nix develop. It downloads the tools and installs the git hooks.
  3. Add your language tools to the dev shell in flake.nix, and your checks under checks.
  4. Fill in the format, lint, and test recipes in justfile with real commands. Keep the recipe names.
  5. Rewrite this README for the project, with the sections that ADR-0001 sets for its kind of repo.
  6. Update the contacts in .github/SECURITY.md and the copyright line in LICENSE.
  7. Install the Renovate app on the new repository.

With the GitHub template button

The button copies every file, the template/ folder included. Remove it in the first commit:

  1. Clone the new repository, and run nix develop in it.
  2. Run just init. It prints the first steps, and it removes the template/ folder with git.
  3. Commit the removal.
  4. Follow the printed steps from step 2. Your repository already has git.

Decisions

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.

Contributing

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.

Security

To report a vulnerability, follow SECURITY.md.

License

Apache License 2.0. See LICENSE.

About

The language-agnostic base: community files, issue and PR forms, the pinned toolchain, git hooks, the CI gate, and the doc rules

Topics

Resources

Code of conduct

Security policy

Stars

1 star

Watchers

1 watching

Forks

Contributors

Languages