The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 07:15 UTC
| 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 (``), |
| 174 | save the text to `/tmp/tweets-<next>/tweets.md`, and note that no tweet has a |
| 175 | link yet. Never post them. |