release

name	release
description	Cut a new datadog-go release and update CHANGELOG.md following the repo's house style. Use when asked to "prepare a release", "cut version X.Y.Z", "update the changelog for the release", "bump the version", or "tag a release" for the DataDog/datadog-go repo. Walks the three-step release process (changelog → telemetry version → git tag) and enforces the 13 changelog guidelines.

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:

# 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:

// 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:

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)"):

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.