Skip to content

Contributing

Workflow

  1. Branch from main (feat/…, fix/…, docs/…).
  2. Make the change with its tests and docs in the same branch.
  3. 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 the
plan-limit lookup inside the lock used a second pool connection …

Pull-request checklist

  • New or changed SQL → make sqlc ran and internal/dbgen is committed.
  • New permission → in internal/authz/catalog.go; ims permission:sync ran.
  • 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/authn below the handler.
  • Endpoint documented in api/openapi.yaml; make openapi and make openapi-check ran.
  • make gen-check is green (sqlc, OpenAPI, generated docs, skill copies).
  • make check is green; make test-integration too when you have a database.
  • Dashboard touched → make web-typecheck and make web-build.
  • Docs updated: the guide for the feature, and docs/architecture/decisions.md for a non-obvious decision.
  • No secrets in logs or payloads.
Terminal window
make check # gofmt + vet + golangci-lint + unit tests
make test-integration # DATABASE_TEST_DSN=postgres://…/ims_go_api_test
make gen-check # generated code and docs are current
make openapi-check # the contract matches the router
make docs-build # the docs site builds and every link resolves

Writing documentation

The site’s pages are the Markdown files in docs/; website/ only renders them.

  • Add a page: create docs/<section>/<page>.md with a title and description in its front matter, then add it to the sidebar in website/astro.config.mjs.

  • Link between pages with relative file links — [Tenancy](../guides/tenancy.md) — they work on GitHub and on the site. Links that leave docs/ (to AGENTS.md, source files) point at GitHub.

  • Asides: :::note, :::tip, :::caution, :::danger with an optional [Title].

  • Components (.mdx pages only): Starlight’s Steps, Tabs, Aside, FileTree, Card, and this site’s Terminal (animated commands) and RequestFlow:

    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 — run make docs-gen.

  • Preview: make docs (Node 22.23+). make docs-build fails 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.