cf-docs-rfc-proposal

Build-time value survey

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

A build-time value is a value on a published page that the build computes instead of reading it from the page’s source: today the copyright year in the footer and the “Page last updated” date. This survey finds every place the book and its 15 cloudfoundry/docs-* repositories set or print one, records the copyright notices written in the repositories, and finds, for every page of the book, the commit that sets its “Page last updated” date. It was done on 2026-10-11 for the build-time values round (R-25 build-time values are expected differences).

File What it is
buildtime.csv 41 rows: each place a value is set or printed at build time, and each copyright notice, with a link to the line
pages.csv 276 rows, one per page of the 12 book repositories: the commit that sets “Page last updated” today, the commit it would be with the candidate commits skipped, and, for the 17 pages saved by this and earlier rounds, whether the published date matches
candidates.txt 72 commits whose subject says they change markup only, or remove content the open-source book did not render; in the format of Git’s blame.ignoreRevsFile
shas.txt The 15 repositories and the commit surveyed in each: the partial survey’s list
survey.py Writes the three files above and prints the counts below

Scope

How the book sets build-time values

  1. The copyright year is the build’s year. The book’s footer writes &copy; <%= Time.now.year %> Cloud Foundry Foundation. All Rights Reserved. (_book-footer.erb L3). It is the only ERB expression in the 15 repositories and the book that reads the clock (buildtime.csv, kind erb-time).
  2. “Page last updated” is a Git date. Before every page’s content the book’s layout prints Bookbinder’s modified_date, unless the page’s front matter says modified_date: false (_pre-content.erb L1-L3). No page says so (no front-matter row in buildtime.csv).
  3. The date is the author date of the newest commit to the page’s own file. modified_date asks page_last_modified_date, which asks the Git accessor for the page’s source file (bookbinder_helpers.rb L85-L91, L159-L169). The accessor walks up to the folder that holds .git, lists the file’s log, and returns the author date of the first commit whose message does not contain [exclude] (git_accessor.rb L57-L84). The log is ruby-git’s, whose default length is 30 commits (object.rb L62 at v1.2.8, the same line at v1.2.9.1; Bookbinder requires git ~> 1.2.8, gemspec L29). Partials and variables the page uses do not count, and renames are not followed.
  4. The rule matches every saved published page. For all 17 pages saved by this round and earlier ones, the published date equals the date the rule gives at the surveyed commits (pages.csv, column published_date_matches). Two of them are dated by a merge commit, whose result differed from both parents: git log -- <file> lists such merges (542bfd4).
  5. The date is drawn in the reader’s browser, in the reader’s time zone. The page holds milliseconds since 1970 in a data-modified-date attribute (bookbinder_helpers.rb L90); a script writes “Dec 5, 2024” with the browser’s local date (bookbinder.js L39-L44, L89-L95). The static HTML says “Page last updated:” with no date, as the headings round’s text comparison showed (text diff). So readers in different time zones can see different dates: architecture’s 2024-12-05T22:18:28Z gives day 6 of month 12 with the JavaScript Date getters the script uses, run under TZ=Asia/Tokyo in Node (checked 2026-10-11), and day 5 under TZ=America/Los_Angeles.
  6. [exclude] exists, and was used once per repository, in 2015. The nine commits whose message holds it are all “Adding last mod date [exclude]”, 2015-12-03: the commits that added the date line (for example docs-buildpacks 89090b9). No commit since uses it, including the July 2026 markup commits below.

What else on the published pages is set at build or serve time

Observed on the pages fetched on 2026-10-11 (../published/):

The dates of today’s pages

Counts from pages.csv (printed by survey.py):

Year of “Page last updated” 2023 2024 2025 2026
Today (Bookbinder’s rule) 40 26 13 197
With the candidate commits skipped 52 62 34 128

The candidate list

Decision (this round): the candidates are the 2026 commits whose subject matches markup-only or not-rendered changes (the regular expression CANDIDATE in survey.py: closing </p> tags, note__title spans, Redcarpet HTML blocks, “naked Markdown”, a name to a id, platform-conditional or commercial-only ERB, blank lines, trailing newlines, notes converted to HTML). They are candidates for the Docs WG to review, not a decision that they changed no content:

How to rerun

Run from a working directory outside this repository, with python3 -I. SURVEY stands for this folder, concepts/build-time-values/survey, and CONCEPTS for concepts/.

# The 15 repositories at their commits, as in the partial survey
# (its README, "How to rerun"), into repos/

# Full histories of the 12 book repositories (blobless is enough)
mkdir -p hist
git clone -q --bare --filter=blob:none https://github.com/cloudfoundry/docs-bbr.git hist/docs-bbr.git
# … the same for each book repository in SURVEY/shas.txt

# The bookbindery 9.12.1 gem, unpacked
mkdir -p gem && curl -fsSL -o gem/bb.gem https://rubygems.org/downloads/bookbindery-9.12.1.gem
tar -xf gem/bb.gem -C gem && mkdir gem/src && tar -xzf gem/data.tar.gz -C gem/src

python3 -I SURVEY/survey.py repos hist SURVEY/shas.txt gem/src \
  CONCEPTS/headings/published CONCEPTS/notes/published CONCEPTS/partials/published \
  CONCEPTS/variables/published CONCEPTS/build-time-values/published -o out
cmp out/pages.csv SURVEY/pages.csv && cmp out/candidates.txt SURVEY/candidates.txt

The script reads files and runs git log and git ls-tree only; it runs nothing from the clones or the gem.