Architecture decisions¶
Short records of decisions that are hard to reverse, where there was a real alternative, or where the reasoning would otherwise be lost.
They are referenced by number from code comments, hooks, workflows and the rest of the documentation. A decision that changes gets a new ADR that supersedes the old one; the old one stays, because the reasoning still explains the code that existed.
| # | Decision |
|---|---|
| 001 | The rendered state of a template is a Git ref |
| 002 | No custom merge or reconciliation |
| 003 | MiniJinja is the only template engine |
| 004 | A single crate, not a workspace |
| 005 | Template refs are append-only |
| 006 | No runtime values in the template context |
| 007 | Question order is derived from a static dependency graph |
| 008 | Provenance lives in commit trailers, not in the tree |
| 009 | init merges the template commit into the branch |
| 010 | Project configuration lives at .config/git.tpl.toml |
| 011 | git2 is confined to one module, enforced by a hook |
| 012 | Partials are .jinja files outside the render root |
| 013 | User preferences live in ~/.config/git-tpl/config.toml |
| 014 | An undefined name in a rendered file may be an error |
| 015 | --json carries a stable diagnostic code on every failure |
| 016 | Template tests are declarative cases in the template repository, with no code execution |
| 017 | .gitignore is evaluated by us, not by libgit2 |
| 018 | A prompt seed may be derived from the repository, through a closed context |
| 019 | A template may address the user and declare Git remotes; it never runs anything |
| 020 | backport emits a patch, and proves it by re-rendering |
| 021 | The attachment rides in the merge commit, so init adds one commit |
| 022 | Un-substitution is proved per line, and confirmed by a human |
| 023 | Hunk selection precedes the proof, and is taken on your own edits |
| 024 | A migration is a file, discovered by diffing the template's own history |
| 025 | A question may keep its default when skipped |
| 026 | A rendered path piece may be . or fan out across /; only .. and a backslash are rejected |
| 027 | A test case may declare commands, run by the harness alone |
| 028 | A test case declares its own trust in remote data sources |
| 029 | A test case's [answers] is always validated strictly |
| 030 | test never resolves a remote template, dirty by default |
| 031 | A Git front-end works by riding ADR-001 and ADR-011, not by being supported |
| 032 | --write only writes; it does not run a case's [commands] or expect |
| 033 | A test case may ask for an isolated Git sandbox |
| 034 | A template may extend one parent, pinned, merged by name |
| 035 | test reports progress as GitHub Actions workflow commands, auto-detected |
| 036 | --shard and --record-durations balance a test suite across a CI matrix |
| 037 | backport hunks can be listed and named in advance, so a script can select without a prompt |