Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.
Go dockerfossgomarkdownmemomicroblognote-takingnotesopen-sourceown-your-datareactself-hostedsqlitetimeline
chore: add agent release playbook
boojack0d989707f82c
diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.mdnew file mode 100644index 000000000..e5649b253--- /dev/null+++ b/.agents/skills/release/SKILL.md@@ -0,0 +1,128 @@+---+name: release+description: >+ Own a Memos release end to end: pick the next CalVer tag, verify the candidate+ commit, draft release notes, push the tag, watch the Release workflow, recover+ from failures, verify published binaries and images, and publish the notes.+ Use when the user asks to cut, ship, promote, or check a Memos release or+ release candidate. Do not use for canary images or demo deploys.+metadata:+ owner: "boojack"+ version: "1.0.0"+ last-reviewed: "2026-10-02"+---++# Release++Pushing a tag is the only release action. `.github/workflows/release.yml` then runs the upgrade smoke test, builds binaries and+checksums, publishes the GitHub Release, and pushes `neosmemo/memos` and `ghcr.io/usememos/memos` images. Your job is everything+around that tag: choose it, gate it, explain it, watch it, and prove the result.++## Ground Rules++- Never release from the user's working tree. Tag a commit SHA that is on `origin/main`; uncommitted or unpushed local work is+ not part of the release. Do not stash, commit, push to main, or rebase for a release.+- A request to run this skill authorizes fetching, dispatching `release.yml` or `upgrade-smoke.yml` on main, rerunning failed+ jobs, and editing the notes of the release you created. Reading the skill authorizes nothing.+- Pushing the tag publishes to GitHub, Docker Hub, and GHCR. Before that push, show the plan and wait for an explicit go, unless+ the user's request already named the tag (or "next rc"/"next stable") and said to proceed without asking.+- Never delete, move, or force-push a pushed tag, and never delete a published release or image, without the user's explicit+ approval for that specific tag. The default recovery is the next tag number.+- Use lightweight tags (`git tag <tag> <sha>`), matching existing tags.++## 1. Establish State++```bash+git fetch origin --tags --prune+git rev-parse origin/main+bash scripts/release_version.sh previous-tag . # last stable before HEAD; run in a checkout of the candidate+gh release list --limit 10+```++Record: candidate SHA (default `origin/main`), the last stable tag, any release candidates after it and the commits they point+to, and whether the working tree differs from the candidate (mention it; do not touch it).++## 2. Choose the Tag++Format is `YY.MM[.N][-rc.N]` (validated by `scripts/release_version.sh` and `internal/version`). `YY.MM` is the current UTC month.++- **New stable:** `YY.MM` if no stable tag exists for this month, else `YY.MM.<N+1>`.+- **New release candidate:** the next stable version plus `-rc.<N+1>`, counting existing candidates for that version.+- **Promote a candidate:** the candidate's base version, tagged on the candidate's commit. Promotion keeps the base version+ even if the month has changed. If main moved past the candidate, ask whether to promote the candidate commit or cut a new+ candidate from main.++Recommend a candidate first when the range since the last stable includes migrations (`store/migration/`), proto API changes,+auth or permission changes, or more than a few weeks of features. Patch releases with only fixes can go straight to stable.++## 3. Gate the Candidate++All must pass before you propose the tag:++1. The tag does not exist locally or on origin, and no release with that name exists.+2. The candidate SHA is reachable from `origin/main`.+3. CI is green. Push to main runs Backend Tests, Frontend Tests, and Proto Linter on every commit:+ `gh run list --commit <sha> --json name,status,conclusion`. Require each of those three to be `completed/success`. Wait for+ in-progress runs; a failure blocks the release.+4. For a stable tag that is not a promotion, do a dry run first: `gh workflow run release.yml --ref main`, confirm the run's+ `headSha` is the candidate, and wait for success. The dry run runs the upgrade smoke and every binary build without+ publishing, so a failing build costs no tag number. Skip it for candidates and promotions, which act as their own dry run.++## 4. Draft the Notes++Write notes for the range from the last stable tag to the candidate, following [release-notes.md](references/release-notes.md).+Read the commits, the merged PRs (`gh pr view`), and the diff for migrations, proto changes, configuration flags, and removed+behavior. Save the draft in a temporary directory outside the repo.++## 5. Propose, Then Tag++Show the user: tag, candidate SHA and subject, last stable tag, commit count, gate results, image tags that will move (from+`bash scripts/release_version.sh image-tags <tag>`), and the drafted notes. After an explicit go:++```bash+git tag <tag> <sha>+git push origin <tag>+```++## 6. Watch the Release Run++Find the run with `gh run list --workflow release.yml --event push --limit 5` and match `headBranch` to the tag. Watch it until it+completes. The jobs are upgrade-smoke, Extract Version, Build Frontend, six binary builds, Generate Checksums, Publish GitHub+Release, three image builds, and Publish Release Image Tags.++On failure, read the failed job's log (`gh run view <id> --log-failed`) and classify it:++- **Infrastructure** (runner loss, network timeout, registry rate limit or 5xx, action download failure): `gh run rerun <id>+ --failed`. Retry at most twice per run.+- **Defect** (test failure, compile error, smoke assertion, bad Dockerfile): stop. Do not rerun. Report the failing step,+ root cause, and the files involved. The fix lands on main through the normal workflow; after it is green, offer the next+ tag (next candidate number or next patch). The failed tag stays as is.+- **Partial publish** (GitHub Release published but images failed, or the reverse): report exactly which surfaces exist. Rerun+ only the failed jobs; they are idempotent for the same tag.++## 7. Verify the Published Release++Do not report success until each check passes:++1. `gh release view <tag> --json isPrerelease,isLatest,assets`: prerelease is true only for `-rc` tags, latest is true only for+ stable tags, and assets are exactly six archives (`linux_amd64`, `linux_arm64`, `linux_armv7`, `darwin_amd64`,+ `darwin_arm64`, `windows_amd64.zip`) plus `checksums.txt`.+2. Download `checksums.txt` and the archive for this machine into a temporary directory. Check it with `sha256sum -c` (or+ `shasum -a 256 -c`) against its line, then extract and run `./memos --version`, which must print the tag.+3. `docker buildx imagetools inspect neosmemo/memos:<tag>` and `ghcr.io/usememos/memos:<tag>`: both list `linux/amd64`,+ `linux/arm64`, and `linux/arm/v7`. For stable tags, `stable` and the series tag (when it differs from the tag) resolve to the+ same digest as `<tag>`.+4. If Docker can run locally, `./scripts/release_smoke_test.sh --candidate-image neosmemo/memos:<tag>` tests the published+ image. If Docker is unavailable, say so; do not skip it silently.++## 8. Publish the Notes++The workflow publishes GitHub-generated notes. Replace them with your draft, keeping the generated `## New Contributors` section+and `**Full Changelog**` line at the end: `gh release edit <tag> --notes-file <draft>`. Then read the release page back and check+that links resolve to the right PRs and commits.++## 9. Report++Give the release URL, tag, SHA, image tags and digest, verification results, any reruns and why, and anything not done. Out of+scope for this skill: announcements, website or docs updates, and the demo deploy (`demo-deploy.yml`, manual dispatch). List+them as follow-ups for the user rather than doing them.diff --git a/.agents/skills/release/references/release-notes.md b/.agents/skills/release/references/release-notes.mdnew file mode 100644index 000000000..631453db7--- /dev/null+++ b/.agents/skills/release/references/release-notes.md@@ -0,0 +1,40 @@+# Release Notes++Model new notes on the v0.31.0 release (`gh release view v0.31.0`). Notes are written for people who run Memos, not for+contributors: describe what changed for them, not how the code changed.++## Range and Sources++- Stable releases cover everything since the previous stable tag, including changes already described in its candidates.+- Candidates cover everything since the previous stable tag too, so testers see the whole release taking shape.+- Read every commit in the range: `git log --no-merges <prev>..<sha>`. For squash-merged PRs, read the PR title, body, and+ linked issue. For direct commits, read the diff.+- Drop changes users cannot observe: refactors, tests, CI, lint, dependency bumps without user effect, and internal docs.++## Structure++Stable releases use these sections in this order. Omit an empty section rather than padding it.++1. **Summary paragraph** (no heading): two sentences. Name the most important additions, then the areas that improved+ overall. Use the release's tag as the version, e.g. "Memos 26.10 adds…".+2. `## Highlights`: new capabilities, ordered writing first, then finding and browsing, then ownership and data.+3. `## Fixes and polish`: grouped by area (Editor, Markdown, Interface and languages, …).+4. `## Administration and integrations`: security, deployment, configuration, API, MCP, CLI.+5. `## Upgrade notes`: anything an operator or API client must know or act on. Check the range for `store/migration/` changes,+ proto field or RPC removals and renames, changed defaults, new or removed flags and environment variables, permission+ changes, and removed features. Say what changes on upgrade and what the reader must do.+6. Keep GitHub's generated `## New Contributors` section and `**Full Changelog**` line unchanged at the end.++Candidates use a shorter form: the summary paragraph, `### What's new`, `### Improvements and fixes`, and upgrade notes when+any apply. Add one line asking testers to report regressions in issues.++## Bullets++- Highlights and grouped sections use `* **Area:** sentence. (links)`. Group related changes into one bullet per area instead+ of one bullet per PR.+- Write in present tense from the user's side: "Browse memos by month", not "Added calendar component".+- Link every bullet to its sources: `[#1234](https://github.com/usememos/memos/pull/1234)` for PRs, and a short descriptive label+ linking the full commit URL for direct commits.+- Use product names as they appear in the app (Spaces, Views, Quick Find). Never call memos posts or messages.+- Do not mention plans, subscriptions, payments, or vendors.+- Do not credit tools or agents that helped produce the release.diff --git a/AGENTS.md b/AGENTS.mdindex 108b1a74f..d9744e924 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -139,6 +139,8 @@ Black-box service tests live in `server/api/v1/test/`, unit tests next to the co## CI Reference+- Releases are cut by pushing a `YY.MM[.N][-rc.N]` tag. To cut, promote, or check a release, follow+ `.agents/skills/release/SKILL.md`.- Development builds use the HEAD committer date in UTC as `YY.MM`; release builds inject the CalVer tag.- `go build` embeds Git metadata automatically; `go run` needs `-buildvcs=true`. Builds without Git metadata must inject`github.com/usememos/memos/internal/version.Version` through `-ldflags`.