Standards
The Overview tab of the Standards region (/standards/overview?repo=owner/name) shows the rules one repository states, and whether each one is enforced. Open Standards, then Overview. The tab needs a selected repository: pick one with the repository control in the region’s header.
The page opens with this line: “Rules this repository states, and whether each one is enforced. A standard with no enforcement is stated but unchecked — it is never assumed to block.”
Subscribed set
Section titled “Subscribed set”The first card says which standards set the repository follows:
- Subscribed to
set name, with a Published vNbadge for the published version the repository currently resolves to. - “This repository is not subscribed to a standards set yet.” when it follows none.
Standards set
Section titled “Standards set”The Standards set select subscribes the repository to one of your organization’s standards sets. Sets are written and published on Standards → Standards sets, which the card links to.
- Only sets with a published version are offered, each as
name (vN). - Choosing a set subscribes the repository straight away. It always resolves to the set’s latest published version, and the standards list below updates.
- The select is disabled while a change is saving, and when no set is published. Its placeholder reads Select a set…, or No published sets available when none can be chosen.
A hint under the select says what to do next:
| Case | Hint |
|---|---|
| The organization has no sets | ”No standards sets yet. Create one under Standards sets, publish it, then select it here.” |
| Sets exist but none is published | ”Your standards sets have no published version yet. Publish one under Standards sets to subscribe this repository.” |
| At least one set is published | ”Sets are written and published under Standards sets.” |
Conventions editor
Section titled “Conventions editor”Below the select, the conventions editor works on the repository’s .colony/conventions.md file.
- When the file exists, the card shows its contents.
- When it does not, the card says so and explains that Import reads the file into the subscribed set as draft statements, and Export writes the set’s published statements back to the file.
- Import reads
.colony/conventions.mdinto the subscribed set as draft statements. A toast reports how many statements were imported and into which set. - Export first asks “Export conventions to the repository?”. The dialog says that confirming commits
.colony/conventions.mdto the default branch and replaces any existing contents with the published statements of the subscribed set. Confirm with Export and commit. A toast then reads “Exported to .colony/conventions.md”.
Export is an explicit action. Editing the set never writes to the repository on its own.
Standards list
Section titled “Standards list”Each row is one standard from the subscribed set, with its statement and an enforcement badge:
| Badge | Meaning |
|---|---|
| Stated | The standard has no check behind it. It is written down but unchecked, and never assumed to block. |
| Non-blocking | A check runs, but a failure only warns. |
| Enforced | A check runs and a failure blocks. |
When the list is empty the page reads “No standards recorded for this repository yet.”
Relation to proposal standards
Section titled “Relation to proposal standards”Some standards are backed by a proposal check, whose check reference starts with proposal:. These are the same standards that appear in the Standards card of a proposal, marked “met” or “not met”, or “Not applicable”. A failed blocking standard disables Authorize. See Drafts for the proposal side.
Proposal-check rows show their badge but get no exception buttons here. Only rows backed by another kind of check can have an exception, and only when the repository is subscribed to a set.
Exceptions
Section titled “Exceptions”An exception records a reasoned reason why one repository is not held to one check.
- Record exception opens a modal with two fields. Kind is Waived or Not applicable. Reason is required; leaving it empty shows “A reason is required” and keeps the button disabled. Cancel closes the modal.
- A row with an exception shows a badge with its kind and a Remove exception button instead.
- Remove exception asks for confirmation: “Remove the exception for
check? The repository will be checked against it again.” Confirm with Remove exception, or choose Keep exception. - After you record one, an info note from the API appears above the list. Choose Dismiss to close it. It is also cleared when you remove an exception or switch repositories.
Recorded exceptions
Section titled “Recorded exceptions”The Recorded exceptions list shows each exception with its check name, kind badge, reason, the author (by name, when known) and a relative time. When there are none, it reads “No exceptions recorded for this repository.”
Who would fail
Section titled “Who would fail”When the repository is subscribed, the Who would fail panel shows, for every checked standard in the set, how the set’s repositories fare. Each check card shows a Blocking or Advisory badge, “N would fail” and “N clean” counts, and four groups:
- Clean — repositories that pass.
- Would fail — repositories that fail, with the number of findings.
- Excepted — repositories with an exception: kind, reason, author and time.
- Not running this check — repositories that do not run it.
An empty group shows None. The panel is hidden when the set has no checks. These Blocking and Advisory labels belong to this panel; the badges on the list use Enforced and Non-blocking.
Permissions
Section titled “Permissions”The page does not hide its buttons. The API checks the grant when you act, and a request without it is refused with a 403 error that the dashboard shows.
| Action | Grant |
|---|---|
| Change the subscription | standards-subscription-update |
| Record or remove an exception | standards-exception-write |
| Import conventions | standard-create |
| Export conventions | conventions-update |
Reading the page needs none of these. See Team & Roles for roles and grants.
Loading and errors
Section titled “Loading and errors”Each region loads on its own. Skeleton cards show while data loads, and a region that fails shows its error message, with a retry where the failure can be retried. The conventions editor, the exceptions list and the adoption panel can fail without affecting the standards list.
| Method | Path | Used for |
|---|---|---|
GET | /api/repos/:owner/:repo/standards | Subscribed set and standards list |
GET | /api/repos/:owner/:repo/standards/subscription | Current subscription |
PUT | /api/repos/:owner/:repo/standards/subscription | Change the subscription |
GET | /api/orgs/:orgId/standards-sets | Sets offered in the select |
GET | /api/repos/:owner/:repo/standards/exceptions | Recorded exceptions |
POST | /api/repos/:owner/:repo/standards/exceptions | Record an exception |
DELETE | /api/repos/:owner/:repo/standards/exceptions/:id | Remove an exception |
GET | /api/repos/:owner/:repo/conventions | Contents of .colony/conventions.md |
POST | /api/repos/:owner/:repo/conventions/import | Import conventions as draft statements |
POST | /api/repos/:owner/:repo/conventions/export | Export and commit conventions |
GET | /pipeline/standards-adoption?set=setId | Who would fail panel |