release

# datadog-go release Prepare a new release of `github.com/DataDog/datadog-go`: 1. **Update `CHANGELOG.md`** with all changes since the last release. 2. **Update `statsd/telemetry.go`** so the client reports the new version in telemetry. 3. **Tag the release on GitHub.** Do the work on a branch and open a "Prepare X.Y.Z release" PR — do **not** push to `master` or create the git tag yourself. ## Step 0 — Gather the changes Find the last released version and collect every PR merged since its tag: ```sh # Latest released tag (e.g. v5.9.0) — capture it so both ranges below use the # SAME tag. Hardcoding a stale version here re-gathers already-released PRs. LAST_TAG=$(git describe --tags --abbrev=0) echo "$LAST_TAG" # Merged PRs since that tag — titles + PR numbers git log "$LAST_TAG"..master --oneline --merges # or, if merges are squashed: git log "$LAST_TAG"..master --oneline ``` For each PR, decide the next version per semver: - **PATCH** (`5.9.0` → `5.9.1`) — only bugfixes / internal improvements, no new API. - **MINOR** (`5.9.0` → `5.10.0`) — new user-facing features or options, backward compatible. - **MAJOR** (`5.9.0` → `6.0.0`) — breaking changes (API, behavior, import path, defaults). A new major changes the import path (`.../datadog-go/v6/statsd`); flag this loudly. Use `gh pr view <num>` to confirm the PR title, author, and whether the author is an external contributor (credit them — see guideline 9). ## Step 1 — Update CHANGELOG.md `CHANGELOG.md` lives at the repo root. Add a new release heading at the **top** of the release list (right under the `[//]: #` reminder comment), keeping reverse chronological order. The link-definition block at the very bottom is generated by **PimpMyChangelog** — preserve its structure and add new `[#nnn]` / `[@user]` definitions there. Note the reminder comment already in the file: > `[//]: # (comment: Don't forget to update statsd/telemetry.go:clientVersionTelemetryTag when releasing a new version)` ### Changelog guidelines (house style) 1. **Reverse chronological order** — newest version first. Use `xxxx-xx-xx` only for an unreleased placeholder date; otherwise use the real release date. 2. **Heading format:** `# <version> / <YYYY-MM-DD>` (e.g. `# 5.8.3 / 2026-02-02`). No extra blank sub-headings unless the release has structured sections like `## Breaking changes`. 3. **Hyphen bullets** (`-`) for all new entries. Older entries used `*`; do not copy that style for new work. 4. **Start every bullet with a category tag.** Established tags: `[FEATURE]`, `[IMPROVEMENT]`, `[BUGFIX]`, `[DOCUMENTATION]`, `[TESTING]`, `[OTHER]`. For beta work stack tags: `[BETA][FEATURE]` (not the old `[BETA FEATURE]`). 5. **Write user-facing outcomes**, not internal implementation detail. - Good: `- [BUGFIX] Gracefully reconnect when UDS connection is severed. See [#323][].` - Less ideal: `- [BUGFIX] Change reconnect code path.` 6. **Concise, imperative phrasing.** Good verbs: Add, Fix, Support, Improve, Reduce, Prevent, Export, Optimize, Revert, "Gracefully reconnect". 7. **Backticks for code, APIs, env vars, options, methods** — e.g. `` `DD_EXTERNAL_ENV` ``, `` `ClientInterfaceEx` ``, `` `WithMaxSamplesPerContext()` ``. 8. **Always include the PR/issue reference** when available, in this exact form: `See [#123][].` For multiple: `See [#182][] and [#185][].` Never paste raw GitHub URLs into the bullet body — add/reuse a link definition at the bottom instead. 9. **Credit external contributors** with the lowercase form: `See [#123][], thanks [@username][].` Do not use `Thanks to` / `(Thanks ...)`. Datadog-employee PRs are not credited with `thanks`. 10. **Sub-bullets only for migration/operational context** — caveats, precedence rules, support notes. Indent them; prefer `-` for new sub-bullets. 11. **Dedicated sections for major releases.** For breaking changes use: ``` # 6.0.0 / YYYY-MM-DD ## Breaking changes - ... ## Notes - [FEATURE] ... - [BUGFIX] ... ``` Reserve `## Breaking changes` for API/behavior/dependency/import-path/default-setting changes that require users to modify code or config. 12. **Be explicit about reverts** — name the affected version and the reason, e.g. `- [IMPROVEMENT] Revert 5.7.0 as it included a breaking change.` or `- [BUGFIX] Revert 5.9.0 change to aggregation flushing because it introduced a breaking behavior change. See [#123][].` 13. **Add link definitions at the bottom**, inside the PimpMyChangelog block: ``` [#123]: https://github.com/DataDog/datadog-go/pull/123 [@username]: https://github.com/username ``` Use `/pull/<n>` for PRs and `/issues/<n>` for issues (match what `[#n]` actually is). ### Templates Normal release: ``` # X.Y.Z / YYYY-MM-DD - [FEATURE] Add `NewOption()` to configure example behavior. See [#123][], thanks [@contributor][]. - [IMPROVEMENT] Reduce allocations when sending metrics without tags. See [#124][]. - [BUGFIX] Fix reconnect behavior when the UDS connection is severed. See [#125][]. ``` Major release: ``` # X.0.0 / YYYY-MM-DD ## Breaking changes - `OldOption()` has been removed in favor of `NewOption()`. - The default aggregation behavior now includes counts, gauges, and sets. ## Notes - [FEATURE] Add `NewOption()` to configure example behavior. See [#123][]. - [BUGFIX] Fix reconnect behavior when the UDS connection is severed. See [#125][]. ``` ### Style checklist (verify before opening the PR) Each new entry: 1. Uses `# version / YYYY-MM-DD`. 2. Uses `-` bullets. 3. Starts with `[FEATURE]` / `[IMPROVEMENT]` / `[BUGFIX]` or another established tag. 4. Describes the user-visible change. 5. Uses backticks for code names, env vars, options, methods. 6. Includes `See [#123][].` when there is a PR or issue. 7. Credits external contributors with `thanks [@username][].` 8. Has matching link definitions at the bottom. 9. Uses `## Breaking changes` only when users may need to change code/config/imports/expectations. ## Step 2 — Update statsd/telemetry.go Bump the version the client reports in telemetry. In `statsd/telemetry.go`: ```go // clientVersionTelemetryTag is a tag identifying this specific client version. var clientVersionTelemetryTag = "client_version:5.9.0" ``` Change the version string to the new release (e.g. `client_version:5.10.0`). This MUST match the new CHANGELOG heading exactly. Verify nothing else hardcodes the old version: ```sh grep -rn "client_version:\|5\.9\.0" statsd/ --include='*.go' ``` ## Step 3 — Open the prepare-release PR, then tag Commit both files together on a release branch and open the PR (mirrors past releases like "Prepare 5.9.0 release (#392)"): ```sh git switch -c <user>/prepare-X.Y.Z-release git add CHANGELOG.md statsd/telemetry.go git commit -s -m "Prepare X.Y.Z release" gh pr create --title "Prepare X.Y.Z release" \ --body "Prepare X.Y.Z release. Update CHANGELOG.md with all changes since $LAST_TAG." ``` ## Quick reference - CHANGELOG: `CHANGELOG.md` (repo root) — new heading at top, link defs in the PimpMyChangelog block at the bottom. - Version tag: `statsd/telemetry.go` → `clientVersionTelemetryTag` (`client_version:X.Y.Z`). - Module path: `github.com/DataDog/datadog-go/v5` — a new MAJOR bumps the `/vN` suffix. - Git tag format: `vX.Y.Z`. - Don't push to `master` or create tags without explicit user confirmation.