trsdn repository standards

This repository contains the public repository quality standard, default community health files, and self-hosted statistics tooling for projects maintained by trsdn.

Its language is English, and it ships no localized content. See L01 and L03.

Canonical standard

The Repository Quality Standard defines the evidence required for maintainable public repositories. Repository-specific requirements may be stricter, but must not silently weaken this baseline.

standard.yml is the same content in machine-readable form, generated from the document and kept in sync by a required check.

Repository statistics for P09 are documented in Repository stats, and account-level cards are documented in Profile statistics.

Citing a criterion

Cite the pinned form, never the default branch:

https://github.com/trsdn/.github/blob/v1.3.3/docs/repository-quality-standard.md#p09

Criterion identifiers are append-only and are never reused, so a citation keeps its meaning. See decision 0001.

Applying the standard to a repository

1. Assess the repository against a published version of the standard. To start from a draft rather than a blank record, read what a script can read:

   python3 scripts/assess.py --repo owner/name --out drafts/owner-name

   It decides only the criteria a fact settles — the topic, the licence, the permissions blocks, the action references — and leaves everything that turns on judgement unknown. See drafting a record.

2. Record the result in .github/conformance.yml, following the record format. To start from a record that already names every criterion, copy templates/conformance.yml or generate one:

   python3 scripts/conformance.py --init --repository /path/to/repository

3. Generate the badge from the record and commit it.

4. Add the trsdn-standard topic so the repository appears in the inventory.

5. Call the reusable check:

   jobs:
     conformance:
       uses: trsdn/.github/.github/workflows/conformance.yml@main

The topic marks a repository as assessed, not as passing. The outcome lives only in the record.

Inventory

gh search repos --owner trsdn --topic trsdn-standard --limit 100 \
  --json fullName,isArchived

The difference between that list and the full account list is the outstanding assessment backlog. scripts/assess.py exists to make that number movable.

This repository's own result

State: Healthy. Every criterion that applies to this repository passes, and the evidence for each is recorded in the self-assessment. The Published Site profile is not among them: this repository defines the standard rather than shipping a product, and its readers are already inside a repository when they read it.

Publishing a green badge over a known gap would devalue every other badge in the estate, so the badge follows the record and never the other way round.

Repository activity

The card is generated by the tooling this repository publishes and committed to the stats branch on a schedule. It is not fetched from a third-party rendering service, which is what P09 requires and why Y02 requires it.

Default community files

GitHub can use the governance and contribution files in this repository for public trsdn repositories that do not provide their own versions. A file in an individual repository takes precedence when project-specific guidance is needed.

• Security policy
• Contributing guide
• Code of conduct
• Support guide
• Issue forms
• Pull request template

Default files improve consistency, but they do not configure branch protection, CI, dependency updates, vulnerability alerts, or secret scanning in other repositories. Those controls must be enabled and verified per repository.

Templates

• templates/AGENTS.md — starting point for the agent readiness criteria G01 to G08.
• templates/conformance.yml — starting point for the B11 conformance record, naming every criterion in the catalog. Generated, so it cannot fall behind the criteria it lists.
• templates/repo-stats/ — caller workflow and README snippet for the P09 repository statistics card.
• templates/release-notes/ — reference release workflow implementing the R07 gate, which publishes the changelog entry for the tag as the release notes.

Contributing

Agent and contributor guidance for this repository is in AGENTS.md. Decisions behind the standard are recorded in docs/decisions/.

Validation

From a clean checkout, run the repository validation commands:

python3 scripts/standard.py --check
python3 scripts/conformance.py --check
python3 scripts/links.py
python3 -m unittest discover -s tests -v
npx --yes markdownlint-cli2@0.18.1 "**/*.md"
pipx run ruff==0.14.5 check . && pipx run ruff==0.14.5 format --check .

The standard and conformance scripts, the link checker, the draft assessor, and their tests use the Python standard library only. The statistics generator is separate runtime tooling and installs requests from requirements.txt when its workflows run. Markdown linting and Ruff pin their tool versions and are never added as dependencies, so every script still runs from a bare Python installation.

Privacy

This repository collects nothing and stores no user data. Routine validation resolves markdownlint-cli2 from the npm registry and Ruff from PyPI. The optional statistics generator contacts the GitHub API to render repository and account SVG cards. The cards it produces are self-contained and embed no remote fonts or images, so displaying one observes nobody. See Y01 and Y02.

Credentials

One credential is configured here beyond the token GitHub issues per workflow run: STATS_TOKEN, an optional fine-grained personal access token the statistics workflows use where the run token is not enough, with the access listed in repo stats. If it is exposed, the maintainer revokes it in GitHub account settings, issues a replacement, and updates the repository secret; no other system holds a copy, so nothing else has to be changed, and until it is replaced the workflows fall back to the run token. GITHUB_TOKEN is issued and revoked per run and needs no such handling. See B14.

License

The content and templates in this repository are available under the MIT License.

Nothing here redistributes third-party code. The documents, templates, scripts, and workflows are written in this repository; the statistics generator's one runtime dependency and the validation tools are resolved from their registries by whoever runs them, and are not vendored, bundled, or published onward. There are therefore no third-party licence obligations to pass on. See B15.