Skip to content

A page and its Markdown copy state the instant their content last changed, so a second change on the same day is a newer date - #1152

Open
jmrplens wants to merge 1 commit into
mainfrom
site/copy-dates-instant
Open

jmrplens wants to merge 1 commit into
mainfrom
site/copy-dates-instant

Conversation

@jmrplens

@jmrplens jmrplens commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

The edge serves each docs page and its Markdown copy with the date their content last changed as Last-Modified. The copy stated that date as a day (Updated: 2026-11-17), and so did the footer of a page first published and last changed on the same day, so both were served as of midnight UTC. Two changes on one day then shared one Last-Modified: a client that revalidated with only If-Modified-Since after the first change got a 304 after the second and kept the old text. That covered every copy on the site and seven pages, and same-day changes do happen (start/getting-started.mdx changed twice on 2026-11-14).

What changes:

  • isoInstant in site/src/lib/date-rules.mjs writes the content date to the second in UTC (2026-11-17T10:30:31Z).
  • LastUpdated.astro: the last <time datetime> of the footer carries that instant. A page published and last changed on the same day shows one date as before, and that date's datetime is now the instant of the change instead of the day.
  • The copy's Updated: line carries the same instant, so the page and its copy get the same Last-Modified. The sitemap's <lastmod> and the structured data keep the day.
  • check-markdown-twins refuses an Updated: that is not an instant to the second, one on another day than the sitemap gives, and one that differs from the date the page's footer states.
  • generate_llms.py measures the longer Updated: line as a dated line, so where a shard is cut still does not depend on the dates. make llms writes the same files as before.

The docs-edge Worker already reads a full ISO date-time from both places, so it needs no change.

Checks run locally: test:agent-md 281/281 and test:scripts 695/695 (with a test of isoInstant), the new check-markdown-twins cases (which fail against the old checker: 43 of 51), pytest tests/test_generate_llms*.py 52/52, make llms with no drift, ruff, and a full site build followed by check:markdown-twins, check:crawl and check:structured-data.

Summary by CodeRabbit

  • Improvements
    • Updated timestamps in generated page copies now include the UTC time to the nearest second, making same-day content changes distinguishable.
    • Update timestamps are checked against the page footer and sitemap date for consistency.
    • Publication dates remain date-only.
  • Documentation
    • Clarified how publication and update dates are represented in generated documentation.

…nged, so a second change on the same day is a newer date

The edge serves a page and its Markdown copy with the date the content last
changed as their Last-Modified. The copy stated that date as a day
(`Updated: 2026-11-17`), and a page first published and last changed on the
same day stated it the same way in its footer, so both were served as of
midnight. Two changes made on one day then had the same Last-Modified: a
client that revalidated with If-Modified-Since after the first got a 304 after
the second and kept the old text. Every copy of the site was dated this way,
and seven pages besides; getting-started.mdx, for one, changed twice on
2026-11-14.

`isoInstant` in date-rules.mjs states the content date to the second in UTC
(`2026-11-17T10:30:31Z`). The footer's last `<time datetime>` carries it,
including on a page published and last changed on the same day, whose one date
stands for both, and the copy's `Updated:` line carries the same value. The
sitemap's <lastmod> and the structured data keep the day.

check-markdown-twins holds `Updated:` to an instant to the second, on the day
the sitemap gives, and equal to the date the page's footer states. The llms
generator measures the longer `Updated:` line as a dated line, so where a
shard is cut still does not depend on the dates; `make llms` writes the same
files.
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026

Copy link
Copy Markdown

Sorry @jmrplens, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 8 hours and 30 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

@github-actions github-actions Bot added site Documentation website ci Workflows, linting and developer tooling area: core Shared internals and cross-cutting code every domain depends on labels Nov 17, 2026
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Updated metadata now uses UTC timestamps with second-level precision. The site displays these timestamps, includes them in Markdown copies, and checks them against page footer metadata and sitemap dates.

Changes: Content date formatting and validation

Layer / File(s) Summary
Format and emit update timestamps
site/src/lib/date-rules.mjs, site/src/lib/agent-md/page.mjs, site/src/components/LastUpdated.astro, site/src/lib/agent-md/header.mjs, site/src/lib/agent-md/test/page.test.mjs, site/scripts/content-dates.test.mjs
The site formats update dates as UTC timestamps to the second. Page metadata, displayed dates, and related tests use this format.
Validate copy dates against page metadata
site/scripts/check-markdown-twins.mjs, site/src/lib/agent-md/test/check-markdown-twins.test.mjs
The checker requires a UTC update timestamp, checks its date against the sitemap, and checks the timestamp against the page footer. Tests cover missing or mismatched dates.
Support timestamps in generated copies
scripts/generate_llms.py, site/src/lib/agent-md/test/dump.test.mjs, tests/llms_dump.py, tests/test_generate_llms_parts.py, .github/workflows/docs.yml
The generator validates date-only Published values and second-precision Updated timestamps. Fixtures and tests use the timestamp format, and workflow comments describe the dated metadata.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Possibly related PRs

  • jmrplens/phonometry#1088: Defines the page modified-date rule that supplies the history used for the footer and Markdown Updated value.

