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

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