From 33f8ff4df407dfb182cf09c3fef8e1bb45dcf6ea Mon Sep 17 00:00:00 2001 From: Alexander Mills Date: Fri, 28 Aug 2026 13:51:39 -0500 Subject: [PATCH] Document generated/ freeze vs writable policy. --- clients/generated/README.md | 43 +++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 clients/generated/README.md diff --git a/clients/generated/README.md b/clients/generated/README.md new file mode 100644 index 0000000..8b95a29 --- /dev/null +++ b/clients/generated/README.md @@ -0,0 +1,43 @@ + + +# Generated files — read-only + +Do **not** hand-edit files in this directory. They are produced by tooling such as: + +- https://github.com/flags-2-env/flags-2-env (typical Dart path: `generated/dart/env.dart`) +- https://github.com/oresoftware/api-docs +- JSON Schema / OpenAPI / route-map generators in this repository + +## Disk permissions + +After generation, files here are frozen with `chmod a-w` (not writable). Directories +and this `README.md` stay writable so generators can replace files. + +Git does **not** persist the write bit (only the executable bit). A fresh clone is +writable until you re-freeze: + +```sh +find generated -type f ! -name 'README.md' ! -name 'readme.md' -exec chmod a-w {} + +``` + +To regenerate, change the **primary source** (`.cli-flags.toml`, route map, OpenAPI, +`schema/*.schema.json`, …) and re-run the generator. Preferred generators thaw, +write, then `chmod a-w` themselves. + +## Gitignored trees + +If `generated/` is in `.gitignore`, generated artifacts stay off VCS. Still commit +this `README.md` (`git add -f generated/README.md` or a `.gitignore` exception) so +the freeze policy is visible. Example exception: + +``` +generated/** +!generated/README.md +``` + +## Runtime contract (not just compile-time) + +JSON Schema is a **cross-check**, not always the primary generator input. Unit tests +should validate fixtures/examples against Draft 2020-12 at runtime (valid must pass, +invalid must fail) and compare schema keys to `.cli-flags.toml` env names or +route-map keys when those exist.