cf-docs-rfc-proposal

Build-time values round — results

Status: draft, incomplete — covers what is known as of 2026-10-11.

What each tool did with the copyright year and the “last updated” date. A summary across tools comes first, then one section per tool, then what the tools share, the open question about the copyright year, and the conventions to record. How the pages were chosen and what the terms mean: README. How the book sets these values today: survey.

How to read the results:

All builds ran on 2026-10-11 with the earlier rounds’ tool versions (Docusaurus 3.10.2, Zensical 0.0.69, Starlight 0.42.6, Antora 3.2.1).

Summary

Every tool prints a copyright notice with any of the three years, and every tool shows a “last updated” date written in the page. They differ in how much code the footer needs and in whether the tool reads dates from Git; where it does, the date is the conversion commit’s.

  Docusaurus Zensical Starlight Antora
Check, build / site / page 4 of 4 each 4 of 4 each 4 of 4 each 4 of 4 each
Footer year from the build config (JavaScript) not in the tool: make writes the year into a copy of the config footer component override (Astro) the default UI’s year helper, in a replaced footer template
Footer year from the site’s content SITE_YEAR read by the config the same config copy SITE_YEAR in the override {{env.SITE_YEAR}} in the template
Year per page a wrapped theme component (React) the copyright template reads revision_date the same override reads the page’s date the template, plus a one-line helper
Date written in the page last_update.date revision_date lastUpdated :page-last-updated: and the template
Date from Git, by the tool committer date; production builds only none (the MkDocs plugin is dropped without a message) committer date none
History, native 0 of 4: conversion or newest commit 0 of 4: no date 0 of 4: conversion or newest commit 0 of 4: no date
History, helper 4 of 4 4 of 4 4 of 4 4 of 4
Shallow clone every page dated by the newest commit — every page dated by the newest commit —
Skip listed commits with a custom VCS (experimental API): 1 of 4, no rename following — no —
Sitemap lastmod none by default none not tested (build warnings) the build time, on every page

Docusaurus 3.10.2

Site: sites/docusaurus/ — conventions: CONVENTIONS.md.

Summary

Grid

Mode access-control architecture using-vol-services high-availability
build, site, page ok ok ok ok
history, native 2026-10-07 (C6, committer date) 2026-10-01 (C5) 2026-10-01 (C5) 2026-10-01 (C5)
history, helper ok ok ok ok
history, shallow 2026-10-07 2026-10-07 2026-10-07 2026-10-07
history, vcs ok no date no date no date

“ok” is the check: the year, the holder and the date as the intent says (check, history).

Zensical 0.0.69

Site: sites/zensical/ — conventions: CONVENTIONS.md.

Summary

Grid

Mode access-control architecture using-vol-services high-availability
build, site, page ok ok ok ok
history, native no date no date no date no date
history, helper ok ok ok ok

(check, history)

Starlight 0.42.6

Site: sites/starlight/ — conventions: CONVENTIONS.md.

Summary

Grid

Mode access-control architecture using-vol-services high-availability
build, site, page ok ok ok ok
history, native 2026-10-07 (C6, committer date) 2026-10-01 (C5) 2026-10-01 (C5) 2026-10-01 (C5)
history, helper ok ok ok ok
history, shallow 2026-10-07 2026-10-07 2026-10-07 2026-10-07

(check, history)

Antora 3.2.1

Site: sites/antora/ — conventions: CONVENTIONS.md.

Summary

Grid

Mode access-control architecture using-vol-services high-availability
build, site, page ok ok ok ok
history, native no date no date no date no date
history, helper ok ok ok ok

(check, history)

Across tools

Conversion resets every Git date

The RFC moves all content into one repository (L69) and converts it centrally (L131). A Git-based date then needs the history before the conversion, and it needs Git to connect each converted file to its old one:

So the dates that exist today can reach the converted pages in two ways: the converter writes each page’s date into the page (all four tools show it), or the converted files keep a Git history that the build follows. Only the first was made to work here in every tool.

Author date and committer date

Bookbinder uses the author date (git_accessor.rb L81); Docusaurus and Starlight use the committer date. They differ when a commit is rebased or cherry-picked: C6’s author date is 2026-10-05 and its committer date 2026-10-07. Decision (this round): the helper uses the author date, as Bookbinder does.

Time zones

Comparing converted and published pages

R-25 build-time values are expected differences: buildtime.py --compare lists the copyright year and the date of both pages, then compares the main text without them (comparison):

The open question (research area). This section lays out observations for each answer. It is not legal advice; the Docs WG may want the Cloud Foundry Foundation’s view, as the research area says.

What the book does today

