# Contributing / Release workflow

## Commit message format

This repo uses [Conventional Commits](https://www.conventionalcommits.org/).
The `.github/workflows/auto-version.yml` workflow reads your commit
messages and decides whether to cut a release automatically.

### Cheat sheet

| Prefix | Release type | Example |
|---|---|---|
| `fix:` | patch (6.1.1 → 6.1.2) | `fix: correct age parser off-by-one for "4y 11m"` |
| `feat:` | minor (6.1.1 → 6.2.0) | `feat: add vitals quick-copy button` |
| `feat!:` (or `BREAKING CHANGE:` in body) | major (6.1.1 → 7.0.0) | `feat!: require re-login after argon2 migration` |
| `docs:` | no release | `docs: update mobile build guide` |
| `refactor:` | no release | `refactor: split audit queue into its own module` |
| `chore:` | no release | `chore: bump eslint dep` |
| `test:` | no release | `test: add encounter version-lock test` |
| `style:` | no release | `style: prettier pass on calculators.js` |
| `ci:` | no release | `ci: cache node_modules in Actions` |
| `build:` | no release | `build: add DATA_ENCRYPTION_KEY to .env.example` |

**Only `fix:`, `feat:`, and `!:` / `BREAKING CHANGE` trigger a version bump and a release.**
Everything else is committed and pushed but doesn't tag.

### Decision tree

Ask yourself:

1. **Did behavior change for the user?**
   - No → `docs:`, `refactor:`, `chore:`, `test:`, `style:`, `ci:` (no release)
2. **Yes. Is it a bug fix?**
   - Yes → `fix:` (patch)
3. **New feature or enhancement?**
   - Yes → `feat:` (minor)
4. **Does it break existing behavior** (users have to log out, re-configure, migrate data, etc.)?
   - Yes → `feat!:` or `fix!:` (major)

### Skip the workflow entirely

Append `[skip ci]` anywhere in the commit message to suppress the
auto-version run for that commit (e.g., for emergency one-off fixes
you want to batch under a later release).

## Manual release (emergency override)

From the Actions tab → **Version bump & release** → Run workflow →
pick patch / minor / major (or type exact version) → Run. Skips
commit-message parsing and bumps exactly as requested.

Or locally:
```bash
scripts/release.sh 6.1.2 --push
```

## After a release is cut

The tag push (whether from auto-version, manual dispatch, or local
script) fires two parallel workflows:

| Workflow | Output | Time |
|---|---|---|
| `android-release.yml` | signed `pedscribe-X.Y.Z.apk` on the GitHub release | ~8 min |
| `docker-publish.yml`  | `danielonyejesi/pediatric-ai-scribe-v3:X.Y.Z` + `:latest` on Docker Hub | ~4 min |

Obtanium users, Docker Hub subscribers, and the login page's
"Download APK" link all update without further action.