From 0323a4146abe2493d3461865eeb12c3fe1bd64a3 Mon Sep 17 00:00:00 2001 From: Tommy Keswick Date: Tue, 1 Sep 2026 14:28:14 -0700 Subject: [PATCH] Record the decisions behind the docs build as ADRs Adopting the MADR format already used in caltechlibrary/alchemist and caltechlibrary/workflows: docs/decisions/, NNNN-kebab-case.md, immutable once accepted, rejected options recorded. Two decisions, chosen on the test in ADR-0001 -- a decision worth recording is one whose result looks like unnecessary complication to someone who did not watch it being made, and which a future reader would therefore be tempted to "simplify" back: 0002 build the site rather than publishing the repository 0003 keep sources and generated files in separate namespaces Both carry the alternatives that were rejected and why, which is the part the code cannot show. 0002 records that a self-contained workflow was built first and worked, and was rejected anyway because it is a copy -- and that the reusable workflow cannot be used here, since a caller cannot add a Deno setup step to a job it did not write. 0003 records why several Markdown files stay in the root: cmt writes them there and its generator registry keys on the exact output filename, so it cannot write to docs/. The reasoning was in the description of #46, which stops being read the moment it merges. The ADRs are not rendered into the site: the build globs docs/*.md without recursing, so docs/decisions/ is carried in the repository and read on GitHub. That suits the audience -- they are for people changing this repository, not for people using the components. Co-Authored-By: Claude Opus 5 --- .../0001-record-architecture-decisions.md | 53 ++++++++ ...e-rather-than-publishing-the-repository.md | 114 ++++++++++++++++++ ...3-separate-sources-from-generated-files.md | 103 ++++++++++++++++ 3 files changed, 270 insertions(+) create mode 100644 docs/decisions/0001-record-architecture-decisions.md create mode 100644 docs/decisions/0002-build-the-site-rather-than-publishing-the-repository.md create mode 100644 docs/decisions/0003-separate-sources-from-generated-files.md diff --git a/docs/decisions/0001-record-architecture-decisions.md b/docs/decisions/0001-record-architecture-decisions.md new file mode 100644 index 0000000..622a9aa --- /dev/null +++ b/docs/decisions/0001-record-architecture-decisions.md @@ -0,0 +1,53 @@ +# 1. Record architecture decisions + +- Status: accepted +- Date: 2026-09-01 + +## Context and Problem Statement + +Several things about this repository look like mistakes to anyone who did not +watch them being decided. Documentation sources live in `docs/` while several +Markdown files stay in the root. The docs workflow calls an action directly +rather than the shorter reusable workflow that exists for the purpose. + +Each is the survivor of an alternative that was tried or costed and rejected, +and the reasoning lived in a pull request description, which stops being read +the moment it merges. The next person to look — human or LLM — sees +only the surviving design and is free to "simplify" it back into the thing that +already did not work. + +## Decision + +Record architecturally significant decisions as ADRs in `docs/decisions/`, +following [MADR](https://adr.github.io/madr/), matching the conventions already +in use in `caltechlibrary/alchemist` and `caltechlibrary/workflows`. The format +originates with Michael Nygard's [Documenting Architecture +Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). + +Conventions: + +- One file per decision, `NNNN-title-in-kebab-case.md`, numbered sequentially + in the order recorded (not the order decided). +- Each has a status: `proposed`, `accepted`, `rejected`, `deprecated`, or + `superseded by ADR-NNNN`. +- **ADRs are immutable once accepted.** A decision that changes is not edited; + a new ADR supersedes it, and the old one is marked as superseded. +- Corrections of *fact* about what shipped are fine to amend in place, dated + and noted. Changes of *decision* get a new ADR. +- Record the rejected options and why. That is usually the most valuable part + and the part that cannot be recovered from the code. + +## Consequences + +Decisions with consequences outliving the change that introduced them get a +stable home, and pull request descriptions stop being load-bearing. + +These are **not** rendered into the published site, even though they sit under +`docs/`. The build globs `docs/*.md` and does not recurse, so the directory is +carried in the repository and read on GitHub. That suits the audience: ADRs are +for people changing this repository, not for people using the components. If +they should be published later, the build takes an `extra-sources` glob. + +The cost is discipline. An ADR nobody writes is worthless, and one nobody +supersedes when the decision changes is worse than worthless. Routine changes — +a new component, a documentation fix, a dependency bump — do not need one. diff --git a/docs/decisions/0002-build-the-site-rather-than-publishing-the-repository.md b/docs/decisions/0002-build-the-site-rather-than-publishing-the-repository.md new file mode 100644 index 0000000..327837c --- /dev/null +++ b/docs/decisions/0002-build-the-site-rather-than-publishing-the-repository.md @@ -0,0 +1,114 @@ +# 2. Build the documentation site rather than publishing the repository + +- Status: accepted +- Date: 2026-09-01 + +## Context and Problem Statement + +Documentation used to reach the web through `make website`, `./publish.bash` +and a merge into a `gh-pages` branch. That was replaced by `static.yml`, the +stock GitHub "Deploy static content to Pages" template, which uploads the +repository as the site: + +```yaml +- uses: actions/upload-pages-artifact@v3 + with: + path: '.' +``` + +That removed the `gh-pages` branch, which was worth doing, but it published +more rather than less. Two consequences, both observed on the live site before +this change: + +- **Repository internals were served publicly.** `Makefile`, `codemeta.json`, + `deno.json` and `page.tmpl` all returned 200 from + `software.library.caltech.edu/CL-web-components/`. +- **The site was whatever HTML happened to be committed.** Nothing rendered the + Markdown, so a documentation change only reached the site if someone + remembered to run `make website` and commit the output. Commit 7f20bdd + updated the hostname in `INSTALL.md` and `README.md`; the committed HTML was + never regenerated, so the published pages still showed the old hostname. + +## Decision Drivers + +- Publishing should not depend on anyone remembering a manual step. +- Only the documentation should be published. +- The build should not be another thing this repository has to maintain. + +## Considered Options + +1. Keep `static.yml`, and remember to regenerate the HTML +2. Keep `static.yml`, but narrow `path:` to a built directory +3. Build in a workflow owned by this repository +4. Build by referencing `caltechlibrary/workflows` + +## Decision Outcome + +**Chosen: option 4.** The docs workflow calls +`caltechlibrary/workflows/.github/actions/build-pandoc@v1`, which renders the +Markdown, and `deploy-site@v1`, which uploads the result. + +### Option 1: remember to regenerate — rejected + +This was the status quo, and it had already failed. The hostname change is the +evidence: the source was updated, the output was not, and nothing detected it. + +### Option 2: narrow the `path:` — rejected + +Would have fixed the leak but not the staleness. The site would still have been +committed HTML, just less of it. + +### Option 3: our own build workflow — rejected + +This was built first and worked — the resulting site was byte-identical to what +was published. It was rejected because it is a copy. Every other Caltech +Library site needs the same 127 lines, and copies drift: `codemeta2cff.yml` +exists in fourteen repositories in five distinct versions, two of them still +pinning `actions/checkout@v2`. + +### Option 4: reference the shared repository — chosen + +The build lives in one place and this repository names a version. A fix there +arrives on the next run; a breaking change requires moving from `@v1` +deliberately. + +## Consequences + +Good: + +- Publishing a documentation change is `git push`. There is no output to + regenerate and no step to forget. +- Only rendered documentation and its declared assets are published. +- Pull requests build the site without deploying it, so a change that breaks + the docs fails in review. +- Improvements to the shared build — accessibility fixes, a Pandoc upgrade — + arrive without editing this repository. + +Bad, and accepted: + +- A dependency on another repository. Mitigated by the version contract: `@v1` + moves only for backward-compatible changes, and pinning a tag or SHA is + available if this repository ever needs to freeze. +- Debugging gains one indirection. `bin/build-pandoc.sh` in the shared + repository runs locally with no GitHub context, so a failing build can be + reproduced on a laptop. + +### Why the action and not the reusable workflow + +`caltechlibrary/workflows` also offers `docs-pandoc.yml`, which would reduce +this repository's workflow to about ten lines. It is not usable here. + +The site publishes compiled component bundles, so `deno task build` must run +before rendering, which needs `denoland/setup-deno` first. **A caller cannot +add steps to a job it did not write.** Using the action inside our own job +costs roughly fifty lines and keeps everything else shared: the Pandoc +invocation, both Lua filters, the theme handling and the Pages plumbing. + +This is the two-tier design working as intended, not a workaround. See +`caltechlibrary/workflows` ADR-0004. + +## More Information + +- caltechlibrary/CL-web-components#46 — the change, with the page-by-page verification +- `caltechlibrary/workflows` ADR-0002 — why shared logic is referenced, not copied +- [ADR-0003](0003-separate-sources-from-generated-files.md) — the layout this depends on diff --git a/docs/decisions/0003-separate-sources-from-generated-files.md b/docs/decisions/0003-separate-sources-from-generated-files.md new file mode 100644 index 0000000..f30c25a --- /dev/null +++ b/docs/decisions/0003-separate-sources-from-generated-files.md @@ -0,0 +1,103 @@ +# 3. Keep sources and generated files in separate namespaces + +- Status: accepted +- Date: 2026-09-01 + +## Context and Problem Statement + +The repository root held around a hundred entries with no separation between +things a person writes and things a tool produces: Markdown sources beside +their rendered HTML, component sources in `src/` beside bundles of the same +name in the root, the Pandoc theme, build scripts, and a committed search +index. + +That arrangement caused real failures, not untidiness: + +- **Ten filenames existed in both `/` and `src/`** — `textarea-csv.js`, + `card-layout.js` and eight others. One of each pair was build output and + could be stale, with nothing indicating which. +- **`add-col-scope.lua` was referenced by `website.mak` but never committed**, + so `make website` failed on the first Markdown file for three months. The + file was invisible among the other root entries; it existed only on the + `gh-pages` branch, where it had been published. +- **Generated HTML drifted from its Markdown.** Commit 7f20bdd changed a + hostname in the sources; the committed pages kept the old one and were + served that way. + +Each of those had the same root cause: authored and generated files sharing one +namespace, so nothing about a file's location said whether editing it meant +anything. + +## Decision + +``` +docs/ Markdown sources, demo and test pages +pandoc/ the Pandoc template +src/ component sources +/ only what has to be there +``` + +Build output is not committed. The site is assembled into `_site/` by CI and +uploaded as an artifact; bundles go to `dist/`, which is gitignored. + +**Some Markdown stays in the root:** `README.md`, `INSTALL.md` and the +`INSTALL_NOTES_*` pair. Not by preference — `cmt` writes them there and can +only write there. Its generator registry keys on the exact output filename, so +`cmt codemeta.json docs/about.md` exits with `unsupported format`. The build +renders them with `extra-sources: "*.md"`, so they are published exactly as +before. + +## Considered Options + +1. Leave the layout flat and be more careful +2. Move everything into `docs/`, including what `cmt` generates +3. Move what can move; render the rest from where `cmt` puts it + +## Decision Outcome + +**Chosen: option 3.** + +### Option 1: be more careful — rejected + +Three months of a broken build, ten shadowed filenames and a stale published +site were the result of being careful. The layout is what made those failures +possible and hard to see. + +### Option 2: move everything — rejected + +Would require either patching `cmt` to accept subdirectory output, or accepting +that a `cmt` run silently reverts the layout. Neither is this repository's +decision to make unilaterally, and the second is worse than the problem. + +### Option 3: move what can move — chosen + +Documentation sources leave the root, which is what allows the build to stop +looking there. The files `cmt` owns stay where it puts them and are rendered +explicitly, so the constraint is visible in the workflow rather than implied. + +## Consequences + +Good: + +- A file's location says whether editing it means anything. Everything in + `docs/` and `src/` is authored; nothing generated is committed except what + `cmt` writes to the root. +- Generated output cannot go stale, because it no longer exists between builds. +- The generated HTML still committed in the root became unused the moment the + build stopped looking there, so removing it is a separate, purely subtractive + change. + +Bad, and accepted: + +- The root is not uniform. Some Markdown sits outside `docs/` for a reason + that is not obvious from looking, which is why it is written down here and + commented in the workflow. +- `extra-sources: "*.md"` publishes every root Markdown file, including any + `cmt` adds later. That reproduces the previous behaviour exactly, but it is + a glob rather than a list, so a new root file appears on the site without + anyone choosing that. + +## More Information + +- caltechlibrary/CL-web-components#46 — the move, with page-by-page verification +- [ADR-0002](0002-build-the-site-rather-than-publishing-the-repository.md) — the build this enables