tmu
c15bc0153e
Actionable sentence in CONTRIBUTING.md § Rules the tools don't enforce; the why — humans skim, agents imitate the dominant style, so verbosity compounds — in development/README.md § Decision blocks. Both sides in one commit per the write-each-fact-once rule.
82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# 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](../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](../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](./library.md) | Public API design, the type-level contract, and its limitations |
|
|
| [workflow.md](./workflow.md) | Branching and merging, script prefixes, feedback tiers, commit messages |
|
|
| [tooling.md](./tooling.md) | Toolchain choices and configuration, editor setup |
|
|
| [testing.md](./testing.md) | Test strategy and type-driven development |
|
|
| [ci.md](./ci.md) | CI pipeline, runner image, coverage serving |
|
|
| [publishing.md](./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:
|
|
|
|
```md
|
|
## 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
|
|
|
|
1. Pick the category: `library`, `workflow`, `tooling`, `testing`, `ci`,
|
|
`publishing`.
|
|
2. Add or update a decision block; keep existing text unless the decision
|
|
changed.
|
|
3. If an actionable rule changes, update
|
|
[CONTRIBUTING.md](../CONTRIBUTING.md) in the same commit and cross-link.
|
|
Never change a rule there without updating its rationale here.
|