Status: Done, with open items (listed under Not yet written). The survey, the checks and the builds are done; the year rule and the holder’s name are decided, the name to be confirmed with the Foundation. Results: results.md.
This round asks how each hands-on tool prints the two values the book’s build computes today, the copyright year and the “Page last updated” date, and how a comparison of converted and published pages can treat them as expected differences (R-25 build-time values are expected differences). It also gathers evidence for the open question whether the copyright year should follow content changes rather than the build date (research area).
Terms used below:
© <%= Time.now.year %> and the “Page last
updated” line, a Git date (survey).blame.ignoreRevsFile, by convention
named .git-blame-ignore-revs. Candidate commits are the 72 commits
this round proposes for it (candidates.txt).docs-*
repositories and the Bookbinder gem, with pinned lines; every copyright
notice; and, for all 276 pages, the commit that sets “Page last updated”
today and the one it would be with the candidates skipped. Bookbinder’s
rule matches all 17 saved published pages. survey/| Page | Repository | Published date | Content date (candidates skipped) | Cases |
|---|---|---|---|---|
access-control, whole page |
cloudfoundry/docs-services | 2026-07-09 | 2026-06-26 | the newest commit is a markup fix; the page compared word by word (headings round’s conversion) |
architecture, excerpt |
cloudfoundry/docs-loggregator | 2024-12-05 | 2024-12-05 | an old date set by a content edit; partials do not count |
using-vol-services, excerpt |
cloudfoundry/docs-dev-guide | 2026-07-21 | 2023-05-31 | a page that is only a partial call, dated by a source-only commit |
high-availability, excerpt |
cloudfoundry/docs-cloudfoundry-concepts | 2026-07-22 | 2026-06-29 | a source-only commit, then a borderline one; the site’s newest content date |
How they were chosen. Decision (this round): every page carries the
same footer, so pages were chosen for their dates: four kinds of commit
that set “Page last updated” today (a markup fix, a content edit, a
source-only change on a page that is only an include, a source-only
change followed by a borderline one), from pages earlier rounds already
converted. Only access-control is converted whole (the headings round’s
native pages), so the comparison runs on it; the other three hold the
published title and first paragraph, since the round tests the frame
around the content.
checks/buildtime.py reads a built HTML page. It needs only Python 3.
# The build-time values on a page
python3 -I checks/buildtime.py published/architecture.html
# A built page against its intent
python3 -I checks/buildtime.py BUILT.html --expect intent/expectations.txt --page architecture --mode page
# A converted page against the published page, build-time values masked (add --no-mask to see them)
python3 -I checks/buildtime.py --compare published/access-control.html BUILT.html
# Every test page of one build (run from sites/<tool>, after make build)
../../checks/check-site.sh build-build build
What it does:
©, ©,
(c) or “Copyright”, and the holder’s name after it.data-modified-date attribute, a <time
datetime> element (Docusaurus, Starlight, Antora here), a date in an
element whose class names a last-updated or source-file box (Zensical),
or a date in the text after “last updated”; and date <meta> tags.build means the year of the build) and holder; the expected date, or
none.text-diff.py does.helpers/content-date.py computes each page’s
content date from the date written in the page and, with --git, the
author date of its newest commit not in the ignore list; --write writes
it back into the page’s field, and --year prints the newest year. It
stops on a shallow clone. The sites use it for the site year and in the
history helper variant.
access-control with its published page.<tool>/CONVENTIONS.md).Each tool keeps the version of the earlier rounds.
concepts/build-time-values/
├── README.md this file
├── results.md results per tool, the copyright-year question, conventions
├── survey/ survey.py, buildtime.csv, pages.csv, candidates.txt, shas.txt, README
├── source/ the four test pages, the book's layouts and Bookbinder's files, verbatim, plus SOURCES.md
├── published/ the four published pages, as served on 2026-10-11
├── intent/ per page: <page>.md; expectations.txt (what the check reads)
├── checks/ buildtime.py, check-site.sh
├── helpers/ content-date.py, make-history.py, pages.py (writes the sites' test pages)
├── sites/ docusaurus/, zensical/, starlight/, antora/: pages, config, footer overrides, Makefile, CONVENTIONS.md
└── results/ check and history output per tool, build warnings, probes, comparison, sitemaps
Each site builds with make build and checks with make check; make
history runs the history variants; Zensical has make probe-git-plugin
and Antora make probe-dates. Build output, the history repositories
(.history/) and installed packages are ignored by git. The results in
results/ were produced from a copy of this folder built
outside the repository; Antora’s playbook reads the repository’s
worktree, so its copy was a Git repository of its own.
Decision (2026-10-11): the saved published pages stay in the repository so the checks can be rerun after the live site changes, as in earlier rounds.