Make great documentation goal 1.2, and plan the README's reorganisation and the nested-template gaps #33

Open
lilleman wants to merge 966 commits from worktree-todo-relative-dates-exact-counts into main
3 changed files with 6 additions and 7 deletions
Showing only changes of commit 665c532f8c - Show all commits
+2 -3
View File
@@ -843,9 +843,8 @@ a minor only adds, and a major is the only release that changes what exists.
A patch changes no row of this table: performance, docs, or a fix inside a promised A patch changes no row of this table: performance, docs, or a fix inside a promised
behaviour that changes no value, path, format or spelling. behaviour that changes no value, path, format or spelling.
Seeded output is a promise within one version: same seed, same version, same Any release may shift a seeded stream, since a value added to a list moves every
data, same output. Any release may shift a stream, since a value added to a list draw after it, so pin fixtures per version. An error's wording may
moves every draw after it, so pin fixtures per version. An error's wording may
improve in a minor; the path, rejected spelling and replacement it names may not. improve in a minor; the path, rejected spelling and replacement it names may not.
Before `v1.0.0` a minor is the breaking unit: `0.(x+1).0` may carry a major's Before `v1.0.0` a minor is the breaking unit: `0.(x+1).0` may carry a major's
+2 -2
View File
@@ -255,8 +255,8 @@ assumes a 64-bit int; on a 32-bit target it could overflow and panic.
load error; the fold stops where an operand varies, so `a/(b*c)` with `b` fixed at `0` load error; the fold stops where an operand varies, so `a/(b*c)` with `b` fixed at `0`
and `c` varying loads and prints `Inf` every draw — catching it needs zero-absorbing and `c` varying loads and prints `Inf` every draw — catching it needs zero-absorbing
algebra for a shape nobody writes. A [typed column](../README.md#datatype) bounds its operands algebra for a shape nobody writes. A [typed column](../README.md#datatype) bounds its operands
instead and refuses a divisor it cannot keep from zero. `Inf` and `NaN` in a string column instead and refuses a divisor it cannot keep from zero. An operand that is sometimes not a
work against goals 6.1 and 4 until `todo.md` item 81 refuses them there too. number prints `NaN` the same way. `Inf` and `NaN` in a string column work against goals 6.1 and 4 until `todo.md` item 81 refuses them there too.
## In data, a default written out and a constant spelled as a sample are load errors ## In data, a default written out and a constant spelled as a sample are load errors
+2 -2
View File
@@ -135,7 +135,7 @@
### 77. Split the shipped data into Go modules per locale and country, which a library imports by choice, and embed every one in the CLI. ### 77. Split the shipped data into Go modules per locale and country, which a library imports by choice, and embed every one in the CLI.
The CLI binary carries every module and may grow to hundreds of MB; a library imports only what it uses, as it imports any dependency, and nothing is fetched at run time. Goal 2 says what ships where. The maintainer decided on 2026-10-04: one module per locale, one per country's `geo/` tree and one for `misc`; and a module registers nothing when imported: the library passes it to `New`, as in `New(WithData(svse.Data))`, per the technical principles' dependency injection and no package globals. The entry for `docs/decisions.md` is written when this ships. Before the module API ships, a panel of the README's audience personas tries pulling in data with it. The CLI binary carries every module and may grow to hundreds of MB; a library imports only what it uses, as it imports any dependency, and nothing is fetched at run time. Goal 2 says what ships where. The maintainer decided on 2026-10-04: one module per locale, one per country's `geo/` tree, and one for `misc`. A module registers nothing when imported; the library passes it to `New`, as in `New(WithData(svse.Data))`, per the technical principles "Compose, do not entangle" and "Explicit over implicit". The entry for `docs/decisions.md` is written when this ships. Still to decide: what a bare `New()` loads, whether a module's data is an `fs.FS` passed to `WithDataFS` so no second option exists, and whether `WithoutShippedData` goes. Before the module API ships, a panel of the README's audience personas tries pulling in data with it.
### 78. Ship 10% of every place's streets, at least 10, and 10% of all US places drawn by population, each place weighted by population. ### 78. Ship 10% of every place's streets, at least 10, and 10% of all US places drawn by population, each place weighted by population.
@@ -264,7 +264,7 @@ GoReleaser attaches the binaries to the release the tag workflow publishes, and
### 81. Refuse at load every `calc` operand not proven numeric and every divisor not proven nonzero, in a string column too. ### 81. Refuse at load every `calc` operand not proven numeric and every divisor not proven nonzero, in a string column too.
The decision "A constant zero divisor is a load error; in a string column a divisor that is not constant prints `Inf`" lets `{calc(a/(b*c))}` with `b` fixed at `"0"` write `Inf` into every row, and an operand that is sometimes not a number prints `NaN`, against goals 6.1 and 4; `valueproof.go` already proves a typed column's divisor nonzero. The decision "A constant zero divisor is a load error; in a string column a divisor that is not constant prints `Inf`" lets `{calc(a/(b*c))}` with `b` fixed at `"0"` write `Inf` into every row. An operand that is sometimes not a number prints `NaN`. Both work against goals 6.1 and 4. `valueproof.go` already proves a typed column's divisor nonzero.
### 36. Report every mistake a load finds in one error, as the decision "A load reports every mistake at once" states. ### 36. Report every mistake a load finds in one error, as the decision "A load reports every mistake at once" states.