Release Notes

StarRocks Release Notes

Generate the English release-notes section for a tagged StarRocks patch release, open a [Doc] PR for it, and hand off Chinese/Japanese translation to the existing /translate workflow. English only — never edit docs/zh/** or docs/ja/**.

Read references/format.md (exact output format) and references/categorization.md (how to map and rewrite PRs) before drafting. The PR is the human review gate, so favor a complete, accurate draft with uncertain items flagged over silent guessing.

Inputs

• $ARGUMENTS = the new patch version, e.g. 3.5.19. If absent, ask for it.
• Derive once and reuse (examples shown for 3.5.19):
  • minor = <MAJOR>.<MINOR> (e.g. 3.5), branch = branch-<minor> (e.g. branch-3.5)
  • file = docs/en/release_notes/release-<minor>.md (e.g. docs/en/release_notes/release-3.5.md)
  • prev tag = the previous patch (e.g. 3.5.18) — the newest ## X.Y.Z already in file; read it to confirm rather than assuming.

Use the derived file path everywhere below — do not hardcode release-3.5.md.

Workflow

1. Collect the changes

Run the collector and capture its JSON:

bash .claude/skills/release-notes/scripts/collect-prs.sh <prev_tag> <new_tag>
# e.g. collect-prs.sh 3.5.18 3.5.19

It returns { release_date_raw, pr_count, prs: [{number,title,url,base,resolved_to_main,labels,body_excerpt}], unresolved_count, unresolved: [...] } for every PR backported between the two tags. If pr_count is 0, stop and report — the tags likely don't exist yet or the order is wrong (gh api repos/StarRocks/starrocks/tags).

Each PR's number is already resolved to the original main PR (release notes always cite the main PR). release_date_raw is only a suggestion (the tag/commit date) — see step 4 for the actual release date.

unresolved lists any PR whose backport chain did not trace back to main (resolved_to_main: false, e.g. a fix authored directly against a release branch). These need a PR-quality warning — see step 7.

2. Mirror the existing format

Read the top of the target file — the frontmatter, the :::warning block, and the current newest ## X.Y.Z section. Match its heading casing, the The following issues have been fixed: line, and the PR-link style. Do not change frontmatter.

3. Categorize and rewrite

Apply references/categorization.md:

• Map each PR to Behavior Changes / Improvements / Bug fixes; exclude [Doc]/[UT]/[Tool] and behavior-neutral [Refactor].
• Rewrite each title into a user-facing sentence (strip prefixes/scope, backtick identifiers), grouping closely related PRs with space-separated links.
• Build a "Needs reviewer confirmation" list for uncertain section choices, terse titles, or possible upgrade/downgrade-warning items. This list goes in the PR body, not the release notes.
• Release date — always ask the user. The official release date is set by QA and product management and is not necessarily the tag/commit date. Prompt the user: "What is the official release date for <new_tag>?", offering the detected release_date_raw (formatted Month D, YYYY) only as a suggested default. Use the user's answer for the Release date: line. Do not proceed to write the section until the date is confirmed.

4. Write the section

Insert the new ## X.Y.Z section into file per references/format.md: directly below the closing ::: of the :::warning block and above the current newest patch section. Omit empty subsections. English file only.

5. Lint (required so the translation comment appears)

The Translation Status Check workflow only posts the language checkboxes after markdownlint passes, so the diff must be clean. Lint the derived file, and note the Vale config lives at docs/.vale.ini and resolves its styles relative to docs/ — run Vale from the docs/ directory:

# from the docs/ directory, using the version-derived file (e.g. release-3.5.md)
cd docs && vale --config=.vale.ini en/release_notes/release-<minor>.md

Also run the repo's markdownlint (docs/.markdownlint.json) if available. Fix any issues. Re-confirm frontmatter/description is unchanged.

6. Open the PR

git checkout -b release-notes-<new_tag>           # e.g. release-notes-3.5.19
git add docs/en/release_notes/release-<minor>.md  # the derived file, e.g. release-3.5.md
git commit -s -m "[Doc] Add release notes for StarRocks v<new_tag>"
git push -u origin release-notes-<new_tag>
gh pr create --title "[Doc] Add release notes for StarRocks v<new_tag>" --body-file <body>

Fill .github/PULL_REQUEST_TEMPLATE.md for the body:

• What type of PR: check - [x] Doc.
• Change in behavior: check - [x] No (the notes themselves don't change product behavior).
• Checklist: this PR is the user documentation; leave test-case boxes unchecked.
• Bugfix cherry-pick branch check: this is a docs PR, not a code backport — leave the version boxes (4.1/4.0/3.5) unchecked unless the user says otherwise.
• Append the "Needs reviewer confirmation" list under "What I'm doing" so reviewers verify the flagged entries.

7. Flag PR-quality issues (when unresolved_count > 0)

If the collector reported any unresolved PRs (backport chain that never reached main), post a single warning comment on the release-note PR so reviewers can act on it. Do not silently drop it — these often indicate a fix that skipped main and may be missing from main/future releases (a regression risk), not just a citation quirk.

gh pr comment <pr-number> --repo StarRocks/starrocks --body-file <warning>

For each unresolved PR, state in the comment: the number cited in the notes and its base branch (not main), that no main PR was found, and the two impacts — (1) the citation is inconsistent with the other entries, and (2) verify the fix exists on main; forward-port if missing. Ask the author to confirm the correct PR number to cite. (Skip this step entirely when unresolved_count is 0.)

8. Hand off translation

Stop and tell the user:

• Only the derived English file (e.g. docs/en/release_notes/release-3.5.md) changed.
• Once CI DOC Checker → markdownlint passes on the PR, the "🌎 Translation Required?" comment will auto-post with zh and ja checkboxes.
• A docs-maintainer checks the desired boxes and replies /translate; the Translation Runner workflow (StarRocks/doc-translator v1.0.1) then commits the Chinese and Japanese versions into the same PR.

Notes and limits

• Whole-file translation: /translate re-translates the entire file, not just the new section. This is the existing established behavior — rely on it; do not change the pipeline or pre-edit zh/ja.
• Behavior changes are detected heuristically; the "Needs reviewer confirmation" list plus PR review is the safety net (docs/CLAUDE.md: never assert unverified technical facts).
• Portability: the only release-specific values are version, branch, file path, and repo. The same skill structure serves other StarRocks lines (e.g. a commercial product) by swapping those constants — author original content, do not copy notes across products.
• Commits must use git commit -s (DCO sign-off).