Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 37 additions & 3 deletions .claude/launch.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,48 @@
{
"name": "properdocs-en",
"runtimeExecutable": "properdocs",
"runtimeArgs": ["serve", "-f", "config/en/properdocs.yml", "--dev-addr", "127.0.0.1:8000", "--watch", "overrides", "--watch", "hooks", "--watch", "data", "--watch", "scripts"],
"runtimeArgs": [
"serve",
"-f",
"config/en/properdocs.yml",
"--dev-addr",
"127.0.0.1:8000",
"--watch",
"overrides",
"--watch",
"hooks",
"--watch",
"data",
"--watch",
"scripts"
],
"port": 8000
},
{
"name": "properdocs-en-alt",
"runtimeExecutable": "properdocs",
"runtimeArgs": ["serve", "-f", "config/en/properdocs.yml", "--dev-addr", "127.0.0.1:8001"],
"runtimeArgs": [
"serve",
"-f",
"config/en/properdocs.yml",
"--dev-addr",
"127.0.0.1:8001"
],
"port": 8001
},
{
"name": "review-preview",
"runtimeExecutable": "python3",
"runtimeArgs": [
"-m",
"http.server",
"8010",
"--bind",
"127.0.0.1",
"--directory",
"/private/tmp/claude-502/-Users-etiennepro--claude-spares-spare-mHZoyW/ba05716d-799e-4788-8abc-098b3b01bdae/scratchpad/site"
],
"port": 8010
}
]
}
}
10 changes: 10 additions & 0 deletions .github/ISSUE_TEMPLATE/maintainer-review.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
name: Maintainer review
description: Maintainer review
title: "Maintainer review: "
body:
- type: input
id: spec_id
attributes:
label: Specification id
validations:
required: true
65 changes: 65 additions & 0 deletions .github/workflows/maintainer_review_redeploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
name: Maintainer review status

# The maintainer review status of each specification is the `review: ...`
# label of its `maintainer-review` issue (see scripts/maintainer_review.py).
# When a status label is added, this keeps it the only one, writes today's
# date into the issue, then starts the existing deploy so the site shows it.
#
# Changes made here with GITHUB_TOKEN do not start this workflow again. The
# deploy is started with workflow_dispatch, which GITHUB_TOKEN is allowed to do.

on:
issues:
types: [labeled, unlabeled, closed, reopened, deleted]

permissions:
actions: write
issues: write

