From c5ef1f58ffa09258216ad106d1bf5da07d2becaf Mon Sep 17 00:00:00 2001 From: tiennm99 Date: Sat, 15 Aug 2026 17:58:28 +0700 Subject: [PATCH] docs(ci): say what the database cache key does, not what it means MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The key is hashFiles over data/**, parser/** and datasets.json, so it invalidates by path. Both the guide and the workflow comment described it by intent instead — "a web or docs change restores the databases" — which the previous commit disproved by paying for a full 348 MB rebuild to fix a comment in datasets.json and a sentence in parser/README.md. Over-invalidating is the safe direction, and narrowing the globs would mean remembering to extend them for every future path that can change a database. Record the trade rather than making it. --- .github/workflows/deploy-pages.yml | 9 +++++++-- docs/deployment-guide.md | 15 ++++++++++----- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml index 50eb934..3d6ced3 100644 --- a/.github/workflows/deploy-pages.yml +++ b/.github/workflows/deploy-pages.yml @@ -99,8 +99,13 @@ jobs: # Parsing 348 MB of spreadsheets is the slowest part of the job, and its # output is a pure function of the inputs in the key: the source files, # the parser (schema, transforms, configs) and the registry the row-count - # and size guards read. Anything else — web code, docs, workflow — cannot - # change a database, so those pushes restore one instead of rebuilding. + # and size guards read. A push touching none of them — web code, docs/, + # this workflow — restores a database instead of rebuilding one. + # + # The key is by path rather than by meaning, so it over-invalidates: a + # comment in datasets.json or a word in parser/README.md pays for a full + # rebuild. Narrowing the globs would trade minutes on a docs push for + # having to remember every future path that can change a database. # # Exact matches only, with no restore-keys: a near-miss here would mean # publishing a database built from different inputs than the commit says. diff --git a/docs/deployment-guide.md b/docs/deployment-guide.md index 40935ed..81ff3ca 100644 --- a/docs/deployment-guide.md +++ b/docs/deployment-guide.md @@ -27,11 +27,16 @@ pull-request run cancel an in-flight `main` deploy while every check stayed green. The database build dominates the runtime: roughly 348 MB of Excel to parse. It -is cached in Actions, keyed on `data/**`, `parser/**` and `datasets.json`, so -only a change to the sources, the parser or the registry pays for it — a web or -docs change restores the databases instead. There are no `restore-keys`: a -near-miss would publish databases built from inputs the commit does not -describe. +is cached in Actions, keyed on `data/**`, `parser/**` and `datasets.json`, so a +push that touches none of those — web code, `docs/`, the workflow — restores the +databases instead of rebuilding them. There are no `restore-keys`: a near-miss +would publish databases built from inputs the commit does not describe. + +The key is by path, not by what the change means, so it over-invalidates: a +comment in `datasets.json` or a word in `parser/README.md` costs a full rebuild +though neither can move a row. That is the safe direction to be wrong in, and +narrowing the globs would mean remembering to extend them for every future path +that *can* change a database. The cost is minutes on the occasional docs push. ## Resulting URLs