> ## Documentation Index
> Fetch the complete documentation index at: https://docs-terra.withunify.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to contribute to Terra without breaking release quality

# Contributing

> Keep changes small, testable, and reviewable. CI is a hard gate.

## Development Workflow

1. Sync `main`: `git checkout main && git pull origin main`
2. Create branch: `git checkout -b feat/<short-name>`
3. Implement with tests/docs in the same change set
4. Run local checks before opening PR
5. Open PR to `main`
6. Merge only after required checks pass

## Required Local Checks

```bash theme={null}
pnpm --dir apps/terra tsc --noEmit
pnpm --dir apps/terra lint
pnpm --dir apps/terra test
```

For E2E-sensitive changes, also run:

```bash theme={null}
pnpm --dir apps/terra exec playwright test tests/status-lookup.spec.ts --project=chromium --grep "Smoke Tests"
```

## Commit Convention

Use conventional commits:

```text theme={null}
feat(forms): add rating field type
fix(auth): handle expired sessions
docs(ops): update onboarding steps
test(terra): unskip duplicate-form suite
```

## Pull Request Checklist

* [ ] Problem statement is clear
* [ ] Scope is limited to one coherent change
* [ ] Typecheck/lint/tests pass locally
* [ ] Security/permission boundaries considered
* [ ] Docs updated if behavior changed
* [ ] Release note sentence included for user-facing changes

## Release Notes Guidance

When a PR changes behavior users/staff will notice, include:

1. What changed (plain language)
2. Why it matters
3. Any migration/config impact

## Architecture Decisions

For significant design choices:

1. Document context and tradeoffs in docs
2. Link to affected systems/pages
3. Capture migration path if needed

***

<CardGroup cols={2}>
  <Card title="Local Development" icon="laptop" href="/operations/local-development">
    Canonical setup guide
  </Card>

  <Card title="Deployment Workflow" icon="rocket" href="/operations/deployment-workflow">
    Branch, CI, and release flow
  </Card>
</CardGroup>