0 Fork 0

Files

T

tmu 05fad0fcd6 📝 Record the autocomplete and matcher-design decisions

The matcher is now two three-overload factories; library.md documents why
the union merge, inferred universe, conditional RequireKeys and cases-first
paths were rejected, and lists the two open issues (the fallback sees all of
T; a redundant _ is still accepted). testing.md records the language server
as the autocomplete oracle, and CONTRIBUTING points the exception at the
matcher's own test file.

The backlog marks the design-doc and autocomplete groundwork done alongside
the adoption.

2026-09-17 20:59:28 +00:00

ci.md

📝 Improve docs after split

2026-09-15 21:46:41 +00:00

library.md

📝 Record the autocomplete and matcher-design decisions

2026-09-17 20:59:28 +00:00

publishing.md

📝 Improve docs after split

2026-09-15 21:46:41 +00:00

README.md

📝 Require concise prose in development/

2026-09-16 08:00:36 +00:00

testing.md

📝 Record the autocomplete and matcher-design decisions

2026-09-17 20:59:28 +00:00

tooling.md

🔥 Remove the match and pattern example modules

2026-09-16 21:57:55 +00:00

workflow.md

♻️ Let create:branch start from an ahead main

2026-09-15 22:14:51 +00:00

README.md

Development documentation

Why this project works the way it does: the decisions, what was rejected, and the shortcomings and known issues we carry. Written for maintainers and contributors.

The actionable rules — setup, running, testing, submitting — live in CONTRIBUTING.md. Each fact is written once: the rule there, the reason here; neither restates the other, and where a fact is useful in both they link. Read the relevant file before changing an area, and when a rule changes update its rationale here in the same commit.

User-facing documentation is README.md. docs/ is deliberately unused: that name is reserved for the future user documentation site, and deploying it is out of scope. These files are not part of that site.

Layout

One file per category:

File	Covers
library.md	Public API design, the type-level contract, and its limitations
workflow.md	Branching and merging, script prefixes, feedback tiers, commit messages
tooling.md	Toolchain choices and configuration, editor setup
testing.md	Test strategy and type-driven development
ci.md	CI pipeline, runner image, coverage serving
publishing.md	Release and npm publishing

We start with one file per category so each area stays small enough to hold in mind; a category that outgrows it becomes a folder with an index, and the links in CONTRIBUTING.md and README.md point at the category, not a single decision.

Decision blocks

Record every non-obvious choice as a block in the relevant category file:

## Runner image

#### Decision (2026-09)

Bake Node into the CI job image at the setup-node tool-cache layout instead
of downloading per job.

#### Why

- ...

#### Rejected

- Gitea Pages / per-job download
- force-pull

#### Known issue

- a Dockerfile-only change re-pushed under an unchanged tag is invisible to the runner
    - recover with `docker rmi <image>`

The date is the month the decision was made, not when the file was edited — the anchor for "current" versus "was current once".
Rejected stops the project re-litigating the same alternatives; an empty one usually means they were never written down.
Known issue is where shortcomings live. A caveat not tied to one decision goes under a ## Known issues section at the end of the file.
Replace a superseded decision in place rather than archiving it; git history is the archive.
Terse is the point: humans skim and agents imitate the style already in the file, so verbosity compounds edit over edit. Grammar loses to density here on purpose.

Adding to these docs

Pick the category: library, workflow, tooling, testing, ci, publishing.
Add or update a decision block; keep existing text unless the decision changed.
If an actionable rule changes, update CONTRIBUTING.md in the same commit and cross-link. Never change a rule there without updating its rationale here.