Contributing
Workflow
- Branch from
main(feat/…,fix/…,docs/…). - Make the change with its tests and docs in the same branch.
- Run the checks below; open a pull request. CI runs them all again on Linux, including the race detector and the integration suite against Postgres.
Commits say what changed and why — one commit per feature or fix, imperative mood:
fix(quota): read plan limits before the per-tenant lock
User and branch creation counted and inserted under a per-tenant advisory lock, but theplan-limit lookup inside the lock used a second pool connection …Pull-request checklist
- New or changed SQL →
make sqlcran andinternal/dbgenis committed. - New permission → in
internal/authz/catalog.go;ims permission:syncran. - Tenant-scoped reads and writes filter on the explicit tenant id — with an isolation test.
- Related data is batch-loaded (no query per row in a list).
- Handlers are thin; business rules live in services; no
httpx/authnbelow the handler. - Endpoint documented in
api/openapi.yaml;make openapiandmake openapi-checkran. -
make gen-checkis green (sqlc, OpenAPI, generated docs, skill copies). -
make checkis green;make test-integrationtoo when you have a database. - Dashboard touched →
make web-typecheckandmake web-build. - Docs updated: the guide for the feature, and
docs/architecture/decisions.mdfor a non-obvious decision. - No secrets in logs or payloads.
make check # gofmt + vet + golangci-lint + unit testsmake test-integration # DATABASE_TEST_DSN=postgres://…/ims_go_api_testmake gen-check # generated code and docs are currentmake openapi-check # the contract matches the routermake docs-build # the docs site builds and every link resolvesWriting documentation
The site’s pages are the Markdown files in docs/; website/ only renders them.
-
Add a page: create
docs/<section>/<page>.mdwith atitleanddescriptionin its front matter, then add it to thesidebarinwebsite/astro.config.mjs. -
Link between pages with relative file links —
[Tenancy](../guides/tenancy.md)— they work on GitHub and on the site. Links that leavedocs/(toAGENTS.md, source files) point at GitHub. -
Asides:
:::note,:::tip,:::caution,:::dangerwith an optional[Title]. -
Components (
.mdxpages only): Starlight’sSteps,Tabs,Aside,FileTree,Card, and this site’sTerminal(animated commands) andRequestFlow:import Terminal from '@components/Terminal.astro'<Terminal title="make dev" lines={[{ cmd: 'make dev' }, { out: 'listening on :8081', tone: 'ok' }]} /> -
Screenshots go in
docs/images/and are referenced relatively (../images/x.png). -
Never edit
docs/reference/{cli,configuration,permissions,make}.md— runmake docs-gen. -
Preview:
make docs(Node 22.23+).make docs-buildfails on any broken link or anchor.
Write for someone who just cloned the repository: say what a thing is for before how it works, show real commands and real code from this codebase, and prefer a table to a paragraph of options.