Enforce canonical RFC timestamp format and improve listing table display#150
Merged
Conversation
rcantin-w
changed the title
Contributor
There was a problem hiding this comment.
Pull request overview
This PR tightens and automates RFC hygiene across the repo by introducing a strict RFC README validator, standardising RFC “Last modified” timestamps to a canonical ISO 8601 UTC offset format, and regenerating the RFC listing table with human-readable dates.
Changes:
- Add
.scripts/validate_rfc.pyand CI/pre-commit wiring to enforce RFC README title,## Purpose, and canonical**Last modified:** YYYY-MM-DDTHH:MM:SS+00:00. - Refactor
.scripts/create_table_summary.pyto regeneraterfcs/README.mdwith Purpose-derived summaries and human-readable last-modified dates, plus--write-readme/--check-readme. - Update RFC documents and docs/README to match the new conventions; remove an unused shell helper script.
Reviewed changes
Copilot reviewed 93 out of 93 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| rfcs/README.md | Documents required RFC sections and adds automation/validation workflow; updates generated RFC listing table. |
| rfcs/087-kiosk-mode/README.md | Adds ## Purpose and canonical Last modified. |
| rfcs/086-item-viewer-refactor/README.md | Normalises RFC title, adds ## Purpose, canonical Last modified. |
| rfcs/084-shopify-integration-strategies/README.md | Normalises RFC title, adds ## Purpose, canonical Last modified. |
| rfcs/083-stable_identifiers/README.md | Adds ## Purpose. |
| rfcs/082-curated-collections-prismic/README.md | Adds ## Purpose and canonical Last modified. |
| rfcs/081-identifiers-in-iiif-builder/README.md | Adds ## Purpose; canonicalises Last modified seconds. |
| rfcs/080-pipeline-failures/README.md | Adds ## Purpose; canonicalises Last modified; heading level tweak. |
| rfcs/079-new-online/README.md | Normalises RFC title; adds ## Purpose; canonicalises Last modified. |
| rfcs/078-name-reconciliation-service/README.md | Adds ## Purpose; canonicalises Last modified seconds/spacing. |
| rfcs/077-enriching-addressables-with-works/README.md | Adds ## Purpose. |
| rfcs/076-catalogue-api-knowledge-graph/README.md | Adds ## Purpose; canonicalises Last modified. |
| rfcs/075-updated_adapters/README.md | Adds ## Purpose; canonicalises Last modified. |
| rfcs/074-offsite-item-requesting/README.md | Adds ## Purpose; converts timestamp to UTC +00:00; heading level tweak. |
| rfcs/073-prismic-api/README.md | Adds ## Purpose. |
| rfcs/072-transitive-sierra-hierarchies/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/071-python_builds/README.md | Adds ## Purpose. |
| rfcs/070-concepts-api-changes/README.md | Adds ## Purpose. |
| rfcs/069-catalogue_graph_ingestor/README.md | Adds ## Purpose (and remains compatible with validation patterns). |
| rfcs/068-exhibitions-content-api/README.md | Adds ## Purpose. |
| rfcs/067-prismic-api-ids/README.md | Adds ## Purpose. |
| rfcs/066-graph_pipeline/README.md | Adds ## Purpose. |
| rfcs/065-library-data-link-explorer/README.md | Adds ## Purpose. |
| rfcs/064-graph-data-model/README.md | Adds ## Purpose. |
| rfcs/063-catalogue_pipeline_lambdas/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/062-knowledge-graph/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/062-content-api-all-search/README.md | Adds ## Purpose. |
| rfcs/061-content-api-next-steps/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/060-healthcheck-principles/README.md | Adds ## Purpose. |
| rfcs/059-splitting-pipeline-terraform/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/058-relevance-testing/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/056-prismic-etl-pipeline/README.md | Adds ## Purpose; heading level normalisation in sections. |
| rfcs/055-genres-as-concepts/README.md | Adds ## Purpose. |
| rfcs/054-authority-vs-canonical-concept-ids/README.md | Adds ## Purpose. |
| rfcs/053-lambda-logging/README.md | Adds ## Purpose. |
| rfcs/052-concepts-pipeline/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/051-concepts-adapters/README.md | Adds ## Purpose; converts timestamp to UTC +00:00; heading level normalisation. |
| rfcs/050-concepts-api/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/049-catalogue-api-aggregations-modelling/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/048-concepts-rfcs/README.md | Adds ## Purpose; converts timestamp to UTC +00:00; heading level normalisation. |
| rfcs/047-catalogue-api-index-structure/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/046-born-digital-iiif/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/045-sierra-work-relationships/README.md | Adds ## Purpose. |
| rfcs/044-patron-deletions/README.md | Adds ## Purpose. |
| rfcs/043-recording-deletions/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/042-requesting-model/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/041-miro-data-changes/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/040-tei_adapter/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/039-requesting-api-design/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/038-matcher-versioning/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/037-api-faceting-principles/README.md | Adds ## Purpose. |
| rfcs/036-holdings-records/README.md | Adds ## Purpose. |
| rfcs/035-marc-856/README.md | Adds ## Purpose. |
| rfcs/034-location_location_location/README.md | Adds ## Purpose. |
| rfcs/033-api-internal-model-versioning/README.md | Adds ## Purpose. |
| rfcs/032-calm-deletions/README.md | Adds ## Purpose. |
| rfcs/031-relation_batcher/README.md | Adds ## Purpose. |
| rfcs/030-pipeline_merging/README.md | Adds ## Purpose; converts timestamp to UTC +00:00; heading level tweak. |
| rfcs/029-work_state_modelling/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/028-pipeline-intermediate-storage/README.md | Fixes RFC number in title; adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/027-relation-embedder/README.md | Fixes RFC number in title; adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/026-relevance_reporting_service/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/025-tagging-our-resources/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/024-library_management/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/023-images-endpoint/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/022-logging/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/021-data_science_in_the_pipeline/README.md | Adds ## Purpose; converts timestamp to UTC +00:00; heading level tweak. |
| rfcs/020-locations_requesting/README.md | Adds ## Purpose. |
| rfcs/019-platform_reliability/README.md | Adds ## Purpose. |
| rfcs/018-pipeline_tracing/README.md | Adds ## Purpose. |
| rfcs/017-url_design/README.md | Adds ## Purpose. |
| rfcs/016-holdings_service/README.md | Adds ## Purpose. |
| rfcs/015-how_we_work/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/014-born_digital_workflow/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/013-release_deployment_tracking/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/012-api_architecture/README.md | Adds ## Purpose. |
| rfcs/011-network_architecture/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/010-data_model/README.md | Adds ## Purpose. |
| rfcs/009-aws_account_layout/README.md | Adds ## Purpose. |
| rfcs/008-api_filtering/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/007-goobi_upload/README.md | Adds ## Purpose. |
| rfcs/006-reindexer_architecture/README.md | Adds ## Purpose. |
| rfcs/005-reporting_pipeline/README.md | Adds ## Purpose. |
| rfcs/004-mets_adapter/README.md | Adds ## Purpose. |
| rfcs/003-asset_access/README.md | Adds ## Purpose. |
| rfcs/002-archival_storage/README.md | Adds ## Purpose; converts timestamp to UTC +00:00. |
| rfcs/001-merger_matcher/README.md | Adds ## Purpose. |
| README.md | Fixes grammar/punctuation in repo overview. |
| .scripts/validate_rfc.py | New strict RFC README validator (title, ## Purpose, canonical timestamp format). |
| .scripts/git_folder_lastmod.sh | Removes unused helper script. |
| .scripts/create_table_summary.py | Refactors table generation, adds README update/sync modes, and human-readable date formatting. |
| .pre-commit-config.yaml | Adds hooks to validate RFCs and keep listing table in sync. |
| .github/workflows/validate-rfcs.yml | Adds PR workflow to validate changed RFCs and check listing table sync. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
kenoir
approved these changes
Jun 2, 2026
Contributor
kenoir
left a comment
kenoir
left a comment
There was a problem hiding this comment.
There is enough python in here now to justify a uv setup probably.
Not blocking.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A while ago, a huge piece of work was done to have a table of content of our RFCs and align them as much as possible. I noticed it hadn't been kept up to date as it was a manual task and if some specific sections were missing from the RFCs, they would be ignored by the Table of content.
This is also used in Gitbook.
So I thought I'd add tests/pre-commits and automations to try and keep it tidy as much as possible.
Warning
I vibe coded this and I don't write Python. As the original script was Python I stuck with it and relied on tests to see if it was working. If it's a mess, I'm happy to change this to a Node script.
What does this change?
This PR refactors and simplifies the RFC automation infrastructure to:
validate_rfc.pyscript enforces the following rules for all RFC README files:# RFC {3-digit-number}: {title}(e.g.,# RFC 070: Concepts API)070-concepts-api)**Last modified:** YYYY-MM-DDTHH:MM:SS+00:00+00:00offset (rejects Z, naive dates, or other formats)## Purposesection (case-insensitive)YYYY-MM-DDTHH:MM:SS+00:00) for Last modified metadata. The validator rejects loose formats (Z suffix, naive timestamps, line formatting variations)--write-readmerfcs/README.mdnow reflects the non-mutating workflow and manual timestamp updatesAll 86 RFCs pass validation with the new strict format enforcement.
How to test
Validate all RFCs:
All 86 should pass without warnings.
Regenerate the RFC listing table:
You'll see:
✓ Updated RFC table in ./rfcs/README.md (86 RFCs)Check table sync (CI mode):
Should exit with code 0 if table is in sync.
Test pre-commit hooks:
Should validate RFCs and regenerate table without modifying timestamps.
How can we measure success?
python3 .scripts/validate_rfc.pywith zero warningsvalidate-rfcs.yml) passes: validates changed RFCs and confirms table syncHave we considered potential risks?
Risk: Timestamp format enforcement could break external tooling relying on older formats
Mitigation: Validation is strict going forward, but this is enforced via pre-commit hooks (catches issues before commit). All existing 86 RFCs already migrated to canonical format.
Risk: Manual Last modified updates could be forgotten when RFCs change
Mitigation: Pre-commit validates Last modified is present and properly formatted, but doesn't auto-update it. Reviewers should notice when Last modified isn't updated in PRs. Consider documenting this in contribution guidelines. Although, I'm not sure how useful it is? I don't think we go back and edit RFCs that much - should we?
Risk: Table generation script could silently fail
Mitigation: Added success/failure messages. CI checks table sync, and pre-commit hook ensures table is regenerated.
Risk: Breaking change in RFC metadata format
Mitigation: Format is validated before commit. All 86 RFCs already conform. New RFCs must match the format from day one.
👉 See the final RFC listing table with human-readable dates: https://github.com/wellcomecollection/docs/blob/align-rfcs/rfcs/README.md