Skip to content

armgit / memos

Public Imported from GitHub
0

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.

chore: add agent release playbook

boojack0d989707f82c
diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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`.