Skip to content

feat(specifications): edit entries and propose new ones from the registry pages - #77

Merged
etienne0101 merged 2 commits into
mainfrom
add-editing
Nov 18, 2026
Merged

etienne0101 merged 2 commits into
mainfrom
add-editing

Conversation

@etienne0101

Copy link
Copy Markdown
Contributor

What changed

In-page editor ("Suggest a change")

  • On a specification page, "Suggest a change" now makes the page editable. A small edit button sits next to every value that comes from the entry's file (data/specifications/<id>.md).
  • Each field gets a control that fits its type:
    • custom drop-downs for status, verdicts, lifecycle, tier and maintainer confirmation;
    • a searchable licence picker grouped by category, with "Other licence" and scopes;
    • an organization picker with "Add" for one that is not in the registry yet;
    • mode chips;
    • validated year, count, date and URL inputs, and text areas for longer text.
  • Values that depend on each other update together:
    • a criterion marked not compliant makes the MDIP status not compliant (the same rule as make specs-check);
    • a closed or restricted licence sets "Free of cost restrictions";
    • a new adopters count takes today's date and the matching tier;
    • an inactive lifecycle makes the status inactive.

Sending a suggestion

  • "Review" shows a before/after table and a field for sources.
  • "Continue on GitHub" opens a pre-filled issue from the new .github/ISSUE_TEMPLATE/specification-edit.yml form. The issue holds the table and the same change as YAML for the file.
  • The draft is kept in localStorage until the contributor confirms they submitted it, so signing in or creating a GitHub account does not lose it. A sign-up link returns to the pre-filled form, and "Copy suggestion" is a fallback.

Proposing a new specification

  • /specifications/new/ is a blank entry opened in the same editor.
  • The registry id is derived from the short name and checked for uniqueness. The page sends the complete new file.
  • It is linked as "Propose a new specification" on every entry, and from "Propose a specification" on the registry page.

History

  • Each change now names who took part, read from the GitHub timeline:
    • "Change proposed by";
    • "Discussed with" (up to three names, then "and N more" linking to GitHub);
    • "Approved by".
  • "Merged by" is shown only when nobody approved.
  • Open suggestions sent from the editor appear under "Proposed changes".

Filter panel

  • On wide screens the panel no longer has its own scrollbar. It scrolls with the page until its last filter is visible, then comes back as soon as the page scrolls up. The mobile drawer is unchanged.

Other

  • The editor draws organization monograms only, so it loads nothing from third-party hosts.
  • .claude/launch.json now points at config/en/properdocs.yml.
  • README.md and data/README.md describe the new contribution flow.

Why

Contributors no longer have to edit YAML in GitHub's editor, and the editor only offers valid values. The site still needs no backend: GitHub issues remain the place where changes are reviewed in public.

Notes for reviewers

  • The issue form only takes effect once it is on main. Until then, the "Continue on GitHub" link will not find the template.
  • Suggestions arrive as issues, not pull requests. A maintainer applies the YAML from the issue to the file. A GitHub Action could turn these issues into PRs later.
  • Without JavaScript, "Suggest a change" still opens the file in GitHub's editor, and the new page shows a link to create the file on GitHub.
  • Checked locally: make specs-check passes, the site builds, and the editor, review dialog, saved draft, History and filter panel were tested in the browser (desktop and mobile). No real issue was submitted. Signing up on GitHub and coming back to the form was not tested with a real account.

🤖 Generated with Claude Code

…stry pages

Add an in-page editor to the specification registry so contributors can
propose changes without editing YAML by hand.

- "Suggest a change" now turns a specification page into an editor: an
  edit button next to every value that comes from the entry's file, each
  opening a control that fits the field (custom drop-downs for statuses
  and verdicts, a searchable licence picker with an "Other licence"
  option and scopes, an organization picker, mode chips, year, count,
  date and URL inputs with validation).
- Values that depend on each other stay consistent while editing: the
  MDIP status follows the criteria verdicts (same rule as specs-check),
  a closed or restricted licence sets "Free of cost restrictions", a new
  adopters count takes today's date and the matching tier, and an
  inactive lifecycle makes the status inactive.
- Changes are reviewed in a dialog and sent as a pre-filled GitHub issue
  from the new specification-edit.yml form, with a before/after table
  and the same change as YAML for the file. The draft is kept in
  localStorage until it is sent, so signing in or creating a GitHub
  account does not lose it; a sign-up link returns to the pre-filled form.
- New /specifications/new/ page: a blank entry opened in the same editor,
  with the registry id derived from the short name and checked for
  uniqueness. It sends the complete new file. Linked as "Propose a new
  specification" on every entry and from the registry page.
- History now lists who took part in each change from the GitHub
  timeline: "Discussed with" (up to three names, then "and N more"),
  "Approved by", and "Merged by" only when nobody approved. Open
  suggestions sent from the editor appear under "Proposed changes".
- The filter panel on wide screens no longer has its own scrollbar: it
  scrolls with the page until its last filter is visible and comes back
  as soon as the page scrolls up.
- The editor draws organization monograms only, so it loads nothing
  from third-party hosts.
- Point the local preview config at config/en/properdocs.yml and
  document the new contribution flow in README.md and data/README.md.

The issue form only takes effect once it is on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread .claude/launch.json Outdated
@@ -4,13 +4,13 @@
{
"name": "mkdocs-en",

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.

mkdocs -> properdocs?

Comment thread .claude/launch.json Outdated
@@ -4,13 +4,13 @@
{
"name": "mkdocs-en",
"runtimeExecutable": "mkdocs",

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.

mkdocs -> properdocs?

Comment thread .claude/launch.json Outdated
"port": 8000
},
{
"name": "mkdocs-en-alt",

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.

mkdocs -> properdocs?

Comment thread .claude/launch.json Outdated
},
{
"name": "mkdocs-en-alt",
"runtimeExecutable": "mkdocs",

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.

mkdocs -> properdocs?

Comment thread README.md Outdated
@@ -50,6 +52,7 @@ change" on a specification's page opens that file in GitHub's editor.
| `scripts/spec_api.py` | Builds the `/api/` files: catalogue, full records, export CSV, the OpenAPI description, and its Swagger UI page at `/api/docs/`. |
| `scripts/check_specs.py` | `make specs-check`: validation, also run on every pull request. |
| `hooks/specifications.py` | MkDocs hook that renders the pages and publishes the API. |

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.

MKDocs -> ProperDocs?

@fredericsimard fredericsimard 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.

Many Mkdocs remain, we switched to ProperDocs and not going back so you can do a search/replace if need be in the future.

Address review feedback on PR #77: the project switched to ProperDocs,
so leftover MkDocs mentions are updated.

- .claude/launch.json: rename the preview configurations to
  properdocs-en / properdocs-en-alt and run the properdocs executable.
- README, Makefile, hooks/specifications.py, scripts/spec_api.py,
  overrides/sitemap.xml, .gitignore: say ProperDocs in prose and comments.

Left unchanged on purpose: the `mkdocs` Python import and logger name in
hooks/specifications.py, PyPI package names in requirements.txt and the
Makefile, and the "Material for MkDocs" theme name, since those are real
identifiers or third-party product names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@fredericsimard fredericsimard 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.

LGTM!

@etienne0101
etienne0101 merged commit 6bf9ebb into main Nov 18, 2026
1 check passed
@etienne0101
etienne0101 deleted the add-editing branch November 18, 2026 22:06
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.

2 participants