eiriktsarpalis/polytype/release-notes

Prepare a release for review

Prepare two artifacts for an upcoming PolyType release: a short, evidence-based # What's new overview and an uncommitted version change. The maintainer reviews both, then separately runs make release to commit, tag, push, and publish. Make reads the prepared version and prepends the overview to GitHub's autogenerated PR list.

Verify the checkout first

Before preparing a release, verify that the checked-out branch is main and HEAD exactly matches freshly fetched origin/main. If not, or if the remote cannot be verified, report the reason and stop without changing version.json or latest-release-notes.md. Existing uncommitted version bumps are allowed.

Choose and confirm the version

Honor an explicit version in the prompt. Otherwise, inspect version.json, published releases, the requested stable or prerelease intent, and relevant changes to infer a candidate. Explain the proposal briefly and ask an explicit question through ask_user to confirm that exact version before changing either artifact. Do not treat a stated assumption or approval of a general plan as version confirmation.

If version.json already has an uncommitted version bump, consider that value as the existing preparation candidate rather than incrementing it again on every invocation. When the prompt does not specify a version, confirm this candidate too. Resolve conflicts with the requested version without discarding maintainer edits.

Use the explicit or confirmed target consistently for the release range, overview, and version change. A hyphen-delimited suffix before any + build metadata makes a version a prerelease; a hyphen in build metadata alone does not.

Choose the release range

1. Record the current commit with git rev-parse HEAD as the draft endpoint. Base claims on that commit, not uncommitted work. Identify the GitHub repository from its remote rather than assuming the working directory's name.
2. List published GitHub releases, including their tags, prerelease flags, publication dates, and bodies. Use gh api with pagination so older stable releases are not missed. Reuse metadata already gathered during version selection. Exclude drafts. Retrieve missing remote tags if needed to check ancestry.
3. Choose the most recent applicable published release preceding the intended version whose tag is an ancestor of the endpoint. Do not select the target release itself or a release from an unrelated maintenance branch. If the release lineage is ambiguous, ask instead of guessing.

• For a prerelease, include both stable and prerelease candidates.
• For a stable release, exclude a candidate if its GitHub prerelease flag is true or its tag's version has a prerelease suffix. Strip the conventional leading v before interpreting a tag. A hyphen in build metadata alone does not make a version a prerelease.

1. For a stable draft, also collect the bodies of intervening published prereleases in the selected range. Include prereleases identified by their version suffix even when GitHub labels them as stable.

For example, with v1.4.1 followed by v2.0.0-rc.1, a 2.0.0-rc.2 draft starts at the RC, whereas a 2.0.0 draft starts at v1.4.1. This remains true if v2.0.0-rc.1 has prerelease: false.

If there is no applicable prior release, treat this as a first release and examine the history up to the endpoint, including any prerelease material for a first stable release. Distinguish that case from unavailable metadata: report authentication, missing-history, or API failures rather than silently choosing a different baseline.

Gather the user-visible changes

Read the commit range and diff from the baseline tag to the endpoint. Follow relevant PRs, source, tests, and documentation to understand the changes rather than summarizing commit titles alone.

Prioritize new capabilities, meaningful fixes, compatibility changes, and measured performance improvements. Omit routine dependency bumps, CI maintenance, and implementation-only refactoring unless they have a concrete consequence for consumers.

For stable releases, use prerelease notes as supporting material, not text to concatenate verbatim. Consolidate related changes, remove duplicate highlights, and check the final API and behavior at the endpoint. Do not describe experimental behavior that was removed or superseded during the prerelease cycle.

Write a short overview

Start the file with exactly:

# What's new

Use a few feature-oriented ## headings. For each major change, explain the capability or behavior in one or two short paragraphs and include a small C# example when it helps the reader use the feature. Ground identifiers and samples in source, tests, or existing documentation; check framework and language requirements and state relevant limitations.

Link to the relevant PR or fuller documentation instead of reproducing exhaustive reference material. This is a release overview, not a complete tutorial, API catalog, or list of every change. GitHub supplies the PR list, contributor sections, and full changelog when the maintainer publishes, so do not duplicate them in this file.

Follow applicable public-writing guidance. Use precise API names, restrained prose, and supported claims. Do not infer performance figures or compatibility guarantees. If there are no user-visible changes, say so briefly rather than inventing a feature.

Prepare the review artifacts

Before updating either artifact, recheck that main and freshly fetched origin/main still match the recorded draft endpoint. If not, stop and rerun preparation rather than saving a stale draft.

Read any existing repository-root latest-release-notes.md before editing. Preserve maintainer edits when updating it; ask before replacing content that cannot be reconciled. Resolve material uncertainty before saving a publication-ready draft, keeping unresolved questions out of the public notes.

Set the chosen version using dotnet nbgv set-version <version> --project <repository-root>. This updates and stages root version.json without committing it. Preserve its other versioning settings. Do not use nbgv prepare-release, which creates branches and commits. If the local tool is unavailable, restore the repository's tools before retrying.

Write the overview to root latest-release-notes.md. Check the header, Markdown fences, links, absence of trailing whitespace, and code samples. Verify samples against existing tests or compile a small isolated example when necessary. Do not modify other tracked files or stage the ignored overview.

Read back version.json and check that its version matches the explicit or confirmed target used for the draft. Inspect staged and unstaged Git diffs to verify the version change remains uncommitted and no unrelated files were modified by preparation. If either artifact failed to update, report the incomplete preparation rather than claiming both are ready.

Report the target version, baseline tag (or first-release status), and endpoint commit to the maintainer outside the notes. Stop for human review of both files. After review, the maintainer manually runs make release; it reads .version from version.json using jq and allows staged or unstaged changes limited to that file. Unrelated tracked or untracked changes must be resolved first. The overview is ignored by Git and remains after publishing; it must be removed or refreshed before another release.

make release VERSION=... remains available to set an explicit version during publication. That override can require regenerating the overview; Make does not check whether the notes match the version.

Do not run make release, create a GitHub release or release tag, commit, push, or change other package versions. The optional overview does not change the range of GitHub's autogenerated PR list.