Contributing
Contributing
Contributions are welcome. This document defines the working agreement for this repo. It states how changes are proposed, reviewed and merged. It states what the CI gates enforce. This is the docs-only Quarto site repo — no Go, no appliance stack; the product working agreement lives in the trishula repo.
The writing standard
This repo follows the org writing standard: ASD-STE100 Simplified Technical English — one thought per sentence, a 20-word cap, active voice and present tense. The canonical decision record lives in the main repo: docs/adr/0002-asd-ste100-standard.md. This repo carries no docs/adr/ scaffolding; the prose conversion tracks as issue #39 (TR-WS-4).
Ground rules
- Never commit to
main. All work runs on a branch. One change uses one branch. The merge runs through a pull request. Branch names follow<type>/<short-description>in kebab-case, for examplesite/nav-order,docs/badge-row,agents/page-refresh. - Conventional Commits. Every commit subject follows the specification:
type: subject(scope optional on a docs-only site).- Standard types:
feat,fix,docs,refactor,test,build,ci,chore,perf,revert. - Site-surface types (this repo’s extension, carried by its history):
site(rendered-page content/layout) andagents(the coding-agents guide page). - Subject: imperative, with no trailing period. Body (optional): what changed and why. Body wraps at 72 columns.
- PR titles follow the same form. Site-track items carry their roadmap id in the subject —
site: TR-WS-3 — …/docs: TR-42 — …. Squash merges use the PR title as the commit subject (squash_merge_commit_title: COMMIT_OR_PR_TITLE), so the PR title is the commit record. A CI gate checks the form on every PR.
- Standard types:
- Sign everything. Commits carry a GPG or SSH signature. The
protect-defaultruleset requires signatures (required_signatures) — an unsigned commit blocks the PR. Verify withgit log --show-signature. - One logical change per PR. Small, reviewable diffs merge faster.
- Pre-commit runs locally. Install the hooks once per clone —
pre-commit install && pre-commit install --hook-type pre-push. Everygit commitandgit pushthen runs the hook set CI runs. pre-commit.ci still gates every PR.
CI gates
Every pull request runs:
| Check | What it does |
|---|---|
site-check (required) |
quarto render fails on broken refs; the built HTML must exist |
scorecard |
OpenSSF Scorecard (publishes on the default branch) |
pr-title-gate |
PR title matches the Conventional Commits form |
pre-commit.ci |
the .pre-commit-config.yaml hook set |
The branch ruleset protect-default (active) enforces: no deletions, no non-fast-forward pushes, required signatures, and the PR rule (code-owner review; extra approval for unattributed changes). Merges to main deploy the site via the Pages workflow (pages.yml); the live page is trishula.dev.
Commits and pull requests
- Cut the branch from current
origin/main. Push and open the PR againstmain. The description states what changed, why (the issue) and how the rendered output was verified. - Verify rendered output, not configuration: run
quarto render, then parse the built_site/*.html(nav order, labels, TOC anchors) before pushing. - Merges happen on review. The merge is the maintainer’s action.
Reporting bugs
Open a GitHub issue describing the page, the observed vs expected render, and the commit where the behaviour appeared. Security issues never go here — SECURITY.md is the channel instead.