70 lines
3.9 KiB
Markdown
70 lines
3.9 KiB
Markdown
---
|
||
name: changelog
|
||
description: Update the public changelog for the Carlos Arias site (carlosarias.co, the /changelog page). Use whenever asked to "update the changelog", "log a change", "add a changelog entry", or to record that something was added, updated, fixed, or found broken. The changelog is a curated narrative seeded from api/cli/seed-changelog.php into the cja_changelog table and read at build time — this skill covers the exact entry format, the valid types, the voice, and the reseed + rebuild steps.
|
||
---
|
||
|
||
# Skill: update the changelog
|
||
|
||
The public changelog (`/changelog`) is a **curated narrative**, not an accreting log. Its
|
||
single source of truth is the `$entries` array in **`api/cli/seed-changelog.php`**. That
|
||
script **TRUNCATEs and reloads** the `cja_changelog` table every run, and the static site
|
||
reads that table **at build time** (`app/src/lib/changelog.js`). So the process is always:
|
||
|
||
1. **Edit** `api/cli/seed-changelog.php` — append (or amend) entries in the `$entries` array.
|
||
2. **Reseed** the table: `php api/cli/seed-changelog.php`
|
||
3. **Rebuild** the site so `/changelog` reflects it.
|
||
|
||
Editing the file alone changes nothing live — steps 2 and 3 are required.
|
||
|
||
## Entry format
|
||
|
||
Each entry is a 4-element array: `[type, summary, detail, 'YYYY-MM-DD HH:MM']`
|
||
|
||
```php
|
||
['added', 'Contact form wired up', 'Real submissions stored in the database, with validation and spam protection.', '2026-07-23 12:14'],
|
||
```
|
||
|
||
- **type** — one of: `added`, `updated`, `fixed`, `bug`, `removed`, `note`.
|
||
Use `bug` to record that something broke, and a paired `fixed` for the repair (see the
|
||
existing bug→fixed pairs for the pattern).
|
||
- **summary** — the headline (≤ 255 chars). Sentence case, no trailing period.
|
||
- **detail** — one sentence of context (≤ 500 chars), or `null` for none. Ends with a period.
|
||
- **timestamp** — `'YYYY-MM-DD HH:MM'` (seconds are appended automatically). **This is what
|
||
orders the timeline** — the page shows entries newest-first by this value, not by array
|
||
position — so a new entry can go anywhere in the array as long as its timestamp is right.
|
||
Use the real date/time the change happened; if unknown, use now.
|
||
|
||
## Voice
|
||
|
||
Match the existing entries: **write for a visitor, not for the repo.** Describe what changed
|
||
on the site from a reader's point of view, in plain past tense. Concise, understated, no hype,
|
||
no exclamation marks, British-leaning spelling ("optimised", "colour") to match the set.
|
||
|
||
- Good: `['added', 'Project galleries and social rail', 'A photo gallery with a lightbox, and a sticky Instagram rail beside each case study.', '...']`
|
||
- Avoid internal mechanics: not "Added a getStaticPaths loop over cja_projects" but "Per-project case-study pages generated from the database."
|
||
- One change = one entry. A bug and its fix are two entries (a `bug` then a `fixed`).
|
||
|
||
## Steps in full
|
||
|
||
```bash
|
||
# 1. edit api/cli/seed-changelog.php — add your entry to the $entries array
|
||
|
||
# 2. reseed the table (truncate + reload the curated set)
|
||
php api/cli/seed-changelog.php # prints "seeded N changelog entries"
|
||
|
||
# 3. rebuild so /changelog is live
|
||
# - preferred: the console runner rebuilds (POST /devconsole/rebuild), OR
|
||
# - direct (never as root — build as the site owner):
|
||
cd app && npm run build
|
||
```
|
||
|
||
## Constraints & gotchas
|
||
|
||
- **Don't INSERT rows directly** into `cja_changelog` — the next reseed would wipe them. The
|
||
seed file is the source of truth; always edit it.
|
||
- **Never build as root** — it leaves root-owned files that break later builds. Build via the
|
||
runner or as the site's agent user (see `agents/console/SETUP.md`).
|
||
- **No shell? (confined headless agent)** — you can still do step 1 (edit the seed file with
|
||
Write/Edit), but you cannot run steps 2–3. In that case, make the edit and clearly report
|
||
that `php api/cli/seed-changelog.php` + a rebuild are still needed for it to go live.
|
||
- The `detail` column is capped at 500 chars and `summary` at 255 — keep both tight.
|