Skip to content

Gate the document on the conformance suite - #7

Merged
NetworkTheoryAppliedResearchInstitute merged 1 commit into
mainfrom
ci/conformance-gate
Sep 13, 2026
Merged

NetworkTheoryAppliedResearchInstitute merged 1 commit into
mainfrom
ci/conformance-gate

Conversation

@NetworkTheoryAppliedResearchInstitute

Copy link
Copy Markdown
Contributor

Three layers, as discussed: a CI check that actually gates, a local hook for fast feedback, and the contributor documentation the repo never had.

Why now

The suite has been the load-bearing rung since #4 published it, and nothing ran it. The repo has no workflows; the checks reporting on a PR are CodeQL and DCO, neither of which knows what the document is.

That was survivable while amendments arrived as separate proposal files — those couldn't break the document by construction. Now that amendments edit the document directly (#6), the suite is the only thing between a malformed edit and the standard, and it ran only when someone remembered.

What's here

File Role
.github/workflows/conformance.yml Runs the suite on every PR and on pushes to main
.githooks/pre-push Same check locally, before anything reaches the remote
CONTRIBUTING.md Sign-off rules, and what the suite actually constrains
.gitattributes Pins the hook and workflow to LF

No paths: filter on the workflow, deliberately. This is meant to become a required status check, and a required check that never runs leaves a PR blocked forever — GitHub waits on a report that never arrives. The suite finishes in under a second, so running it on everything costs nothing and always reports.

The hook is a convenience, not a gate, and both the hook and CONTRIBUTING.md say so. Hooks aren't distributed with a repository — .git/hooks isn't committed, so it only exists where someone ran git config core.hooksPath .githooks — and --no-verify skips them. A non-conformant edit can always be proposed. What this stops is it being merged.

.gitattributes matters more than it looks: checked out with CRLF on a Linux runner, the hook has a bad interpreter line and silently won't run.

CONTRIBUTING.md

The repo has enforced DCO on every commit without documenting it anywhere. It now records the sign-off requirement and, specifically, that DCO matches the trailer against the commit author exactly — commits here are authored the Institute <info@ntari.org> while history often signs off under a personal name, and that mismatch is the failure contributors actually hit.

It also writes down what the suite constrains, which was previously only discoverable by reading the suite: the nine sections, no new ### inside a layer section, twelve lines, the twenty-five anchors, no product names, no addresses beyond the footer.

Merge order matters

The required status check is not in this PR, and shouldn't be — adding it now would block #6, which has no workflow in its branch and would wait forever on a check that can't report.

Sequence: merge this → the workflow lands on main → then the check becomes required. I've staged a repo-level ruleset for that, currently disabled so it enforces nothing until you flip it.

It has to be repo-level rather than added to Org Baseline - Protect main: that ruleset is shared across NTARI-RAND, and most of those repos have no conformance suite to run.

Note that main currently has no required_status_checks rule at all — so today even DCO and CodeQL going red wouldn't stop a merge.

The suite has been the load-bearing rung since it was published, and nothing
ran it. The repository carried no workflows at all; the checks reporting on a
pull request were CodeQL and DCO, neither of which knows what the document is.
That was survivable while amendments arrived as separate proposal files, which
could not break the document by construction. Now that amendments edit the
document itself, the suite is the only thing standing between a malformed edit
and the standard, and it ran only when someone remembered to run it.

Adds the Conformance workflow, which runs the suite on every pull request and
on pushes to main. Deliberately no paths filter: this is meant to become a
required status check, and a required check that never runs leaves a pull
request blocked forever. The suite finishes in well under a second, so running
it on every pull request costs nothing and always reports.

Adds .githooks/pre-push for the same check locally, installed with
  git config core.hooksPath .githooks
and says plainly in both the hook and CONTRIBUTING.md that this is a
convenience rather than a gate — hooks are not distributed with a repository,
and --no-verify skips them. The pull request check is what holds.

Adds CONTRIBUTING.md, which the repository never had despite DCO being enforced
on every commit. It records the sign-off requirement and the fact that DCO
matches the trailer against the commit author exactly, which is the failure
mode contributors actually hit. It also writes down what the suite constrains:
the nine sections, no new third-level heading inside a layer, twelve lines, the
twenty-five anchors, no product names, no addresses beyond the footer.

.gitattributes pins the hook and the workflow to LF. Checked out with CRLF on a
Linux runner the hook has a bad interpreter line and will not run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: the Institute <info@ntari.org>
@csecrestjr
csecrestjr self-requested a review September 11, 2026 23:15
@NetworkTheoryAppliedResearchInstitute
NetworkTheoryAppliedResearchInstitute merged commit 1eecd00 into main Sep 13, 2026
4 checks passed
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