Skip to content

docs: add verified dates and registry steps - #166

Merged
uniqueg merged 4 commits into
mainfrom
docs/161-last-verified
Nov 17, 2026
Merged

uniqueg merged 4 commits into
mainfrom
docs/161-last-verified

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

#161, last verified dates

  • Pages with operational facts carry last_verified in their front matter: a date (YYYY-MM-DD), or null until someone has verified them. An override of Material's content partial (overrides/partials/content.html, a copy of the partial, as social.html is) shows "Facts last verified on " or "Facts not verified yet" at the end of the page.
  • 28 fact pages got the key:
    • the operator pages (index, onboarding, both tutorials, Cloud Registry, using the registry and its UI, service info, LS Login) and the service pages
    • the researchers' start page and guides, and the interactive services tutorial
    • the API guide, the demos index and About
  • The hook hooks/last_verified.py fails the build on anything but an unquoted date or null. That includes impossible dates such as 2026-13-01, where MkDocs would otherwise drop the whole front matter silently. It has unit and build tests.
  • mkdocs-material now needs at least 9.8.1, the release the partial was copied from.
  • Only three are dated (2026-11-17), because only their facts were checked against their sources:
    • About: the contact and contributing guides in elixir-cloud-aai/.github (SUPPORT.md, CONTRIBUTING.md, code of conduct, security policy), the website and the GA4GH Driver Projects page.
    • TESK: the TESK repo (dev: chart values storage, storageClass, serviceInfo, transfer) and docs/deployment.md (ReadWriteOnce, S3, OpenShift, Minikube). Two fixes came out of this: the chart link pointed to master, which no longer exists (GitHub redirects it to dev), and S3 was said to be in the chart's README, which doesn't cover it (it's in the TESK docs, Deployment > S3).
    • Funnel: Funnel v0.12.3 (default service info environment development, PBS backend qsub/qdel/qstat -x XML, reconciler off by default, template variables including Args), Configurable service info (id, environment, organization) calypr/funnel#1493 still open, docs site up.
  • The other 25 say "not verified yet". The facts I could check there were partly wrong or couldn't be checked by plain GETs (see "Findings while verifying").
  • README: a "Last verified dates" note for contributors. It says which pages carry the key, that a PR setting a date verifies the page as it is on main, and that the partial must be compared with each new Material release.
  • The weekly job that lists stale pages (second half of docs: add "last verified" dates to fact pages #161) is not in this PR, to keep out of the CI work of ci: check service URLs against the registry #159/ci: flag mentions of archived repositories #160. A follow-up issue is drafted for it. It treats null as stale.

#162, registry update at the end of deployments

  • New section "After a deployment or an upgrade" in operators/using-cloud-registry.md:
    • With sync on: sync and check the entry.
    • Without sync (Funnel, Poiesis): edit the entry.
    • A new API version: sync applies it to the same entry once an admin has approved it.
    • A new URL or another API: needs verification again, and a replaced entry is deleted.
    • A service that is taken down: its entry is deleted.
  • Every deployment or upgrade procedure ends with that step and links to the section:
    • onboarding (new step 4)
    • the Node tutorial (new step 9, plus the manual-upgrade note of step 8)
    • the data-centre tutorial (new step 7)
    • the TESK, Funnel, Poiesis, proTES and TRS-Filer pages
    • the Cloud Registry's own Upgrades section (the self-listing updates itself at app start; a manually registered entry has to be edited)
  • proWES and DRS-Filer have no deployment procedure yet (being revived), so they're left alone.

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.yml is unchanged: its Test job 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: passed
  • mkdocs build --strict: passed (with the live registry)
  • pytest: 143 passed, coverage 100% (including hooks/last_verified.py).
    • tests/unit/test_last_verified.py covers the hook.
    • tests/integration/test_last_verified_build.py builds sites with the overrides and the hook. It checks the dated, the null and an unmarked page, plus seven malformed values as YAML reads them.
    • The tests failed before the code and pass after it.
  • Built pages checked: site/about/ shows the date, site/operators/onboarding/ shows "Facts not verified yet".
  • CI on df728a4: all checks passed (PR title, Docs, Test, CI passed, CodeQL, Read the Docs preview). Sourcery approved.

Declined review findings

  • Require the key on pages by path (quality review): declined. Which pages hold operational facts is a judgement call, so the README says it's a convention.
  • Split the TESK link fixes out (quality review): declined. They came out of verifying that page, which this PR dates.

Findings while verifying (out of scope)

Nothing here blocks this PR. These pages stay "not verified yet" until someone settles the points below:

  • Poiesis: GET https://poiesis.dyn.cloud.e-infra.cz/ga4gh/tes/v1/service-info answers 503, but the page says it "runs".
  • TRS-Filer: the live service reports version 0.5.1.dev13+gfa501e6dc and TRS 2.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 reports trs 2.0.1. I couldn't check writes with a plain GET.
  • proTES: address, version 0.6.0 and the one configured TES service (the CSC TESK, csc-tesk-noauth.rahtiapp.fi) match, and GET /tasks without a token gives 401. The group rule (ECP_CLN:EOC-Compute) can't be checked without a token. Its service info says environment: test and "proTES sandbox (BioHackathon 2026)".
  • Registry entries: neither proTES nor TRS-Filer is in the registry (it lists 4 services). The registry's own entry (J0LBQG) looks like a manual registration, not the self-listing (ELIXIR_CLOUD_SERVICE_REGISTRY_1) that cloud-registry.md describes.

🤖 Generated with Claude Code

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>
@uniqueg uniqueg self-assigned this Nov 17, 2026
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Implementation

Validate last_verified front matter, including malformed YAML dates that MkDocs silently drops, and fail the build with a page-specific error.

  • hooks/last_verified.py L1-61

UI

Display a page’s verified date or unverified status at the end of its content.

  • overrides/partials/content.html L1-33

Configuration

Register the validation hook and require the Material version from which the overridden partial was copied.

  • mkdocs.yml L136-141
  • pyproject.toml L24

Documentation

Explain the verification-date convention and how contributors should set dates and maintain the copied theme partial.

  • README.md L96-130

Mark About as verified and the demos index as not yet verified.

  • docs/about.md L2
  • docs/demos/index.md L1-4

Add verification metadata and explain keeping the registry’s own entry current after upgrades.

  • docs/operators/cloud-registry.md L1-4, L1762-1769

Add unverified metadata and a registry-entry update step to the data-centre onboarding tutorial.

  • docs/operators/data-centre-onboarding-tutorial.md L1-4, L316-324

Mark the operators index as not yet verified.

  • docs/operators/index.md L1-4

Mark the LS Login page as not yet verified.

  • docs/operators/ls-login.md L1-4

Add unverified metadata and a registry-entry update step to the node onboarding tutorial.

  • docs/operators/node-onboarding-tutorial.md L1-4, L460-480

Add unverified metadata and make registry maintenance part of onboarding next steps.

  • docs/operators/onboarding.md L1-4, L111-122

Mark the service-info page as not yet verified.

  • docs/operators/service-info.md L1-4

Mark DRS-Filer as not yet verified.

  • docs/operators/services/drsfiler.md L1-4

Mark Funnel as verified and direct operators to update its unsynced registry entry after changes.

  • docs/operators/services/funnel.md L1-4, L15-17

Mark the services index as not yet verified.

  • docs/operators/services/index.md L1-4

Mark Poiesis as not yet verified and document manual registry-entry updates after changes.

  • docs/operators/services/poiesis.md L1-4, L14-17

Mark proTES as not yet verified and document registry registration and maintenance.

  • docs/operators/services/protes.md L1-4, L19-22

Mark proWES as not yet verified.

  • docs/operators/services/prowes.md L1-4

Mark TESK as verified, direct operators to check registry sync, and correct the chart and S3 documentation links.

  • docs/operators/services/tesk.md L1-4, L14-17 (+2 small edits)

Mark TRS-Filer as not yet verified and document registry registration and sync checks.

  • docs/operators/services/trsfiler.md L1-4, L14-18

Mark the Cloud Registry UI guide as not yet verified.

  • docs/operators/using-cloud-registry-ui.md L1-4

Mark the API guide as not yet verified.

  • docs/partners-and-developers/apis.md L1-4

Mark the researchers’ command-line guide as not yet verified.

  • docs/researchers/cli.md L1-4

Mark the Crypt4GH with proTES guide as not yet verified.

  • docs/researchers/crypt4gh-with-protes.md L1-4

Mark the federated workflows guide as not yet verified.

  • docs/researchers/federated-workflows.md L1-4

Mark the researchers index as not yet verified.

  • docs/researchers/index.md L1-4

Mark the Krini guide as not yet verified.

  • docs/researchers/krini.md L1-4

Mark the command-line tutorial as not yet verified.

  • docs/researchers/tutorial-cli.md L1-4

Mark the Krini tutorial as not yet verified.

  • docs/researchers/tutorial-krini.md L1-4

Mark the interactive TES services tutorial as not yet verified.

  • docs/tutorials/tes-services/interactive_services_tes.md L1-4

Tests

Test that the hook accepts absent, null, and date metadata, rejects malformed values, and catches unreadable front matter.

  • tests/unit/test_last_verified.py L1-77

Build a small MkDocs site to check verified and unverified notes, unchanged pages, and build failures for malformed dates.

  • tests/integration/test_last_verified_build.py L1-121

Include the new hook in the project’s coverage requirements.

  • pyproject.toml L28-29, L42

Other changes

Files not grouped.

  • docs/operators/using-cloud-registry.md L1-4, L191-217

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@read-the-docs-community

read-the-docs-community Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

@uniqueg
uniqueg marked this pull request as ready for review November 17, 2026 09:24

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread README.md Resolved
Comment thread docs/operators/using-cloud-registry.md Resolved
Comment thread overrides/partials/content.html Resolved
Comment thread README.md Resolved
uniqueg and others added 3 commits November 17, 2026 10:35
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>

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sourcery assessment

Approved.

@uniqueg
uniqueg merged commit af13108 into main Nov 17, 2026
21 checks passed
@uniqueg
uniqueg deleted the docs/161-last-verified branch November 17, 2026 09:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant