From 4832981e25a6ec64c1bb0d82382aab834b645181 Mon Sep 17 00:00:00 2001 From: Oier Bravo Urtasun Date: Tue, 19 May 2026 01:48:09 +0200 Subject: [PATCH] docs(fase-17): history doc + bump version to 1.0.0-rc.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes Fase 17 (v1.0 · 1/4). Bumps package.json `version` to `1.0.0-rc.0` — picked up by apps/web/vite.config.ts's `__APP_VERSION__` define, so the next built bundle reads it. The plain `1.0.0` tag is reserved for the close of Fase 20 (Euskera locale) per the v1.0 plan. Updates CLAUDE.md to mark the v1.0 cycle as in-progress (1/4 ✅) and adds the per-fase history docs (Fase 13–17) to the documentation map. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 9 +- docs/history/fase-17-versioning-changelog.md | 92 ++++++++++++++++++++ package.json | 1 + 3 files changed, 100 insertions(+), 2 deletions(-) create mode 100644 docs/history/fase-17-versioning-changelog.md diff --git a/CLAUDE.md b/CLAUDE.md index ceead50..02b1a68 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,7 +10,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co **Fase 16: loading spinner** — `Spinner.svelte` (sizes sm/md/lg = 16/24/40px, `currentColor` for theme, `motion-reduce:animate-none`, `role="status"` + sr-only `m.loading()`) integrated at 7 loading sites (auth splash + search + notes archive + create-collective modal + manage page: members-list / invite generator / add-common-item button). No DB migration; reuses existing `m.loading()`. Added 5 Vitest unit (SP-U-01..05) + 3 Playwright e2e (SP-E-01..03). Vitest config gained `resolve.conditions: ['browser']` + `server.deps.inline: [/^svelte/]` so Svelte 5's `mount()` resolves the browser entry; see `docs/history/fase-16-spinner.md`. **Final cumulative MVP2 (fases 9–16): 177 pgTAP + 179 Vitest integration + 52 Vitest unit + 96 Playwright + 1 gated rate-limit = 505 tests green; 3 skipped.** -**v1.0 — planned (📋):** four fases on `mvp2` branch (will retag at the end). Aimed at producing the first tagged release: **Fase 17 versioning** — git tags (`vX.Y.Z` semver), `CHANGELOG.md` in repo root (Keep-a-Changelog format, `[new]/[fix]/[tweak]` prefixes), one big `[v0.0.0-beta]` backfill section covering Fases 0–16, About-modal in `/settings` rendering bundled CHANGELOG via `?raw` import, deploy-script tag check + tag column in `.deploys.log` (`plan/fase-17-versioning-changelog.md`) | **Fase 18 shopping list flow** — required title (client + DB tightening), `#N` auto-numbering parsed from prefix per collective, `collectives.default_list_title` + `collective_list_titles` catalog with admin-only RPCs, autocomplete union catalog + last-10 titles (`plan/fase-18-shopping-list-flow.md`, migration 027) | **Fase 19 emoji avatars** — `EMOJI_CATALOG` lazy-load per category (faces / food / animals / objects, ~280 codepoints, Unicode 14 baseline for iOS<17 compat), new `EmojiPicker.svelte` replacing the 8-emoji hardcoded selector at 4 sites (`plan/fase-19-emoji-avatars.md`, no migration) | **Fase 20 Euskera locale** — `messages/eu.json` via machine-translate seed + `[needs review]` marker, `users.language` check constraint extended to `('en','es','eu')`, `accept-language` parser + selector in `/settings`; v1.0.0 tag lands at the end of this fase (`plan/fase-20-euskera-locale.md`, migration 028). +**v1.0 — in progress (1/4 ✅):** four fases on `mvp2` branch (will retag at the end). Aimed at producing the first tagged release. **Fase 17: versioning + CHANGELOG + about modal** — shipped 2026-05-19 (`docs/history/fase-17-versioning-changelog.md`); root `CHANGELOG.md` with `[v0.0.0-beta]` backfill of Fases 0–16 (58 bullets, `[new]/[fix]/[tweak]` prefixes), `scripts/check-changelog.mjs` linter wired into `just check`, `ChangelogModal.svelte` rendering the CHANGELOG via `?raw` build-time import (5 levels up from the component file), `/settings` › About "Ver historial" trigger, deploy-script HEAD tag warn (5s) + 4th `` column appended to `.deploys.log` (compat-safe; rollback `--list` surfaces it), `package.json` bumped to `1.0.0-rc.0` + local `v1.0.0-rc.0` tag (no push). | **Fase 18 shopping list flow** — required title (client + DB tightening), `#N` auto-numbering parsed from prefix per collective, `collectives.default_list_title` + `collective_list_titles` catalog with admin-only RPCs, autocomplete union catalog + last-10 titles (`plan/fase-18-shopping-list-flow.md`, migration 027) | **Fase 19 emoji avatars** — `EMOJI_CATALOG` lazy-load per category (faces / food / animals / objects, ~280 codepoints, Unicode 14 baseline for iOS<17 compat), new `EmojiPicker.svelte` replacing the 8-emoji hardcoded selector at 4 sites (`plan/fase-19-emoji-avatars.md`, no migration) | **Fase 20 Euskera locale** — `messages/eu.json` via machine-translate seed + `[needs review]` marker, `users.language` check constraint extended to `('en','es','eu')`, `accept-language` parser + selector in `/settings`; v1.0.0 tag lands at the end of this fase (`plan/fase-20-euskera-locale.md`, migration 028). ## Documentation Map @@ -22,7 +22,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co - `docs/history/fase-9-polish-dark-mode.md` — MVP2 dark mode + reading width + sync-conflicts debug panel - `docs/history/fase-10-spec-completion.md` — MVP2 CU-H06/H07/H08 + trash RPCs + account delete + sidebar create + reset from detail + auto language - `docs/history/fase-11-item-tags-importance.md` — MVP2 item tags + drag-reorder -- `docs/history/fase-12-section-visibility.md` — MVP2 section visibility / feature flags (this fase) +- `docs/history/fase-12-section-visibility.md` — MVP2 section visibility / feature flags +- `docs/history/fase-13-server-admin.md` — MVP2 server administration +- `docs/history/fase-14-pwa-hardening.md` — MVP2 PWA hardening (auto-update + version chip) +- `docs/history/fase-15-common-items.md` — MVP2 common items management +- `docs/history/fase-16-spinner.md` — MVP2 loading spinner +- `docs/history/fase-17-versioning-changelog.md` — v1.0 versioning + CHANGELOG + about modal - `analysis/analisis-funcional.md` — complete functional specification (domain model, use cases, data models, business rules) - `plan/fase-*.md` — phase-by-phase implementation plans (Fase 0 through Fase 7) - `design/slate_collective/DESIGN.md` + `design/*/screen.png` — "Monolith Editorial" direction + per-screen Stitch mockups. Consult before changing UI. diff --git a/docs/history/fase-17-versioning-changelog.md b/docs/history/fase-17-versioning-changelog.md new file mode 100644 index 0000000..87c79d4 --- /dev/null +++ b/docs/history/fase-17-versioning-changelog.md @@ -0,0 +1,92 @@ +# 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 , 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: ` 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 `

Changelog

`. + - 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 + `

Changelog

` + 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. diff --git a/package.json b/package.json index 503965b..de3dff0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,7 @@ { "name": "colectivo", "private": true, + "version": "1.0.0-rc.0", "scripts": { "build": "turbo run build", "dev": "turbo run dev --parallel",