Skip to content

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; corrected to resolve actual pin objects
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
038 Pinned sibling templates render independent module trees in one deterministic, append-only project ref
039 Native Git owns patch and diffstat presentation, including the configured pager
040 Native Git owns explicit merge abort recovery
041 Supplied answers preserve typed versus CLI origins
042 Lint compiles effective inherited output and every retained partial declaration
043 Configured local sources are rooted at the project, independently of ref identity
044 Rendered artifacts and snapshot manifests preserve symbolic-link modes and opaque targets
045 Git source objects persist locally while symbolic refs resolve freshly
046 Migration cases assert a real updated and merged project
047 Actual expression access controls data acquisition and computed resolution
048 Template tests assert resolved context with first-class null values
049 Snapshot manifests record paths and modes in TOML without content checksums or sizes