release-runbook

name	release-runbook
description	Use when drafting, creating, or updating a GitHub release for elastic/elasticsearch-net (any 9.x or 8.19.x patch). Covers branch targeting, backport linking, per-PR sub-bullets, and how to summarize regenerate-client PRs with optional upstream correlation to elastic/elasticsearch-specification and elastic/client-generator-net.

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 non-breaking sub-bullets, plus every breaking change (see rule 9).
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.
9. Breaking changes are never capped. Every breaking change gets its own sub-bullet, prefixed **Breaking** (or **Breaking (area)** when there are enough to group by Elasticsearch area), and these do not count against the sub-bullet caps in rules 4 and 7. List them after the non-breaking bullets. When a release carries any breaking change, open the notes with a > [!WARNING] callout telling readers to review the list before upgrading. Rationale: a cap that silently drops a breaking change leaves users to discover it as a compile error after upgrading; 8.19.0 set the > [!WARNING] precedent.

Quick reference: version → target branch

Version line	Target branch
9.4.x	9.4
9.3.x	9.3
8.19.x	8.19

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:

Signal	Category
New *Request.g.cs + *Response.g.cs triplet under _Generated/Api/<area>/	New endpoint (likely spec change)
Deleted *Response.g.cs under _Generated/Api/	Removed/consolidated response (potentially breaking; spec change)
New *.g.cs under _Generated/Types/QueryDsl/ or Aggregations/	New query/aggregation type (spec change)
New small enum/type file under _Generated/Types/ (e.g. *Flag.g.cs)	New enum value or type (spec change)
Added DefaultRequestConfiguration { Accept = ... } block	Content-type fix (spec change — often resolves a deserialization bug)
*.csproj version change (e.g. Elastic.Transport)	Dependency bump
Same code-shape change applied uniformly across many existing files (converter pattern, attribute, init block)	Generator change — likely from elastic/client-generator-net
Small +/- on existing *Request.g.cs (XML doc only)	Skip — not user-facing
In a modified *.g.cs: changed property type, removed/renamed member, or a member gaining/losing required	Breaking change (uncapped, rule 9)
A sealed class becoming interface I* alongside new per-variant types and a *Factory	Breaking change: variant family split
Changed union arm or discriminator string in a modified *.Converters.g.cs	Behavior fix — the old code mis-deserialized that arm

Breaking changes hide in modified files, not added ones. The path signals above only catch new and deleted files, so diff the modified generated sources too:

git diff <prev-tag> origin/<branch> --name-status -- src/Elastic.Clients.Elasticsearch/_Generated
git diff <prev-tag> origin/<branch> -- '**/_Generated/**/*.g.cs'

A regen touching hundreds of files is too large to read directly, and the request-converter metadata and XML doc churn swamp the real signal. Delegate the sweep to a subagent, telling it to ignore .g.xml files, XML doc comments, SpecReferences.xml and request-converter metadata, and to report changed property types, removed members, new required members and renamed members. Verify each reported breaking change against the actual diff hunk before writing it into the notes.

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.

List every breaking change in its own sub-bullet (uncapped, per rule 9). Then pick the top ≤5 non-breaking 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. Behavior fixes where a generated converter or discriminator was previously wrong
5. New query/aggregation/enum types
6. Generator improvements with user-visible effects
7. Dependency bumps (only if user-visible behavior changes)

Cap the non-breaking bullets at 5 even if more candidates qualify. Never drop a breaking change to fit a cap.

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 the top ≤5 non-breaking bullets across the union (breaking changes stay uncapped). 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), not counting breaking changes
• Regenerate line has ≤5 grounded non-breaking sub-bullets
• Every breaking change is listed, prefixed **Breaking**, and none was dropped to fit a cap
• > [!WARNING] callout present when the release carries any breaking change
• 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

Mistake	Why wrong
Targeting main	Releases must cut from 9.3 (or matching minor)
Using the Regenerate client PR from main	Use the [X.Y] branch-prefixed one
Adding ### Bug Fixes category headers	No prior release uses them
Tagging as v9.3.6	Tags have no v prefix
Linking the [X.Y] backport PR (or both)	Reference ONLY the original main PR — the backport is not linked
>5 non-breaking regen bullets / unsubstantiated bullets	Cap non-breaking at 5; ground each in a diff signal, closed issue, or upstream PR
>2 non-breaking sub-bullets on a non-regen PR	Cap is 2
Dropping a breaking change to respect a cap	Breaking changes are uncapped; a missed one becomes a compile error for users
Padding sub-bullets when the title already describes the PR fully	Skip them entirely in that case
Fabricating an upstream PR correlation	Only correlate when the match is clear; otherwise client-diff analysis
Publishing the release directly (omitting --draft)	Always create as draft; the user publishes manually

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