Release

datadog-go release

Prepare a new release of github.com/DataDog/datadog-go:

• Update CHANGELOG.md with all changes since the last release.
• Update statsd/telemetry.go so the client reports the new version in telemetry.
• 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)

• Reverse chronological order — newest version first. Use xxxx-xx-xx only for an

unreleased placeholder date; otherwise use the real release date.

• 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.

• Hyphen bullets (-) for all new entries. Older entries used *; do not copy that

style for new work.

• 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]).

• 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.
• Concise, imperative phrasing. Good verbs: Add, Fix, Support, Improve, Reduce,

Prevent, Export, Optimize, Revert, "Gracefully reconnect".

• Backticks for code, APIs, env vars, options, methods — e.g. DD_EXTERNAL_ENV ,

ClientInterfaceEx , WithMaxSamplesPerContext() .

• 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.

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

• Uses # version / YYYY-MM-DD.
• Uses - bullets.
• Starts with [FEATURE] / [IMPROVEMENT] / [BUGFIX] or another established tag.
• Describes the user-visible change.
• Uses backticks for code names, env vars, options, methods.
• Includes See [#123][]. when there is a PR or issue.
• Credits external contributors with thanks [@username][].
• Has matching link definitions at the bottom.
• 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.