patch-update

name

patch-update

description

Walks through the ship-day site update for a Positron patch release. Bumps versions, copies the new patch entry from next.md into release.md, resets next.md, refreshes _freeze, and opens the PR. Use when the user starts the ship-day PR for a patch (typically invoked as /patch-update). The earlier "Prepare release notes" PR that lands patch content into next.md is a separate workflow and is not part of this skill.

Patch release update

The pattern is well-established. Reference ship-day PRs: #277 (2026.02.1, first patch of month), #334 (2026.04.1, first patch), #357 (2026.05.1, first patch), #360 (2026.05.2, subsequent patch).

This skill assumes a separate "Prepare release notes" PR (e.g. #359) has already merged. That earlier PR adds the new patch entry to release-notes/next.md and bumps NEXT_RELEASE in _environment to the upcoming patch version. The content in next.md ships to S3 for in-product release notes during the patch cycle, so by ship day it has already been reviewed; treat it as the source of truth for the patch description.

This skill is a guided checklist. Drive the mechanical edits; pause for user input where noted with ⏸.

1. Gather and derive inputs

Only one input from the user: the new patch's full version, e.g. 2026.05.2-3. Derive everything else.

a. Confirm the patch exists and capture its date

gh release view <new full version> --repo posit-dev/positron --json tagName,publishedAt --jq '"\(.tagName)  \(.publishedAt[:10])"'

If this exits non-zero or reports "release not found", stop and re-confirm the version with the user. On success, the printed YYYY-MM-DD is the patch release date.

b. Decompose the version

From YYYY.MM.N-BUILD:

• Display version = YYYY.MM.N (used in headings and link text)
• Tag = full version with -BUILD (used in URLs)
• Patch number = N (selects first-patch vs subsequent-patch handling in step 3)

c. Compute next month's .0

Decompose YYYY.MM.N. Increment MM; if MM == 12, roll over to YYYY+1 and MM = 01. Append .0. This is the new NEXT_RELEASE value.

• 2026.05.2-3 → next release 2026.06.0
• 2026.12.1-... → next release 2027.01.0

d. Sanity-check current state

grep RELEASE_VERSION _environment
grep NEXT_RELEASE _environment

Expected state on ship day (the prep PR has already merged):

• RELEASE_VERSION is the previously shipped tag (e.g. 2026.05.1-2 before shipping 2026.05.2-3, or 2026.05.0-179 before shipping 2026.05.1-2).
• NEXT_RELEASE matches the patch being shipped (e.g. 2026.05.2 before shipping 2026.05.2-3).

⏸ If NEXT_RELEASE does not match the new patch's YYYY.MM.N, the prep PR may not have merged yet. Stop and ask the user.

Then read release-notes/next.md. It should open with ### Patch notes, followed by one or more paragraphs (one per patch), followed by ### Release highlights. Confirm the last paragraph under ### Patch notes references the new patch's display version and tag; this is the entry that will be inserted into release.md verbatim in step 3.

e. Show the user the derived set for sign-off

New patch:         2026.05.2-3   (2026-05-14)
Display version:   2026.05.2
Patch number:      2     (first-patch handling: false)
Next release:      2026.06.0
Branch name:       patch-2026-05-2-is-released
Patch entry to insert into release.md (copied verbatim from next.md):
  The [2026.05.2 patch release](https://github.com/posit-dev/positron/releases/tag/2026.05.2-3) (2026-05-14) fixes ...

⏸ Wait for explicit confirmation before editing files.

2. Branch

git checkout main && git pull
git checkout -b patch-YYYY-MM-N-is-released

YYYY-MM-N uses the patch's year, month, and patch number, e.g. patch-2026-05-2-is-released. If a prior branch with that name exists, append a suffix.

3. File edits

_environment

RELEASE_VERSION="<new full version>"
NEXT_RELEASE="<next month .0>"

Both lines change. Reference: PR #360 went RELEASE_VERSION="2026.05.1-2" to "2026.05.2-3" and NEXT_RELEASE="2026.05.2" to "2026.06.0".

release-notes/release.md

Extract the new patch paragraph from release-notes/next.md. It is the last paragraph under ### Patch notes, just before the blank line preceding ### Release highlights. Copy it verbatim; do not rewrite.

First patch of the month (N == 1): release.md currently starts with ### Highlights. Replace just that heading with:

### Patch notes

<the extracted patch paragraph>

### Release highlights

The rest of release.md (the existing release content) stays untouched. See PRs #277, #334, #357 for shape.

Subsequent patch (N >= 2): release.md already has a ### Patch notes section with prior entries. Insert the new patch paragraph as a new paragraph after the last existing patch paragraph, before the blank line that precedes ### Release highlights. Order is chronological (oldest first, newest last). See PR #360 for shape.

release-notes/next.md

Overwrite with the contents of release-notes/release-notes-template.md. The patch content has already shipped to S3, so next.md returns to the empty-state stub.

4. Refresh _freeze

The site uses execute: freeze: auto. Re-render only the pages that reference _environment variables, not the whole site.

First, check which pages currently use the env vars:

grep -rln 'env RELEASE_VERSION\|env NEXT_RELEASE' --include='*.qmd' .

As of writing, the set is download.qmd and release-notes.qmd. If grep returns a new file, render it too.

quarto render download.qmd
quarto render release-notes.qmd

⏸ Show the user the resulting _freeze/ diff. Expect only version-string changes; flag anything unexpected.

Commit _freeze/ changes in a dedicated commit so the diff stays reviewable (e.g. Update `_freeze` , matching prior PRs).

5. Commit structure

Match the cadence of PRs #357 / #360:

1. Update site for YYYY.MM.N patch release (the three mechanical files: _environment, release-notes/release.md, release-notes/next.md).
2. Update `_freeze` (only _freeze/ files).

Heredoc commit messages so they format cleanly. Do not skip hooks.

6. PR

git push -u origin patch-YYYY-MM-N-is-released

PR conventions from past patch releases:

• Title: Update site for YYYY.MM.N patch release
• Body: one celebratory line. Past PRs have used Release is now out! 🚀, Release is now out! 🚢, or Release is out!. Pick one; reviewers read the diff, no summary needed.
• Base: main.

⏸ Confirm title and body with the user before running gh pr create. Do not merge automatically.

7. After the PR merges

Merging does not publish positron.posit.co. A merge to main republishes positron.posit.co/dailies only. Patches publish the same way monthly releases do: the Release Documentation Bundles workflow builds from main, reads RELEASE_VERSION from _environment, and publishes the rendered site to the root of gh-pages. So this PR has to merge before that workflow runs.

⏸ Tell the user this step is still outstanding once the PR merges. Leave the workflow run to them.

Once it finishes, the footer on the live site should read the new patch version, and the patch notes should be at https://positron.posit.co/download.html#release-notes.

Style and repo conventions

• No em dashes in file contents (repo style preference). Use commas, semicolons, parentheses, or two sentences.
• Sentence case for headings.
• Screenshot updates for the new patch (e.g. PR #361 followed PR #360) are handled in a separate PR, not bundled here.
• Downstream doc edits (faqs, troubleshooting, etc.) are rarely needed for patches. If the patch ships a notable behavior change that dates other pages, suggest the user open a separate PR rather than bundling here.

Things to watch for

• If next.md does not have a ### Patch notes section, the prep PR likely has not merged yet. Stop and ask the user before proceeding.
• The display version in the link text (X.Y.N) and the tag in the URL (X.Y.N-BUILD) are different. Do not confuse them. PR #334 shipped with the link text reading 2026.04.0 patch release while the tag was 2026.04.1-10; that was a typo. Use the correct display version YYYY.MM.N in the link text.
• RELEASE_VERSION keeps its -BUILD suffix (e.g. 2026.05.2-3), but NEXT_RELEASE does not (e.g. 2026.06.0). Match the format of the lines you are replacing.