collective-lists/docs/history/fase-17-versioning-changelog.md

# Fase 17 — Versioning + CHANGELOG + about modal (v1.0 · 1/4)

**Status: ✅ Shipped 2026-05-19.**

First fase of the v1.0 cycle. Lands the version-tracking infrastructure
that every later v1.0 fase will register entries against. No DB migration,
no new RPCs — pure tooling + UI plus the BETA backfill.

Plan: `plan/fase-17-versioning-changelog.md`.

## What changed

### 17.1 — `CHANGELOG.md` + Keep-a-Changelog linter

- New `CHANGELOG.md` at the repo root. Keep-a-Changelog header + `[Unreleased]` placeholder + one big `[v0.0.0-beta] — 2026-05-19 — MVP + MVP2 (Fases 0–16)` section. 58 bullets grouped by area: auth + identity, shopping lists + items, tasks + notes, search, mobile UX + a11y, PWA + offline, collective management, server admin, i18n, infra + deploy. Each bullet prefixed `[new] / [fix] / [tweak]`. Slightly over the 30–50 target range because 17 fases of feature surface is a lot to compress without losing signal.
- New `scripts/check-changelog.mjs` validates (a) the Keep-a-Changelog header line, (b) every release heading matches `## [vX.Y.Z] — YYYY-MM-DD` (semver-with-optional-prerelease), (c) every bullet starts with `[new] / [fix] / [tweak]`. Lines that end in `:` are exempt — they're the area sub-titles, intentionally prefix-less.
- Wired into `just check`. Exit code 2 on validation failure, 1 on missing file. No pre-commit hook — the plan's "warn-only" stance.

### 17.2 — `ChangelogModal.svelte` + `/settings` integration

- New `apps/web/src/lib/components/ChangelogModal.svelte`. CHANGELOG is bundled at build time via Vite's `?raw` query — the import path is `'../../../../../CHANGELOG.md?raw'` (5 levels up: `components → lib → src → web → apps → repo-root`). The plan estimated 3; the off-by-two is documented in the component's leading comment for anyone moving the file later.
- Inline markdown parser handles `#` / `##` / `###` headers, `-` / `*` bullets, `**bold**`. HTML-escapes every input line before re-wrapping with our own tags — the input is static repo content, so this is defence-in-depth rather than a sanitisation barrier.
- Layout reuses the `CreateCollectiveModal` overlay pattern: `fixed inset-0 z-50` overlay with `bg-black/40`, panel `max-w-2xl` centred, scrollable body `max-h-[70vh]`. Close via overlay-click or Escape.
- Three new Paraglide messages (en + es): `settings_about_view_changelog`, `changelog_modal_title`, `changelog_modal_close`.
- `/settings` › About section gains a discreet underlined text-button "Ver historial" beneath the existing version chip. Click sets `showChangelog = true`; the modal mounts at the bottom of the template so it stacks above the delete-account / leave-collective modals.

### 17.3 — deploy + rollback tag handling

- `infra/scripts/deploy-erosi.sh` now runs `git describe --exact-match --tags HEAD` before rsync. When HEAD is between tags, prints a yellow `WARNING` and sleeps 5s — operator can Ctrl-C, tag, and re-run. When a tag is present, the banner reads `commit <sha>, tag <tag>`.
- The success-log line in `.deploys.log` gains a 4th tab-separated column: the tag (empty when absent). Compat with pre-Fase-17 3-column rows is preserved — the rollback script's `cut -f1..3` keeps reading the older rows, and `cut -f4` returns empty.
- `infra/scripts/rollback-erosi.sh`:
  - `--list` reformats each row via awk so the tag is visible (placeholder `(no tag)` for pre-Fase-17 rows). Falls back to the raw log if awk isn't on PATH.
  - The target-row banner shows `git tag: <tag>` when present.

### 17.4 — Tests