jobs:
status:
if: >-
github.event.action == 'labeled' &&
startsWith(github.event.label.name, 'review: ') &&
contains(github.event.issue.labels.*.name, 'maintainer-review')
runs-on: ubuntu-latest
steps:
- name: Keep one status label and date it
uses: actions/github-script@v7
with:
script: |
const issue = context.payload.issue;
const added = context.payload.label.name;
for (const l of issue.labels) {
if (l.name.startsWith('review: ') && l.name !== added) {
await github.rest.issues.removeLabel({
...context.repo, issue_number: issue.number, name: l.name });
}
}
const today = new Date().toISOString().slice(0, 10);
const re = /(### Review date\s*\n\s*\n)([^\n]*)/;
const body = re.test(issue.body || '')
? issue.body.replace(re, `$1${today}`)
: `${(issue.body || '').trimEnd()}\n\n### Review date\n\n${today}\n`;
await github.rest.issues.update({
...context.repo, issue_number: issue.number, body });

redeploy:
needs: status
# Runs after `status`, or on its own when `status` was skipped.
if: >-
always() && needs.status.result != 'failure' &&
(contains(github.event.issue.labels.*.name, 'maintainer-review') ||
github.event.label.name == 'maintainer-review')
runs-on: ubuntu-latest
# Several changes in a row queue one deploy instead of one per change.
concurrency:
group: maintainer-review-redeploy
cancel-in-progress: true
steps:
- name: Debounce
run: sleep 60
- name: Start the website deploy
env:
GH_TOKEN: ${{ github.token }}
run: gh workflow run update_website_contents_on_server.yml --repo "$GITHUB_REPOSITORY" --ref main
20 changes: 19 additions & 1 deletion hooks/specifications.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,8 @@
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.insert(0, os.path.join(ROOT, "scripts"))

import spec_api # noqa: E402 (path set above)
import maintainer_review # noqa: E402 (path set above)
import spec_api # noqa: E402
import spec_data # noqa: E402
import spec_history # noqa: E402

Expand Down Expand Up @@ -637,6 +638,19 @@ def dl_row(ico, label, value_html, field=None, empty=False, view=None, edit=True
% (edit_only(empty), icon(ico), escape(label), dd, value_html))


def render_review(review):
"""The line under "Maintained by": where the assessment stands in its review
by the maintainer. The status lives in a GitHub issue, not in the file the
editor changes (see scripts/maintainer_review.py)."""
if not review:
return ""
ico = "check-circle" if review["status"] == "reviewed" else "progress-clock"
date = (' <span class="spec-hero__review-date">%s</span>' % escape(review["date"])
if review["date"] else "")
return ('<p class="spec-hero__review"><span class="pill pill--%s">%s<span>%s</span>%s</span></p>'
% (escape(review["status_tone"]), icon(ico), escape(review["status_label"]), date))


def render_detail(spec, data, base, new=False):
"""One specification's page, or with `new` the blank page on which a
specification is proposed: the same layout, every field empty, opened in
Expand Down Expand Up @@ -681,6 +695,7 @@ def render_detail(spec, data, base, new=False):
o.append('<span class="org-chip org-chip--lg">%s<span>%s</span></span>'
% (org_logo(org, base), escape(org["name"])))
o.append("</span></div>")
o.append(render_review(spec.get("review")))
o.append("</div></header>")

# ---- in-page nav
Expand Down Expand Up @@ -1228,6 +1243,9 @@ def blank_spec():

def on_files(files, config):
data = spec_data.build_dataset()
reviews = maintainer_review.load(spec_data.GITHUB_REPO, {s["id"] for s in data["specs"]})
for spec in data["specs"]:
spec["review"] = reviews.get(spec["id"])

for issue in data["issues"]:
log("specifications: %s in %s: %s"
Expand Down
4 changes: 4 additions & 0 deletions overrides/assets/stylesheets/specifications.css
Original file line number Diff line number Diff line change
Expand Up @@ -2060,3 +2060,7 @@ buttons
:is(.mdip-specs, .mdip-spec) .specs-hero__glow,
:is(.mdip-specs, .mdip-spec) .spec-hero__glow { animation: none; }
}

/* Maintainer review of the assessment, under "Maintained by" */
:is(.mdip-specs, .mdip-spec) .spec-hero__review { margin: .7rem 0 0; }
:is(.mdip-specs, .mdip-spec) .spec-hero__review-date { font-weight: 400; opacity: .8; }
167 changes: 167 additions & 0 deletions scripts/maintainer_review.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
"""Where each specification's assessment stands in its review by the maintainer.

The status is not kept in data/: it lives in one GitHub issue per
specification, labelled `maintainer-review`, so the team changes it on GitHub
with no commit and no pull request.

- The status is the issue's `review: ...` label (see REVIEW_STATUS).
- The issue body holds only the specification id and the date of the last
status change. The redeploy workflow rewrites that date whenever a status
label is added, so nobody edits the body by hand:

### Specification id

gbfs

### Review date

2026-10-24

Trust: only issues carrying the `maintainer-review` label are read, and only
people with triage access can add labels, so a visitor cannot publish a status.

`load()` is called once per build. It never fails the build: when GitHub cannot
be reached it logs a warning and the pages simply show no review status.

MDIP_REVIEWS=off skip the lookup (offline builds)
MDIP_REVIEWS_FILE=path read issues from a JSON file instead of GitHub,
in the shape the GitHub issues API returns
GITHUB_TOKEN optional; raises the API rate limit
"""

from __future__ import annotations

import json
import logging
import os
import re
import urllib.request
from collections import OrderedDict

LABEL = "maintainer-review"
API = "https://api.github.com/repos/%s/issues?labels=%s&state=all&per_page=100&page=%d"
MAX_PAGES = 5

# key: GitHub label, text on the page, tone, whether the date is shown.
REVIEW_STATUS = OrderedDict([
("requested", {"github_label": "review: requested",
"label": "Assessment review requested", "tone": "warn", "dated": True}),
("in_progress", {"github_label": "review: in progress",
"label": "Assessment under review by maintainer", "tone": "warn",
"dated": True}),
("no_answer", {"github_label": "review: no answer",
"label": "Assessment review requested", "tone": "warn", "dated": False}),
("reviewed", {"github_label": "review: reviewed",
"label": "Assessment reviewed by maintainer", "tone": "pass", "dated": True}),
])
BY_GITHUB_LABEL = {v["github_label"]: k for k, v in REVIEW_STATUS.items()}

_HEADING_RE = re.compile(r"^###\s+(.+?)\s*$", re.M)
_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
_NO_RESPONSE = "_no response_"

log = logging.getLogger("mkdocs.hooks.maintainer_review")


def parse_body(body):
"""{field heading (lowercase): answer} from an issue form body."""
fields = {}
parts = _HEADING_RE.split(body or "")
for i in range(1, len(parts) - 1, 2):
value = parts[i + 1].strip()
fields[parts[i].strip().lower()] = "" if value.lower() == _NO_RESPONSE else value
return fields


def make_body(spec_id, date):
return "### Specification id\n\n%s\n\n### Review date\n\n%s\n" % (spec_id, date or "_No response_")


def review_from_issue(issue):
"""The published review record for one issue, or (None, reason)."""
fields = parse_body(issue.get("body"))
sid = fields.get("specification id", "").strip()
if not sid:
return None, "no specification id"
names = [l["name"] if isinstance(l, dict) else l for l in issue.get("labels") or []]
statuses = [BY_GITHUB_LABEL[n] for n in names if n in BY_GITHUB_LABEL]
if len(statuses) != 1:
return None, "%d review labels instead of 1" % len(statuses)
status = statuses[0]
meta = REVIEW_STATUS[status]
date = fields.get("review date", "").strip()
if date and not _DATE_RE.match(date):
return None, "review date is not YYYY-MM-DD"
return {
"spec_id": sid,
"status": status,
"status_label": meta["label"],
"status_tone": meta["tone"],
"date": (date or None) if meta["dated"] else None,
"_updated": issue.get("updated_at") or "",
}, None


def _fetch(repo):
headers = {"Accept": "application/vnd.github+json",
"User-Agent": "mdip-registry-build"}
token = os.environ.get("GITHUB_TOKEN")
if token:
headers["Authorization"] = "Bearer " + token
issues = []
for page in range(1, MAX_PAGES + 1):
req = urllib.request.Request(API % (repo, LABEL, page), headers=headers)
with urllib.request.urlopen(req, timeout=15) as resp:
batch = json.load(resp)
issues.extend(batch)
if len(batch) < 100:
break
return issues


def _read_issues(repo):
path = os.environ.get("MDIP_REVIEWS_FILE")
if path:
with open(path) as fh:
return json.load(fh)
return _fetch(repo)


def load(repo, known_ids):
"""{spec id: review record} for every specification with a review issue."""
if os.environ.get("MDIP_REVIEWS", "").lower() in ("off", "0", "false", "no"):
return {}
try:
issues = _read_issues(repo)
except Exception as exc: # network, rate limit, bad JSON: never fail the build
log.warning("maintainer review: issues not read, no status shown (%s)", exc)
return {}

reviews = {}
for issue in issues:
if "pull_request" in issue:
continue
record, reason = review_from_issue(issue)
where = "issue #%s" % issue.get("number", "?")
if record is None:
log.warning("maintainer review: %s skipped: %s", where, reason)
continue
if record["spec_id"] not in known_ids:
log.warning("maintainer review: %s names unknown specification %r",
where, record["spec_id"])
continue
# Several issues for one specification: the most recently updated wins.
previous = reviews.get(record["spec_id"])
if previous is None or record["_updated"] > previous["_updated"]:
reviews[record["spec_id"]] = record
for record in reviews.values():
record.pop("_updated", None)
return reviews


def api_record(review):
"""The review as the JSON API publishes it, or None."""
if not review:
return None
return {"status": {"id": review["status"], "label": review["status_label"]},
"date": review["date"]}
Loading
Loading