Suggested reviewers: sourcery-ai

Merge Risk: Minimal · up to 01199

Docs pages and their Markdown copies now state the last-change time to the second in UTC, which fixes stale 304 revalidation after same-day edits. No actionable merge risk remains.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title describes the main change: a page and its Markdown copy now record the instant of their last content change, so two same-day changes get distinct timestamps. This matches the changeset (isoI…
Description check Passed The description covers the problem (same-day changes sharing a midnight Last-Modified), the changes made per file, and the validation run locally. It follows the template's What and why section and th…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title describes the main change: a page and its Markdown copy now record the instant of their last content change, so two same-day changes get distinct timestamps. This matches the changeset (isoInstant, footer datetime, Updated: line, checker changes).

Full details: Description check

Explanation

The description covers the problem (same-day changes sharing a midnight Last-Modified), the changes made per file, and the validation run locally. It follows the template's What and why section and the checklist items it reports, though it does not tick the template's checklist or name a numeric oracle for new normative computation. The change adds no new normative implementation, so the Validation section is not strictly required to name one. The description is mostly complete.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between a1968f9 and 01199bc.

Files selected for processing: 13

  • .github/workflows/docs.yml
  • scripts/generate_llms.py
  • site/scripts/check-markdown-twins.mjs
  • site/scripts/content-dates.test.mjs
  • site/src/components/LastUpdated.astro
  • site/src/lib/agent-md/header.mjs
  • site/src/lib/agent-md/page.mjs
  • site/src/lib/agent-md/test/check-markdown-twins.test.mjs
  • site/src/lib/agent-md/test/dump.test.mjs
  • site/src/lib/agent-md/test/page.test.mjs
  • site/src/lib/date-rules.mjs
  • tests/llms_dump.py
  • tests/test_generate_llms_parts.py

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

@codecov

codecov Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.35%. Comparing base (a1968f9) to head (01199bc).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1152   +/-   ##
=======================================
  Coverage   97.35%   97.35%           
=======================================
  Files         477      477           
  Lines       97722    97722           
=======================================
  Hits        95136    95136           
  Misses       2586     2586           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions

Copy link
Copy Markdown
Contributor

Numerical conformance

All 1899 conformance checks pass, across 111 domains, against 230 normative designations and 121 further published sources

1899/1899 checks pass across 111 domains, against 230 normative designations and 121 further published sources.

Used in the tables below is how much of that clause's published tolerance the deviation consumes: 100 % sits exactly on the limit, 5 % uses a twentieth of the allowance, and a dash means the clause states no two-sided tolerance for the quantity, so there is no budget to spend. It is reported and never used to decide a verdict, which is settled at full precision before any rounding.

Nothing moved: same 1899 checks, same verdicts, same numbers.

Closest to their published limit (top 5)

The rows with the least room left, so the ones a change is most likely to push over.

Standard Quantity Deviation Used
ISO/TR 17534-3:2015 Table 3 Ground-projected path length dp, m 0.005 m 100 %
DIN 4150-2:1999-06 Annex C, Example 5 KB_FTr with hammer b) in the rest hours, Formula (5) -0.005 100 %
DIN 4150-2:1999-06 Annex C, Example 8 KB_FTm over the record with the passage maxima alone -0.0005 100 %
E DIN 4150-2:2023-08 Annex B, Table B.1 KB_FTm,Zug of the metro north by Formula (5) -0.0005 100 %
Jarvis (1996) NPL CIRA(EXT) 010 Appendix B, folio 26 Volume of the coupler of the example, v = pi r^2 L -0.00000000005 m³ 100 %

Pass Tests & coverage: 367860 tests, 0 failures (all green)
Python Version Tests Failures Coverage Status
macos-latest-3.12 40880 0 97.3% Pass Passed
macos-latest-3.13 40880 0 97.3% Pass Passed
macos-latest-3.14 40880 0 97.3% Pass Passed
ubuntu-26.04-3.12 40880 0 97.4% Pass Passed
ubuntu-26.04-3.13 40880 0 97.4% Pass Passed
ubuntu-26.04-3.14 40880 0 97.4% Pass Passed
windows-latest-3.12 40860 0 97.3% Pass Passed
windows-latest-3.13 40860 0 97.3% Pass Passed
windows-latest-3.14 40860 0 97.3% Pass Passed

Full report at this commit: docs/CONFORMANCE.md · docs/conformance.json · full CI artifacts

@sonarqubecloud

Copy link
Copy Markdown

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: core Shared internals and cross-cutting code every domain depends on ci Workflows, linting and developer tooling site Documentation website

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant