Repository navigation
docs: add verified dates and registry steps - #166
Conversation
Pages with operational facts carry `last_verified` in their front matter, a date or `null` until verified, and show it at their end (override of Material's `content` partial, with a build test). The README tells contributors how to set it. About, TESK and Funnel were checked against their sources today; the TESK page now links the chart on `dev` and the S3 section of the TESK docs. Every deployment and upgrade procedure (onboarding, both tutorials, the service pages, the registry's own upgrades) now ends with updating the service's Cloud Registry entry or checking that sync did, described once in "After a deployment or an upgrade". Closes #161 Closes #162 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewer's GuideImplementationValidate
UIDisplay a page’s verified date or unverified status at the end of its content.
ConfigurationRegister the validation hook and require the Material version from which the overridden partial was copied.
DocumentationExplain the verification-date convention and how contributors should set dates and maintain the copied theme partial.
Mark About as verified and the demos index as not yet verified.
Add verification metadata and explain keeping the registry’s own entry current after upgrades.
Add unverified metadata and a registry-entry update step to the data-centre onboarding tutorial.
Mark the operators index as not yet verified.
Mark the LS Login page as not yet verified.
Add unverified metadata and a registry-entry update step to the node onboarding tutorial.
Add unverified metadata and make registry maintenance part of onboarding next steps.
Mark the service-info page as not yet verified.
Mark DRS-Filer as not yet verified.
Mark Funnel as verified and direct operators to update its unsynced registry entry after changes.
Mark the services index as not yet verified.
Mark Poiesis as not yet verified and document manual registry-entry updates after changes.
Mark proTES as not yet verified and document registry registration and maintenance.
Mark proWES as not yet verified.
Mark TESK as verified, direct operators to check registry sync, and correct the chart and S3 documentation links.
Mark TRS-Filer as not yet verified and document registry registration and sync checks.
Mark the Cloud Registry UI guide as not yet verified.
Mark the API guide as not yet verified.
Mark the researchers’ command-line guide as not yet verified.
Mark the Crypt4GH with proTES guide as not yet verified.
Mark the federated workflows guide as not yet verified.
Mark the researchers index as not yet verified.
Mark the Krini guide as not yet verified.
Mark the command-line tutorial as not yet verified.
Mark the Krini tutorial as not yet verified.
Mark the interactive TES services tutorial as not yet verified.
TestsTest that the hook accepts absent, null, and date metadata, rejects malformed values, and catches unreadable front matter.
Build a small MkDocs site to check verified and unverified notes, unchanged pages, and build failures for malformed dates.
Include the new hook in the project’s coverage requirements.
Other changesFiles not grouped.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Documentation build overview
28 files changed ·
|
There was a problem hiding this comment.
Hey - I've found 4 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="README.md" line_range="119" />
<code_context>
(where `CI` or `READTHEDOCS` is set), so published builds always show
the services.
+### Last verified dates
+
</code_context>
<issue_to_address>
**Concurrent edits misstate verification**
When a verification change and a separate facts edit to the same page are merged without rechecking the combined result, a verification change and a separate operational-facts edit to the same page can merge cleanly when they touch different lines; the resulting page keeps a date that verifies the old facts, so readers see stale information presented as checked.
Require rechecking the page after merging concurrent changes to its operational facts, or otherwise invalidate the date when those facts change.
</issue_to_address>
### Comment 2
<location path="docs/operators/using-cloud-registry.md" line_range="203-204" />
<code_context>
+ the entry shows the new values, e.g., the version, with the label
+ `synced`. If it shows `out-of-sync`, see [Out-of-sync
+ reasons](#out-of-sync-reasons).
+- **Without sync** (a manual entry, e.g., of Funnel or Poiesis): edit the
+ entry by hand, so that it matches the service again.
+- **A new URL or API type:** with sync on, the URL can't change (see
+ [Labels](#labels)), and a new API type needs a new entry. Either change
</code_context>
<issue_to_address>
**Obsolete service entry stays listed**
When a service changes to a new API type and operators follow the instruction to create a new entry, the new API-type path registers a replacement entry but never retires the old one; when sync detects the type mismatch, the registry keeps the old values listed, so users see a stale entry alongside the replacement.
Tell operators to delete or otherwise retire the old entry when creating the replacement, then request verification for the new entry.
</issue_to_address>
### Comment 3
<location path="overrides/partials/content.html" line_range="19" />
<code_context>
+ <span class="md-icon" title="Operational facts verified against their sources">
+ {% include ".icons/material/calendar-check-outline.svg" %}
+ </span>
+ {% if page.meta.last_verified %}
+ Facts last verified on
+ <time datetime="{{ page.meta.last_verified }}">{{ page.meta.last_verified }}</time>
</code_context>
<issue_to_address>
**Invalid dates appear verified**
When a page's front matter contains a non-null malformed `last_verified` value, `page.meta.last_verified` passes the truthiness check, so the partial writes the malformed value into the `<time>` element and visitors see an invalid verification date.
Validate `last_verified` as `YYYY-MM-DD` or null and fail the build for any other value.
</issue_to_address>
### Comment 4
<location path="README.md" line_range="98-99" />
<code_context>
+### Last verified dates
+
+Pages with operational facts that can't be generated, such as onboarding
+steps, access procedures, addresses, versions and contacts, say when
+someone last checked those facts against their sources. Their front matter
+holds the date, which the page shows at its end (see
</code_context>
<issue_to_address>
**Operational guides lack verification status**
When an operational guide such as the CLI or Krini guide has no `last_verified` key, the content override renders no verification state for that page, so readers cannot distinguish unchecked or stale instructions from checked content.
Add `last_verified` to the front matter of operational guides, using `null` until their facts have been verified.
</issue_to_address>Sourcery assessment
Approval pending. 4 findings to address first.
Blocking findings: README.md:119, docs/operators/using-cloud-registry.md:204, overrides/partials/content.html:19, README.md:99
Address the Sourcery review: a hook fails the build on malformed `last_verified` values (anything but an unquoted date or null), with unit and build tests. The researchers' guides, the API guide and the demos index get `last_verified: null`. The README says that a pull request setting a date verifies the page as on `main`, and the registry section says to delete an entry replaced after an API type change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An impossible date such as 2026-13-01 makes YAML fail, and MkDocs then drops the whole front matter silently; the hook now fails the build when unread front matter sets `last_verified`. Build tests cover the values YAML reads differently (datetimes, unpadded dates) and check the hook's message. Also from the review: the partial names the Material version it was copied from, the README lists the pages that carry the key and says it is a convention, and the registry section tells a new API version (synced into the same entry) from another API (a new entry). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The copy of Material's `content` partial comes from 9.8.1, so require that version at least. Clarify that the `last-verified` class has no styles, and list the interactive services tutorial among the pages with the key. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Summary
#161, last verified dates
last_verifiedin their front matter: a date (YYYY-MM-DD), ornulluntil someone has verified them. An override of Material'scontentpartial (overrides/partials/content.html, a copy of the partial, associal.htmlis) shows "Facts last verified on " or "Facts not verified yet" at the end of the page.hooks/last_verified.pyfails the build on anything but an unquoted date ornull. That includes impossible dates such as2026-13-01, where MkDocs would otherwise drop the whole front matter silently. It has unit and build tests.mkdocs-materialnow needs at least 9.8.1, the release the partial was copied from.elixir-cloud-aai/.github(SUPPORT.md, CONTRIBUTING.md, code of conduct, security policy), the website and the GA4GH Driver Projects page.dev: chart valuesstorage,storageClass,serviceInfo,transfer) anddocs/deployment.md(ReadWriteOnce, S3, OpenShift, Minikube). Two fixes came out of this: the chart link pointed tomaster, which no longer exists (GitHub redirects it todev), and S3 was said to be in the chart's README, which doesn't cover it (it's in the TESK docs, Deployment > S3).development, PBS backendqsub/qdel/qstat -xXML, reconciler off by default, template variables includingArgs), Configurable service info (id, environment, organization) calypr/funnel#1493 still open, docs site up.main, and that the partial must be compared with each new Material release.nullas stale.#162, registry update at the end of deployments
operators/using-cloud-registry.md:Not light lane: the build hook (added after the Sourcery review) is real logic. Two rounds of adversarial and quality review ran. All four Sourcery threads are fixed, answered and resolved.
ci.ymlis unchanged: itsTestjob comment still names only the two older tested files, which is left for the follow-up.How it was verified
python scripts/check_names.py: passedmkdocs build --strict: passed (with the live registry)pytest: 143 passed, coverage 100% (includinghooks/last_verified.py).tests/unit/test_last_verified.pycovers the hook.tests/integration/test_last_verified_build.pybuilds sites with the overrides and the hook. It checks the dated, thenulland an unmarked page, plus seven malformed values as YAML reads them.site/about/shows the date,site/operators/onboarding/shows "Facts not verified yet".Declined review findings
Findings while verifying (out of scope)
Nothing here blocks this PR. These pages stay "not verified yet" until someone settles the points below:
GET https://poiesis.dyn.cloud.e-infra.cz/ga4gh/tes/v1/service-infoanswers503, but the page says it "runs".0.5.1.dev13+gfa501e6dcand TRS2.0.2. The page says writes need LS Login tokens, but the data-centre tutorial says 0.5.0 has no authentication of writes and reportstrs2.0.1. I couldn't check writes with a plain GET.csc-tesk-noauth.rahtiapp.fi) match, andGET /taskswithout a token gives401. The group rule (ECP_CLN:EOC-Compute) can't be checked without a token. Its service info saysenvironment: testand "proTES sandbox (BioHackathon 2026)".J0LBQG) looks like a manual registration, not the self-listing (ELIXIR_CLOUD_SERVICE_REGISTRY_1) thatcloud-registry.mddescribes.🤖 Generated with Claude Code