cf-docs-rfc-proposal

Concept: Copyright and build-time values

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:

Progress

Test pages

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.

Build-time values check

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:

Content-date helper

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.

Method

  1. Survey where the book computes values at build time and how, and date every page by the book’s rule.
  2. Choose pages for the kinds of commit that date them today.
  3. Write the intent: the year and date each mode must show.
  4. Configure each tool for the three year modes and the date written in the page; build a repository with known dates to test each tool’s own Git-based date, the helper, a shallow clone and, in Docusaurus, a lookup that skips commits.
  5. Check every build with the build-time values check, and compare access-control with its published page.
  6. Record conventions per tool (sites/<tool>/CONVENTIONS.md).

Each tool keeps the version of the earlier rounds.

Layout

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.