diff --git a/README.md b/README.md index 9bb78c0..3afccbf 100644 --- a/README.md +++ b/README.md @@ -908,8 +908,8 @@ Where the project is heading; the sections before Audience document what ships t 1. It covers the ten most-spoken languages and the Nordic countries. 2. Each locale covers the common categories: names, addresses, phone numbers, ids, companies and dates. - 3. The shipped data comes in Go packages, and a library gets only the packages it is - handed. + 3. The shipped data comes in Go packages, and a program links only the packages it + imports. 3. **The code is easy to understand.** 1. You can go from a bug to the code behind it without asking anyone. 2. You can change one part without keeping the rest in your head. diff --git a/docs/comprehension-history.md b/docs/comprehension-history.md index fe5470f..e0d8946 100644 --- a/docs/comprehension-history.md +++ b/docs/comprehension-history.md @@ -161,3 +161,12 @@ Inherited architect, decided by: - `shipped.go:61` `loadCallerPath`: the load-before-walk order is held by data flow, where a comment on `loadShippedAt` stated it - `node.go:30` `choice`: the `shared` comment no longer sends a `--list` bug to the wrong field - `README.md:163` `## Data`: the opening names the `geo` trees the section documents + +## 2026-10-09T16:48:45Z, PR #201 at c3ef728, against 2652779 + +Ruling: same + +| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | +|---|---|---|---|---|---| +| Mid A | same | same | same | same | same | +| Inherited architect | same | same | same | same | same | diff --git a/docs/decisions.md b/docs/decisions.md index 2db2d04..e3893db 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -140,20 +140,19 @@ still lives in `data/`; `--data-path` layers over it. ## The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0 -2026-10-04, Lilleman auf Larv; Go packages in the core's module, not Go modules of their own, from 2026-10-09. Serves goals 2.3, 6.2, 7.3, 9 and 10.1. Carried out by `todo.md` item 180, `todo.md` item 181, `todo.md` item 182, `todo.md` item 183, `todo.md` item 184, `todo.md` item 185 and `todo.md` item 186; until then the shipped data is embedded whole, as the decision "The shipped data is embedded, not discovered" states. The CLI binary may grow to hundreds of MB. +2026-10-04, Lilleman auf Larv; revised 2026-10-09 to put the packages in the core's Go module. Serves goals 2.3, 6.2, 7.3, 9 and 10.1. Carried out by `todo.md` items 180, 181, 182, 183, 184, 185 and 186; until then the shipped data is embedded whole, as the decision "The shipped data is embedded, not discovered" states. The CLI binary may grow to hundreds of MB. -- One Go package per locale, one per country's `geo/` tree, and one for `misc`, all in the core's Go module. A package registers nothing when imported, and Go links only the packages a program imports. +- One Go package per locale, one per country's `geo/` tree, and one for `misc`, all in the core's Go module. A package registers nothing when imported. - A bare `New()` loads no data and fails, naming the option to add. `WithoutShippedData` goes. - A data package's `FS` is an `fs.FS` passed to `WithDataFS`, as anyone's data is, and `New` takes several. A module carrying functions loads through an option of its own, so a data module that starts carrying functions breaks its users. Such a function reaches the randomness through an interface the root declares; `internal/drawstate`'s type stays internal. - A module names, in a manifest, every module it reads by default, directly or through another, so the first error names the whole set to import. A manifest is optional: a `--data-path` folder without one is a module. Nothing loads a default on its own. -- A module's manifest names the fejkdata version it was built for, and any version but the core's own fails in `New`, naming the `go get` line that aligns them. The maintainer chose exact equality on 2026-10-09. The shipped packages sit in the core's module, so they match it by construction. A module from anyone else then needs a new release on every fejkdata release, even when its data did not change. -- The README's one version covers the library, the CLI and the data, and CI cuts one tag per release. +- A module from anyone else names, in its manifest, the fejkdata version it was built for, and any other version than the core's fails in `New`, naming the `go get` line that aligns them. The maintainer chose exact equality on 2026-10-09, so such a module needs a new release on every fejkdata release, even when its data did not change. A shipped package's manifest names no version: it ships in the core's Go module. - In the CLI, a flag of its own says a `--data-path` replaces what it clashes with, so flags still go anywhere on the line. Data authors and hand fixture authors bench it. - The README asks for functions with no side effects of their own. - The CLI is a library call. One exported list names every shipped package, and `fejkdata`'s own `main` passes it to that call. The list lives in a package of its own, so a library importing the core links no data it did not import. A custom CLI is the same few lines with other modules added, and no code exists only for custom CLIs. A README section shows it with example code, and the README's Library quick start shows the whole import block for one locale. - Before the module API ships, a panel of the README's audience personas tries pulling in data with it. -Valid while downloading every shipped package costs a library user little, since `go get` fetches a whole module. Past that, the largest packages move into nested Go modules that keep their import paths; the `go` command refuses a module zip over 500 MiB (`MaxZipFile` in `golang.org/x/mod/zip`). +Valid while downloading every shipped package costs a library user little, since `go get` fetches the whole Go module. Past that, the largest packages move into nested Go modules that keep their import paths, each requiring the core release that drops the package, so no build sees it twice; the `go` command refuses a Go module zip over 500 MiB (`MaxZipFile` in `golang.org/x/mod/zip`). ## With only the shipped set, a category loads on the first call reaching it; beside a `--data-path`, every category loads in `New` diff --git a/todo.md b/todo.md index 82c3f0f..4e03c8d 100644 --- a/todo.md +++ b/todo.md @@ -78,7 +78,7 @@ | 57 | 0.1.0 | | **Rewrite `CHANGELOG.md`'s `[Unreleased]` as what v0.1.0 holds.** | 1 | 2 | 6 | 6 | 1.1 | 22.5 | | 164 | 0.1.0 | | **Let a table's format or a cell bind a name, which lives in that format or cell and keeps one pick through the draw.** | 2 | 2 | 5 | 7 | 4.1, 5.3 | 19.4 | | 157 | 0.1.0 | | **Show in the README's CLI section how PowerShell and cmd.exe pipe a template, one line per shell family.** | 1 | 1 | 5 | 6 | 7.2 | 17.1 | -| 183 | 0.1.0 | decision | **Fail `New` when a manifest's `fejkdata` version is not exactly the core's, naming the `go get` line that aligns them.** | 3 | 2 | 5 | 7 | 6 | 17.0 | +| 183 | 0.1.0 | decision | **Fail `New` when a manifest's `fejkdata` version is not exactly the core's version, naming the `go get` line that aligns them.** | 3 | 2 | 5 | 7 | 6 | 17.0 | | 181 | 0.1.0 | decision | **Fail a load where two sources define one category, unless the library's option or the CLI's flag says the later replaces the earlier, and then make every read reach the replacement.** | 5 | 4 | 6 | 9 | 9.3 | 16.8 | | 167 | 0.1.0 | | **Lower the reading cost of the files a chunk reads most before its first commit.** | 1 | 3 | 2 | 8 | 3, 3.4 | 16.6 | | 89 | 0.1.0 | | **Fail `New` without `WithSeed`, naming the option, and seed the CLI from the system.** | 3 | 3 | 6 | 7 | 10.1 | 16.0 | @@ -185,12 +185,12 @@ Needs item 180. Carries out the decision "The shipped data is Go packages a libr - Each package's directory is a data root, so its tree spells its namespace: `data/sv_SE/` is `github.com/larvit/fejkdata/data/sv_SE` and holds `sv_SE/*.json`; `data/geo/SE/` holds `geo/SE/…`. Each package exports only `var FS embed.FS`, with no `init`, and carries a generated manifest whose `reads` names the modules it reads, `sv_SE` naming `geo/SE`. - The package `github.com/larvit/fejkdata/data` exports `Modules() []fs.FS` and imports every data package; the core imports none, so a library links only the data it imports. - The core stops embedding data. `WithDataFS` takes several. `WithoutShippedData` goes, and `--no-shipped-data` loads none of the modules the CLI carries. A read nothing provides fails, naming the module from the reader's manifest or saying none does, and the first error names the whole set to import. -- A data package imports nothing of the core, so core tests may import data packages, and each data package's own test calls `New(WithDataFS(FS))`. `data-import/` output paths, `AGENTS.md`, CI's changelog filter and the shape pin follow the move. +- A data package imports nothing of the core, so core tests may import data packages. Each data package's own test calls `New(WithDataFS(FS))`. `data-import/` output paths, `AGENTS.md`, CI's changelog filter and the shape pin follow the move. - Revises the decisions "The shipped data is embedded, not discovered" and "A locale's `address` reads its country's `geo` tree, so a locale folder is no data set on its own". ### 185. Seat a panel of the README's audience personas to pull data in through the module API and build a custom CLI, and fix what it names. -Needs item 184; 0.1.0 is not cut before it. Carries out the decision "The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0". Seats: the Go test author, the bulk fixture author, a custom CLI's builder, and a data author with a `-d` folder and the replace flag, each in a scratch module against the checkout or a pre-release tag. Bench the geo packages' names, `data.Modules()`, and the error naming the import set. Record the ruling in `docs/`. +Needs item 184; 0.1.0 is not cut before it. Carries out the decision "The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0". Seats: the Go test author, the bulk fixture author, a custom CLI's builder, and a data author with a `-d` folder and the replace flag, each in a scratch Go module against the checkout or a pre-release tag. Bench the geo packages' names, `data.Modules()`, and the error naming the import set. Record the ruling in `docs/`. ### 16. Add locale categories: company, phone, finance, vehicle, words. @@ -291,9 +291,9 @@ The maintainer ruled so on 2026-10-09: a name is a lexical closure, as the decis Split from item 129. cmd.exe's `echo` keeps its quotes and a trailing space, so `echo {/users} | fejkdata` sends `{/users} ` and stops naming the record. -### 183. Fail `New` when a manifest's `fejkdata` version is not exactly the core's, naming the `go get` line that aligns them. +### 183. Fail `New` when a manifest's `fejkdata` version is not exactly the core's version, naming the `go get` line that aligns them. -Needs item 182. Carries out the decision "The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0". A shipped package's manifest names no version, since it ships in the core's module. A module from anyone else names the version it was built for. The core reads its own from `debug.ReadBuildInfo()` in the shell and passes it to a pure comparison, which skips where it is `(devel)` or missing, as in a checkout. Probe first that a library user's `go test` binary records the core's version. +Needs item 182. Carries out the decision "The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0". A shipped package's manifest names no version, since it ships in the core's module. A module from anyone else names the version it was built for. The core reads its own from `debug.ReadBuildInfo()` outside the pure comparison, and the check passes when that version is `(devel)` or missing, as in a checkout. Probe first that a library user's `go test` binary records the core's version. ### 181. Fail a load where two sources define one category, unless the library's option or the CLI's flag says the later replaces the earlier, and then make every read reach the replacement. @@ -325,7 +325,7 @@ The maintainer ruled so on 2026-10-09. Today `checkSelectorCells` in `internal/r ### 180. Load on first reach a source whose `.fejkdata.json` carries an index, and any other source in `New`; move the shipped index from `shippedindex.go` into that manifest. -Carries out the decision "The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0". The manifest is `.fejkdata.json` at a module's root, hidden so it is no category: `{"fejkdata": version, "reads": {path prefix: module}, "index": {category: {"parent", "paths", "reads"}}}`. `go generate` writes it from the data, as it writes `shippedindex.go` today, and `TestShippedIndexIsCurrent` becomes a test that it is current. +Carries out the decision "The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0". The manifest is `.fejkdata.json` at a module's root, hidden so it is no category: `{"fejkdata": version, "reads": {path prefix: module}, "index": {category: {"parent", "paths", "reads"}}}`, where a shipped package's manifest leaves out `fejkdata`. `go generate` writes it from the data, as it writes `shippedindex.go` today, and `TestShippedIndexIsCurrent` becomes a test that it is current. - `internal/datafiles` reads the manifest, and `shipped.go`'s unloaded tree is built per source from its index, so fejkdata's data loads as anyone's does (goal 9.1). - Each index entry carries the categories it reads. Beside a `--data-path`, `New` loads the user's categories, what they read and the shipped categories reaching a replaced one; the rest load on first reach. - Core tests move to `fstest.MapFS` fixtures carrying manifests. @@ -333,7 +333,7 @@ Carries out the decision "The shipped data is Go packages a library imports by c ### 191. Read an existing tag through `git/ref/tags/{tag}` in `publish_release.py`, so its guard against a tag at another commit fires. -GitHub answers `tags/{tag}` with 404 whatever exists, so a release job on another commit than the tag's publishes the release on that old tag instead of stopping. +GitHub has no `tags/{tag}` endpoint and answers 404 whether or not the tag exists. So when the tag already sits at another commit, the release job publishes on that old tag, and the guard never stops it. The guard follows an annotated tag to its commit before comparing. ### 58. Ship prebuilt binaries, a container image, and packages for Homebrew, Scoop and the biggest Linux package managers, so the CLI needs no Go.