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.