Contributing

This section is the contributor-facing handbook for working on the plexsphere repository. Read it before opening a pull request — the gates documented here run in CI, and a red gate is the most common reason a PR sits unmerged.

The handbook is grouped by the order a contributor typically needs the information: first the lay of the land and the toolchain, then how to test and how CI verifies the change, then the surfaces (API, dashboard, docs) each with their authoring rules, and finally the contributor tooling that helps with audits and previews.

Orient yourself

Read these first when you join the repository or come back to it after a long absence.

• Repository layout and bounded-context map — where each internal/<context>/ package belongs, the binaries under cmd/, and the depguard rules that enforce the boundaries.
• Composing an API surface — the surface contract, the registry phases cmd/plexsphere walks at boot, the order of the registry, the transport dependency struct, the opt-out rule, and the gates that pin every registered surface.
• Toolbox — building without host dependencies — the image every make target runs in by default, what it mounts from the host, and when to switch it off with TOOLBOX=0.
• Toolchain pins and upgrade procedure — the single source of truth for Go, golangci-lint, GitHub Actions, SPDX headers, container images, and every other build-time pin.
• Commit subjects and release notes — which Conventional Commit types reach the generated release notes, which are dropped, and the make release-notes and make changelog targets.

Test and verify a change

How the test pyramid is organised and what CI runs on every PR.

• Testing — pyramid, build tags, and the shared harness — the unit / integration / E2E tiers, the integration build tag, the shared internal/platform/testutil primitives, and the rendered-surface rule on every failure message.
• CI pipeline — jobs, triggers, and reproducing failures — every CI job mapped to its local make target, the path-based skipping rules, the cache layers, and the per-tool reproduction recipes for a red run.
• Dev stack runbook — bring up the full local dev cluster on kind, seed the demo tenant, sign in with plexctl, run the golden flow, and consult the manifest-to-CI mapping and troubleshooting matrix.

Evolve the /v1 API surface

Three pages target the /v1 HTTP surface: the spec workflow and codegen, the versioning and compatibility policy with the gates that enforce it, and the runtime UI that renders the spec.

• OpenAPI-first contract and code generation — the authoring loop for api/openapi/plexsphere-v1.yaml, the authentication and contract conventions the spec linter enforces, and the generated artefact trees the drift gate covers.
• API versioning and compatibility — the /v1 compatibility policy, the spec-driven Deprecation and Sunset headers, the oasdiff compatibility gate with its reviewed exceptions file, the client tolerance rules, and the nightly scenario that runs the previous plexd release against the current tree.
• Embedded ReDoc UI for /v1/docs — the vendored ReDoc bundle, the supply-chain-safe upgrade procedure, the security headers the handler emits, and the authn/authz bypass entries that let the page render without credentials.

Author and maintain the docs corpus

The rules that keep the docs corpus consistent, traceable, and free of internal task identifiers, plus how to preview the site locally.

• Docs authoring conventions — sentence-case headings, the five-field frontmatter contract, and the rule that internal task identifiers never reach the rendered output.
• Traceability identifier conventions — repository-wide map of which surfaces may carry planwerk task ids, requirement ids, and review-item codes, plus the regression gate that keeps them out of rendered surfaces.
• Previewing and building the docs site locally — make docs-preview, make docs-build, make docs-publish, the umbrella make publish (which also ships the cross-platform plexctl downloads), the pinned VitePress tooling, and the worked example for adding a new page to the sidebar.

Contributor tooling

• Claude Code skills — the repository-specific audit skills under .claude/skills/, what each one covers, how to invoke them, and how their deterministic scripts pair with the CI gates.

When to read this section

• You are setting up a development environment for the first time — start with layout and toolchain.
• A CI job is failing and you want the local reproduction recipe — see the CI pipeline guide.
• You are about to author a new doc page and need the heading and frontmatter rules — see authoring conventions and the docs-preview worked example.
• You are introducing a new bounded context, a new CI job, or a new top-level binary — see layout and CI, and remember the lockstep gates the audit skills in claude-skills cover.