From f5a10419de5e6d34f55ba8f784ab5dfee7a1e9c1 Mon Sep 17 00:00:00 2001
From: Daniel <daniel@danvics.com>
Date: Tue, 14 Apr 2026 23:51:09 +0200
Subject: [PATCH] docs: add CONTRIBUTING.md + .gitmessage template for
 conventional commits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drops a cheat sheet (CONTRIBUTING.md) in repo root so anyone — you,
future maintainers — has the full commit-prefix table one glance
away. Covers which prefixes trigger a release and which don't.

Also adds .gitmessage that you can optionally wire into git as the
default commit template:

  git config --local commit.template .gitmessage

Opens the cheat sheet in your editor every time you `git commit`
without -m. Remove it with `git config --local --unset commit.template`.

This commit uses `docs:` prefix so it does NOT trigger a release —
proving the auto-version workflow's filter works.
---
 .gitmessage     | 22 ++++++++++++++++
 CONTRIBUTING.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 .gitmessage
 create mode 100644 CONTRIBUTING.md

diff --git a/.gitmessage b/.gitmessage
new file mode 100644
index 0000000..0d1f407
--- /dev/null
+++ b/.gitmessage
@@ -0,0 +1,22 @@
+# <type>: <short summary>
+#
+# Types that cut a release:
+#   fix:   → patch (6.1.1 → 6.1.2)   bug fix
+#   feat:  → minor (6.1.1 → 6.2.0)   new feature
+#   feat!: → major (6.1.1 → 7.0.0)   breaking change
+#
+# Types that commit but don't release:
+#   docs:     documentation
+#   refactor: code reshape, no behavior change
+#   chore:    tooling, deps, housekeeping
+#   test:     tests only
+#   style:    formatting / whitespace
+#   ci:       CI/CD configuration
+#   build:    build system / external deps
+#
+# Full reference: https://www.conventionalcommits.org/
+# Or see CONTRIBUTING.md in this repo.
+#
+# ---- body below (optional) -------------------------------------------
+# Explain the WHY more than the what. Breaking changes must include a
+# line starting with "BREAKING CHANGE: <description>".
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..412aa88
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,68 @@
+# 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.