The footer prints the build’s year, “© 2026 Cloud Foundry Foundation” (_book-footer.erb L3). The repositories’ NOTICE files say “YYYY-Present”, with first years from 2013 to 2019 (survey). Under the RFC, every merge rebuilds and redeploys the site (L83), so a build-year footer changes year with the first merge of each year.

The answers, with what was observed

Answer What the footer says Observed elsewhere What this round found
A. The build’s year (today) the year of the newest deploy kubernetes.io: © {{ now.Year }}, Hugo’s current time (center.html L1-L2); Docusaurus’s site template (L149); cloudfoundry.org’s footer shows “©2026” (fetched 2026-10-11) works in all four tools; a format-only rebuild in a new year changes the year; builds differ by date alone, so a comparison must mask it
B. The newest content year on the site the year of the newest content date Sphinx replaces %Y with the current year, or with SOURCE_DATE_EPOCH’s year when that is set, citing the Reproducible Builds specification (config.py L694-L723) works in all four tools with the helper; it needs a decision about which commits are content (the candidate list) and a full history or dates in the pages; in 2026 it equals A
C. Each page’s content year a year per page, with its date not seen on the sites checked works in all four tools; costs code in Docusaurus (a theme component) and Starlight (an override), a template in Zensical and Antora; years range 2023–2026 on the test pages
D. The first year, or a range to “Present” for example “© 2015–Present” or “© 2001” docs.python.org: “© Copyright 2001 Python Software Foundation”, and a separate build time, “Last updated on Oct 11, 2026” (fetched 2026-10-11; conf.py L74); the repositories’ NOTICE files a fixed string: no build-time value at all, nothing to mask
E. No year for example “Copyright The Cloud Foundry Authors” CNCF recommends notices without years for contributions to its projects, to avoid “years or ranges of years” (copyright-notices.md L19-L38) a fixed string

Public statements that bear on the question:

Observations from this round’s data:

Decision (Docs WG lead, 2026-10-11): B, the newest content year on the site, computed by the same helper that sets page dates, so a format-only conversion never moves the year; D if the Foundation prefers a fixed notice.

Conventions to record

For cf-docs-migrate convert and the site build. Decisions of this round, for review:

  1. Comparisons of converted and published pages mask build-time values: the copyright notice, “last updated” dates (as text, as <time datetime>, as Bookbinder’s data-modified-date), and date <meta> tags, listed apart as expected differences: checks/buildtime.py --compare (R-25 build-time values are expected differences).
  2. Every converted page carries its content date in the page, in the tool’s own field: last_update.date (Docusaurus), revision_date (Zensical), lastUpdated (Starlight), :page-last-updated: (Antora). The converter writes it once, from the page’s history before conversion.
  3. The date written by the converter is Bookbinder’s rule, the author date of the newest commit to the page’s file, except commits the Docs WG lists as not content (convention 4). Partials do not move a page’s date, as today. Amended (Docs WG lead, 2026-10-11): a page whose text is all in a partial (its file holds only the call) takes the newer of the two dates. using-vol-services is such a page: its file’s date is 2023-05-31, its partial’s 2025-03-27 with the candidates skipped. content-date.py does this with --git: a page whose body holds only include calls, in any of the four tools’ forms, also takes its partials’ dates (test-content-date.py). On the round’s history repositories it prints the same dates as before.
  4. Commits that are not content are listed in .git-blame-ignore-revs in the docs repository: the conversion commits, and bulk markup commits after review of candidates.txt. Git (blame.ignoreRevsFile) and GitHub’s blame view (GitHub Docs) read the same file. Accepted (Docs WG lead, 2026-10-11): the central migration team reviews the list once before conversion; the Docs WG owns it afterwards.
  5. Before each build, the date is brought up to date from Git by one shared script (content-date.py --write): the later of the written date and the newest listed-not-skipped commit. The tools’ own Git lookups are not relied on. Decision (Docs WG lead, 2026-10-11): compute the date at build first; whether the updated dates are also committed is decided after the proof of concept.
  6. The build fetches the full history, and the script stops on a shallow clone (fetch-depth: 0 for actions/checkout).
  7. Dates and years are computed in UTC, and dates are shown as calendar dates.
  8. The copyright year comes from one setting (YEAR_MODE: build, site or page), so the decision on the open question changes one value. Which value is the open question (above). Set to site, answer B (Docs WG lead, 2026-10-11).
  9. A sitemap’s lastmod is the content date or absent, never the build time (R-20 search-engine and AI-friendly output): Antora’s default does not meet this; Docusaurus’s sitemap plugin can take the content date (lastmod option), not tested.
  10. The build-time values check runs on every converted page: one notice, with the expected year and holder, and the expected date: checks/buildtime.py --expect.

Requirements

Not yet written