# Contributing

## Commit format

[Conventional Commits](https://www.conventionalcommits.org). Nothing parses
these automatically any more — the auto-version workflow was a GitHub one and
this repository has no GitHub remote — but the prefixes still say what a change
is, and `scripts/release.sh` still wants a version chosen the same way.

| Prefix | Bump | |
|---|---|---|
| `fix:` | patch | bug fix |
| `feat:` | minor | new feature |
| `feat!:` / `fix!:` / `BREAKING CHANGE:` in body | major | breaking change |
| `docs:` `refactor:` `chore:` `test:` `style:` `ci:` `build:` | none | no release |

## Manual release

```bash
scripts/release.sh 6.2.0 --push       # bump, commit, tag, push
```

## Branches

`main` is production. It is what `scripts/deploy.sh` deploys and what the
container registry publishes from. `dev` is where work lands first.

```
feature work ──▶ dev ──▶ (tests pass, you try it) ──▶ main ──▶ deploy
```

| Branch | On push, CI does | Publishes an image |
|---|---|---|
| `dev` | runs the test suite, then builds the image | no |
| `main` | runs the test suite, builds the image, pushes it to the registry | yes |

`dev` builds the image but does not publish it, so nothing on `dev` can be
mistaken for something deployable. Both branches prove the same two things —
the tests pass and the image builds — which is the point: by the time a change
reaches `main` the only new question is whether it is *right*, not whether it
works mechanically.

Deploying is never automatic. It is the **Deploy** workflow, run by hand from
the Actions tab, after you have looked at the change. That is deliberate: the
step between "tests pass" and "this is live" is a person deciding, and a push
is not a decision. `scripts/deploy.sh` then pins the image, waits for health,
asks `/api/build` which revision is actually serving, and rolls back if the
answer disagrees.

To merge up:

```bash
git checkout main && git merge --no-ff dev && git push forgejo main
```

`--no-ff` keeps the merge visible, so a release is one commit to point at and
one commit to revert.

## Local dev

```bash
docker compose up -d                  # Postgres + app
docker logs -f pediatric-ai-scribe
```

Web changes hot-reload via browser refresh (JS/CSS cached 1h — add `?v=` query
or clear cache; the build-ID server-side cache-buster appends `?v=<git SHA>`
automatically on fresh page loads).

Server code changes require `./scripts/build-image.sh && docker compose up -d --no-build`.

## DB migrations

`src/db/database.js` is the baseline (idempotent CREATE-IF-NOT-EXISTS). New
changes go in `migrations/` via `node-pg-migrate`. See `docs/migrations.md`.