The best way to control Claude Code, Codex and more from any computer or phone

main
md 175 lines 8.98 KB
Rendered Raw
1 ---
2 name: release-blog
3 description: Write the next alchemy release blog post — find the last `chore(release)` commit on origin/main, read the description of every PR merged since, plan the headline sections (Effect upgrades, new providers, new features, major bug fixes, breaking changes) with DX-first code snippets, fold the rest into "Also in this release", credit contributors, check every link and diff block, and (when asked) draft one tweet per category with a screenshot of its section. Use for "write the release blog", "prepare the next release post", "/release-blog", "blog for beta.N", "write tweets for the release".
4 metadata:
5 internal: true
6 ---
7
8 # Write the release blog
9
10 The post covers every PR merged to `origin/main` since the most recent
11 `chore(release)` commit, and announces the next version. The house rules for
12 release posts live in AGENTS.md ("Blog / Release Notes Conventions"); this
13 skill is the procedure. Read the last two posts in
14 `website/src/content/docs/blog/` (`*-beta-*.md`) before writing. They set the
15 voice, length and structure to match.
16
17 ## 1. Collect every PR
18
19 ```sh
20 .agents/skills/release-blog/scripts/collect-prs.sh /tmp/release-blog-<next>
21 ```
22
23 It prints the release commit (`chore(release): 2.0.0-beta.N`, so the post is
24 for `beta.N+1`) and writes one JSON per PR, a `digest.txt` with every PR's
25 title, author and full body (oldest first), and `authors.txt` with every
26 non-maintainer author's display name.
27
28 ## 2. Read every description in full
29
30 Read all of `digest.txt`, in chunks, start to finish. It holds whole bodies,
31 on purpose: a PR's later sections ("### Changes", a second snippet, a
32 "Removed" list) are where secondary features and renames hide, and a post
33 planned from excerpts folds them into a clause or drops them. Don't sample,
34 and don't skim by title: a `chore` or `test` title can carry a user-facing
35 fix, and a `feat` body often holds the best snippet for the post.
36
37 Tag each PR as you go:
38
39 - **breaking**: `!` in the title, or `Breaking`/`[!CAUTION]` in the body. Note
40 the migration diff the PR gives. Unmarked PRs break things too: look for
41 "renamed", "removed", "replaces", "is gone", "now requires", "`X` is now
42 `Y`" and "was `X`" in every body. Confirm each one shipped in the last
43 release (`git grep <old name> <release-sha> -- packages/`) before listing
44 it; a rename of something added in this same release isn't breaking.
45 - **headline**: a dependency upgrade users must make (Effect, a framework
46 major), a new provider or package, a new capability with a user-facing API,
47 or a major bug fix (data loss, wrong resource deleted or taken over,
48 deploys that hang or fail, large perf or bundle wins).
49 - **also**: smaller features and fixes users would notice.
50 - **skip**: internal only. CI, skills, lint and repo tooling, test-only PRs
51 that fix no shipped behavior, distilled bumps without a user-visible change,
52 docs restyles, and fix-ups of earlier PRs in the same release.
53
54 Group related PRs into one item: a stack of PRs for one feature is one
55 section, and a family of fixes (drift, ownership, local dev) is one bullet.
56
57 ## 3. Plan before writing
58
59 Write the plan out first: the title, the breaking-change list, the ordered
60 headline sections with the PRs each one cites, and the also-list groups.
61
62 - **Title**: `2.0.0-beta.N - <three short items>`. It renders in the blog
63 sidebar, so it must fit on one line.
64 - **Order the headlines** by how much they change a user's day: required
65 upgrades (Effect) first, then new providers and packages, then the biggest
66 new capabilities, then major fixes. There is no cap on the number of
67 sections; a large release gets 25–30. Its size is set by what shipped.
68 - **A new user-facing API gets a snippet**, in its own section or in a
69 section about its area (a "New AWS resources and options" section collects
70 smaller ones). Never shrink one into a clause of an unrelated section: a
71 reader skimming headings must find it. A PR that adds several APIs (a store
72 that gains `accountId`, `workerName` and `domain` plus a new bootstrap
73 command) is usually its own section.
74 - **Everything else** goes into `## Also in this release`, grouped by area
75 (Cloudflare features, Cloudflare fixes, Local dev fixes, AWS features, AWS
76 fixes, GCP, Domain, Auth, …), each group one bullet with its PR links.
77
78 ## 4. Write it
79
80 File: `website/src/content/docs/blog/YYYY-MM-DD-beta-NN.md`, dated the
81 release day (ask if it isn't today). Frontmatter `title`, `date`,
82 `category: release` and a one-sentence `excerpt`.
83
84 - Open with two short paragraphs naming the headline features in bold.
85 - `:::caution` with **Breaking changes** at the top. Each item says what to
86 do, with a `diff` snippet when code changes, and links its section below.
87 - One `##` per headline. One or two sentences, then a snippet of the
88 user-facing API. Show DX, not implementation: what you write, what you get,
89 the before/after error or output. Take snippets from the PR bodies, trim
90 them, and check the names against the source (`grep` the export) since PRs
91 get renamed in review.
92 - End a section with `Docs: [Page](/path)` links when a page covers it.
93 - Cite PRs inline as `([#NNN](https://github.com/alchemy-run/alchemy/pull/NNN))`.
94 - Credit external contributors by display name from `authors.txt`, linked to
95 their GitHub profile: `Thanks [Name](https://github.com/login)!`. Use the
96 login when there's no display name. PRs a maintainer opened on someone's
97 behalf say so in the body ("carries #N by", "ported from", "supersedes");
98 credit that person.
99 - End with `## Where to go next`: doc links, then
100 `[CHANGELOG](https://github.com/alchemy-run/alchemy/blob/main/CHANGELOG.md#v200-betaNN)`
101 and `[Compare v2.0.0-beta.N → v2.0.0-beta.N+1](https://github.com/alchemy-run/alchemy/compare/v2.0.0-beta.N...v2.0.0-beta.N+1)`.
102
103 Format every snippet the way oxfmt would at an 80-column print width (the
104 blog's code column), and move trailing comments that overflow onto their own
105 line. oxfmt reads a top-level `yield*` as multiplication, so format such
106 snippets by hand or inside a temporary `function* () {}` wrapper.
107
108 Style: plain, direct sentences; no marketing adjectives; no "X just
109 happened" lists explaining a snippet. Every ```diff block needs a context line
110 at column 0 (a comment, an import, the outer call), and `+`/`-` lines are the
111 marker followed by the line's real indentation. Inline code that contains a
112 backtick uses double-backtick delimiters.
113
114 ## 5. Check it
115
116 ```sh
117 python3 -I .agents/skills/release-blog/scripts/check-post.py website/src/content/docs/blog/<post>.md /tmp/release-blog-<next>
118 ```
119
120 It checks that every docs link and anchor resolves and that every diff block
121 passes the website build's odd-indent check. Fix every problem it reports.
122 It also lists every `feat`, `fix`, `perf` or `!` PR the post doesn't cite.
123 Each one must be a deliberate skip (a fix-up of another PR in this release,
124 test or CI only); cite the rest.
125
126 Then hand the post to the user with the headline plan (sections and the PRs
127 behind each), the breaking-change list, and anything you weren't sure about:
128 a PR whose user impact was unclear, a section you cut, or the date. Don't
129 commit, push or open a PR unless asked.
130
131 ## 6. Tweets (when asked)
132
133 One tweet per major category, in the post's order: Effect, each headline
134 Domain feature, each headline provider feature, state, CLI, and one for the
135 bug fixes. Each tweet is one sentence plus a screenshot of its section.
136
137 **The sentence** states the user-facing change and, when the post has one,
138 its number: "a million accounts in 8 minutes", "plans are 270× faster".
139 Plain words, no hype, no hashtags, no emoji. Take every claim from the post,
140 not from memory.
141
142 **The screenshot** is the section's heading plus its code, diagram or table,
143 with the prose between them hidden. Run the docs dev server
144 (`cd website && bunx astro dev --ignore-lock`), list each heading's blocks,
145 then write a `shots.json` that picks them:
146
147 ```sh
148 PW=$(ls -d node_modules/.pnpm/playwright-core@*/node_modules | tail -1)
149 URL=http://localhost:4321/blog/<post-slug>/
150 NODE_PATH=$PW bun .agents/skills/release-blog/scripts/screenshot-sections.mjs $URL --list
151 NODE_PATH=$PW bun .agents/skills/release-blog/scripts/screenshot-sections.mjs $URL /tmp/tweets-<next> shots.json
152 ```
153
154 ```json
155 {
156 "01-effect-41": [["effect-41", "h"], ["effect-41", 1], ["effect-41", 3]],
157 "02-domain-rollout": [
158 ["deploys-roll-out-every-change-to-a-model", "h"],
159 ["how-it-scales", 1],
160 ["how-it-scales", 5]
161 ]
162 }
163 ```
164
165 Each entry is `[heading id, "h" | n]`, where `n` is the block index `--list`
166 prints under that heading; blocks can come from different headings. Images
167 are dark mode at 2× resolution, and animated figures render their last frame.
168 Pick the block that shows the change best: the diagram over the prose, the
169 failure output over the test code, the before/after table over the setup.
170 Open every image and check that no code line is cut off and no neighbouring
171 text shows.
172
173 Show each tweet inline with its image (`![](/tmp/tweets-<next>/NN-name.png)`),
174 save the text to `/tmp/tweets-<next>/tweets.md`, and note that no tweet has a
175 link yet. Never post them.