release-runbook

elasticsearch-net Release Runbook

How to draft a GitHub release for elastic/elasticsearch-net. Always work from the GitHub auto-generated baseline and enhance it — don't write release notes from scratch.

Conventions (must follow)

1. targetCommitish = the major.minor branch. 9.3.x → 9.3, 9.4.x → 9.4, 8.19.x → 8.19. NEVER main. Most important rule.
2. Backports reference the original main PR only. When the GH baseline lists a [X.Y] backport, replace it with the original main PR (drop the [X.Y] prefix). The backport PR is not linked at all — not the URL, not the number, not the bot author. Rationale: attribute the work to where it was originally done; the backport is an internal mechanism, not user-facing.
3. Issue references. Fixes <full-issue-url> for main bullets, (#issue) shorthand for sub-bullets.
4. Regenerate PR uses the [X.Y] branch-prefixed PR, never the main one. Summarize with up to 5 grounded sub-bullets.
5. Multiple regenerate PRs in one release. Combine into one line item; link both PRs.
6. Always create the release as a draft. Use gh release create ... --draft. Never publish — the user reviews and publishes manually. Default to --draft even when the user's request doesn't explicitly say "draft" — a request to "create release X.Y.Z" is not authorization to publish. Rationale: publishing has user-visible consequences (notifications, package release pipelines, public visibility) the user wants to control manually after reviewing the generated notes.
7. Every non-regen PR gets up to 2 sub-bullets describing what changed/fixed/improved. Skip when the title is already fully self-describing.
8. Best-effort upstream correlation for the regen PR — try to match diffs to PRs in elastic/elasticsearch-specification (spec changes) and elastic/client-generator-net (generator changes). Optional grounding; don't fabricate matches.

Quick reference: version → target branch

Read the version from the user's request, pick the branch deterministically. If the version line is unfamiliar, ask before guessing.

Workflow

Six phases: gather → baseline → enhance non-regen → analyze regen → review → draft.

1. Gather PRs and closed issues since the previous tag

Find the previous tag on the same major.minor:

gh release list -R elastic/elasticsearch-net --limit 10

PRs merged into the branch since the previous tag's date:

gh pr list -R elastic/elasticsearch-net --state merged --base <branch> \
  --search "merged:>=<prev-tag-date>" \
  --json number,title,author,baseRefName,body,url,closingIssuesReferences

Recently closed issues — used in step 4 to ground regen sub-bullets:

gh issue list -R elastic/elasticsearch-net --state closed \
  --search "closed:>=<prev-tag-date>" \
  --json number,title,closedAt,url --limit 50

2. Generate the GH baseline

gh api repos/elastic/elasticsearch-net/releases/generate-notes \
  -F tag_name=X.Y.Z -F target_commitish=X.Y -F previous_tag_name=X.Y.W \
  -q .body

This produces the canonical skeleton: ## What's Changed, then bullets, optional ## New Contributors, then **Full Changelog**: .../compare/X.Y.W...X.Y.Z. Use it as-is — do not add ### Bug Fixes / ### Features category headers (no prior release uses them).

3. Enhance each non-regenerate line

For every non-regen PR in the baseline:

Detect backports. Signals: title starts with [X.Y], body mentions "backport"/"cherry-pick"/an original PR. Find the original:

gh pr view <num> -R elastic/elasticsearch-net --json body,commits
gh pr list -R elastic/elasticsearch-net --state merged --base main \
  --search "<title-keywords-without-[X.Y]-prefix>"

If a backport, replace the line with the original main PR's title (no [X.Y] prefix), author, and URL. The backport PR is not mentioned.

Link related issues. From gh pr view <num> --json closingIssuesReferences,body, render as Fixes https://github.com/elastic/elasticsearch-net/issues/<n> inline.

Add ≤2 sub-bullets describing what changed/fixed/improved. Sources in priority order:

1. PR body — if it explains the problem/fix in plain language, distill it.
2. Closing issue title/body — the user-visible symptom or expected behavior.
3. The diff — for small targeted PRs, the changed code paths often imply the bullet (e.g. "now supports X in Y", "no longer throws Z when W").

Skip sub-bullets entirely when the title is already fully self-describing — simple version bumps, trivial renames, dependency updates. Don't pad.

Format:

* <PR title> by @<author> in <PR url>
  * <bullet 1>
  * <bullet 2>

4. Analyze the [X.Y] Regenerate client PR(s)

This is the heart of the runbook. The PR body is always "As titled.", so all signal comes from the diff.

Pick the branch-prefixed PR, e.g. [9.3] Regenerate client. NEVER the main Regenerate client PR.

gh pr view <num> -R elastic/elasticsearch-net --json files,additions,deletions
gh pr diff <num> -R elastic/elasticsearch-net

Categorize changes by file-path signal:

Cross-reference with the closed-issue list from step 1. Match symptoms to categorized changes (e.g. issue "FieldType missing Wildcard" → enum addition; issue "SearchMvtAsync TransportException" → content-type fix). When matched, use the issue title for the bullet text and link (#issue).

Correlate to upstream repos (best effort). Two upstream sources can drive client diffs:

Spec changes (new endpoints, types, enums, fields) → query elastic/elasticsearch-specification:

gh pr list -R elastic/elasticsearch-specification --state merged \
  --search "merged:>=<prev-tag-date>" --json number,title,url,body --limit 50

Match by path/area (client _Generated/Api/Reindex/Cancel*.g.cs ↔ spec PR touching specification/_global/reindex/CancelReindex*) or by keyword (spec PR title "Add Wildcard to FieldType" ↔ client adds Wildcard enum value).

Generator changes (uniform code-shape changes across many files) → query elastic/client-generator-net:

gh pr list -R elastic/client-generator-net --state merged \
  --search "merged:>=<prev-tag-date>" --json number,title,url,body --limit 50

When a match is found, use the upstream PR's title/body to write a more accurate bullet — the spec/generator PR usually states the user-facing intent more clearly than the client diff. Linking the upstream PR in the release notes is optional (prior releases haven't); default to enriched bullet text rather than added URLs unless the upstream PR is materially significant (major area, breaking change).

If correlation isn't obvious within a few minutes, fall back to client-side analysis. Don't fabricate matches.

Pick the top ≤5 bullets, prioritized:

1. Bullets grounded in BOTH a closed issue AND an upstream PR (highest signal)
2. Issue-grounded fixes
3. New endpoints (spec-grounded if possible)
4. Removed/consolidated response types (call out as breaking when applicable)
5. New query/aggregation/enum types
6. Generator improvements with user-visible effects
7. Dependency bumps (only if user-visible behavior changes)

Cap at 5 even if more candidates qualify.

Format:

* Regenerate client by @<author> in https://github.com/elastic/elasticsearch-net/pull/<num>
  * Fixes <symptom> (#<issue>)
  * <other category bullet>

5. Combining multiple regenerate PRs

If two or more [X.Y] Regenerate client PRs fall in the release window, diff each, categorize each, combine + dedupe, then pick top ≤5 across the union. Link both PRs on one line:

* Regenerate client by @<author> in <PR1-url> and <PR2-url>
  * <combined-bullet-1>
  * ...

6. Keep ## New Contributors verbatim

GitHub auto-generates this section from the contributor graph. Don't invent it, don't remove it. If GH omitted it, there are no new contributors this release — that's correct.

7. Pre-draft checklist

• targetCommitish = major.minor branch (NOT main)
• Tag matches the version, no v prefix (e.g. 9.3.6, not v9.3.6)
• Every backport line references the ORIGINAL main PR only (the [X.Y] backport PR is NOT linked)
• Every PR with a related issue references it (Fixes <url> or (#X))
• Every non-regen PR has ≤2 sub-bullets (or none if title is fully self-describing)
• Regenerate line has ≤5 grounded sub-bullets
• Regen bullets attempted upstream correlation (spec and/or generator) where signals suggest it
• Multiple regen PRs combined into one line, both linked
• ## New Contributors kept exactly as GH generated it (or omitted if absent)
• **Full Changelog**: .../compare/<prev>...<current> line present
• No category headers added
• gh release create invocation includes --draft

8. Create the draft

ALWAYS use --draft. Never publish a release. Hand the resulting draft URL to the user; the user reviews and publishes manually.

gh release create X.Y.Z \
  --target X.Y \
  --title X.Y.Z \
  --draft \
  --notes-file release-notes.md

Never include AI/Claude attribution anywhere in release notes.

Common mistakes

Canonical example — 9.3.5 (verbatim)

Use this as the structural target. Note that prior releases (including 9.3.5) do not yet have the new ≤2-bullet sub-bullets on non-regen PRs — that rule applies on top of this structure going forward.

## What's Changed

* Hand-craft IndexSettingsTimeSeriesConverter to handle out-of-range dates by @flobernd in https://github.com/elastic/elasticsearch-net/pull/8873
* Fix DefaultMappingFor not consuming `IdPropertyName` and `DisableIdInference` by @flobernd in https://github.com/elastic/elasticsearch-net/pull/8877
* Regenerate client by @flobernd in https://github.com/elastic/elasticsearch-net/pull/8883
  * Fixes `FieldType` enum doesnt have `Wildcard` value" (#8826)
  * Fixes `SearchMvtAsync` throws `TransportException` on successful `HTTP 200 _mvt` responses with valid binary tile payload (#8867)
* Align LINQ-to-ES|QL integration with `Elastic.Esql` 0.11.0 by @flobernd in https://github.com/elastic/elasticsearch-net/pull/8886

**Full Changelog**: https://github.com/elastic/elasticsearch-net/compare/9.3.4...9.3.5