- **Unit** (`apps/web/src/lib/components/ChangelogModal.test.ts`):
  - CHM-U-01 `open={false}` renders nothing.
  - CHM-U-02 `open={true}` renders the CHANGELOG `<h1 class="...">Changelog</h1>`.
  - CHM-U-03 overlay click fires `onClose`.
  - CHM-U-04 Escape fires `onClose`. Needs `flushSync()` from `svelte` after `mount()` because `$effect` runs in a microtask — without flushing, the keydown listener isn't attached when the test dispatches Escape.
- **Playwright** (`apps/web/tests/e2e/changelog.test.ts`):
  - CL-01 Ana opens `/settings`, clicks "Ver historial", asserts the modal + `<h1>Changelog</h1>` + a `/v0\.0\.0-beta/` match in the body.
  - CL-02 Esc closes the modal.
- **Linter test** is the script itself — runs at `just check` time.

### 17.Z — Version + tag

- `package.json` `version` bumped to `1.0.0-rc.0`. This is the start of the v1.0 cycle; the `1.0.0` (no suffix) tag is reserved for the close of Fase 20 (Euskera locale) per the plan.
- Local tag `v1.0.0-rc.0` created on HEAD via `git tag -a`. NOT pushed to the remote — that's a manual step the operator decides on.

## Test deltas (Fase 17 only)

| Suite | Before | After | Δ |
|---|---|---|---|
| pgTAP (`just test-db`) | 177 | 177 | 0 |
| Vitest integration (`just test-integration`) | 179 + 3 skipped | 179 + 3 skipped | 0 |
| Vitest unit (`just test-unit`) | 52 | 56 | +4 (CHM-U-01..04) |
| Playwright e2e (`just test-e2e`) | 96 | 98 | +2 (CL-01, CL-02) |
| Gated rate-limit | 1 | 1 | 0 |

## Files added

- `CHANGELOG.md`
- `scripts/check-changelog.mjs`
- `apps/web/src/lib/components/ChangelogModal.svelte`
- `apps/web/src/lib/components/ChangelogModal.test.ts`
- `apps/web/tests/e2e/changelog.test.ts`
- `docs/history/fase-17-versioning-changelog.md` (this file)

## Files modified

- `Justfile` — `check` recipe runs the linter before `pnpm turbo run check`.
- `apps/web/messages/en.json`, `apps/web/messages/es.json` — 3 new keys.
- `apps/web/src/routes/(app)/settings/+page.svelte` — About section trigger + modal mount.
- `infra/scripts/deploy-erosi.sh` — tag check + tag column in `.deploys.log`.
- `infra/scripts/rollback-erosi.sh` — `--list` shows tag, target banner shows tag.
- `package.json` — version `1.0.0-rc.0`.

## Decisions documented

1. **Bundle CHANGELOG via `?raw`, not fetch.** Avoids a runtime round-trip, dodges the SW precache miss, and works under adapter-node SSR without filesystem reads. Bundle size cost ~6 KB today. Revisit (dynamic import, marked, etc.) when it grows past ~30 KB or starts using non-trivial markdown (tables, code blocks).

2. **Tag check is warn + sleep, not abort.** Hotfix deploys must still be possible from untagged commits. The 5-second window is enough to Ctrl-C, tag, and retry without being annoying on regular tagged deploys.

3. **`.deploys.log` 4th column instead of a new file.** Backwards-compatible — older rows stay readable, the rollback script's existing `cut -f1..3` works, and `cut -f4` returns empty for pre-Fase-17 rows (the right "no tag" sentinel).

4. **No GitHub Releases sync, no push of tags from the deploy script.** Both are explicit non-goals in the plan §"Scope explícito fuera". Operator pushes tags manually if/when they want a public release page.

5. **Markdown parser inline, not `marked`.** Keep-a-Changelog only uses headers, lists, and bold — 30 lines of `String.replace` cover that. If a future entry needs tables / code blocks / links, swap to `marked` (~30 KB minified) at that point.

6. **5-levels-up `?raw` path, not 3.** The plan estimated 3; the actual depth from `apps/web/src/lib/components/` to the repo root is 5. The component comment documents the path explicitly so the next person who moves the file isn't surprised.