create-release-note

Create a release note file using the reno format. Release notes are mandatory for all PRs unless labeled changelog/no-changelog.

Instructions

Step 1: Gather information from the user

Use AskUserQuestion to collect the following. If $ARGUMENTS provides the topic, skip that question.

1. Topic: A short kebab-case identifier for the change (e.g. fix-ntp-timeout, add-gpu-metrics). Used in the filename.

2. Section: Which section does this change belong to?

   • features — New functionality (e.g. "Add support for GPU metrics collection")
   • enhancements — Small improvements to existing features (e.g. "Improve log rotation performance")
   • fixes — Bug fixes (e.g. "Fix memory leak in forwarder")
   • deprecations — Deprecation notices (e.g. "Deprecate log_enabled in favor of logs_enabled")
   • upgrade — Breaking changes requiring user action (must include steps for users to identify if affected)
   • security — Security fixes or improvements
   • issues — Known issues or limitations
   • other — Miscellaneous (rarely used)

3. Content: A user-facing description of the change. This is read by customers, not developers. Ask the user to describe what changed and why.

4. Target: Which release notes directory?

   • releasenotes/notes/ — Main agent (default, most common)
   • releasenotes-dca/notes/ — Cluster Agent (DCA)

5. APM-related?: If the change affects cmd/trace-agent or pkg/trace, the content must be prefixed with APM : and the topic should be prefixed with apm-.

Step 2: Create the release note file

Generate the file using reno:

reno new <topic> --no-edit

Or for non-default directories:

reno --rel-notes-dir <directory> new <topic> --no-edit

This creates a file at <directory>/notes/<topic>-<hash>.yaml with a template.

Always create the file with reno. The <hash> suffix is reno's unique note ID — it must be a real, unique 16-character hex string that reno generates for you. Never hand-write a placeholder like a1b2c3d4e5f6a7b8 or any sequential/guessed value: reno treats the suffix as the note's UID and fails release-note-check with a "UID collision" when two notes share one (this placeholder has broken main more than once).

If reno is not installed, install it rather than creating the file by hand: pip install reno (see the contributing guide). Only if you genuinely cannot install it, generate a real random suffix with openssl rand -hex 8 and name the file <topic>-<hash>.yaml — never a placeholder.

Then replace the template content with only the relevant section. Remove all unused sections (don't leave them commented out — reno template comments are noisy).

Final file format:

---
<section>:
  - |
    Description of the change written for end users.
    Can span multiple lines.

Step 3: Content formatting rules

Release note content must follow these rules:

1. ReStructuredText (RST) format, NOT Markdown:

   • Links: `link text <https://example.com>`_ (NOT [text](url))
   • Bold: **text**
   • Inline code: ``code`` (double backticks, NOT single)
   • Code blocks: use .. code-block:: <lang> directive

2. User-facing language: Write for Datadog customers, not developers. Describe the impact, not the implementation.

3. Self-contained: Each note must be readable independently. Don't reference other release notes.

4. For APM changes: Prefix with APM : (e.g. APM : Fix trace sampling rate calculation).

5. Multiple items: Use separate list items in the same section:

   fixes:
     - |
       Fix memory leak when collecting Docker container metrics.
     - |
       Fix panic in log agent when file is rotated during read.
   

Step 4: Verify

Run the release note linter to validate:

dda inv linter.releasenote

This checks:

• Valid YAML structure
• Only known sections are used
• No empty items
• Valid RST formatting (no Markdown patterns)
• No Markdown links [text](url), headers #, or single-backtick code

If linting fails, fix the issues and re-run.

Section Guidelines

Section	When to use	Example
features	Wholly new capabilities	"Add Windows support for the Process Agent"
enhancements	Improvements too small to be features	"Add PDH data to Windows flare"
fixes	Bug fixes	"Fix EC2 tags collection with multiple marketplaces"
deprecations	Deprecation notices	"The log_enabled config option is deprecated, use logs_enabled"
upgrade	Breaking changes needing user action	"The --config flag format has changed. Users must update..."
security	Security fixes	"Enforce bearer token authentication for API endpoints"
issues	Known issues	"Kubernetes 1.3 is not fully supported in this release"
other	Misc (rarely used)	"Update internal CI tooling"

When to skip (use changelog/no-changelog label)

• Documentation-only changes
• Test-only changes
• CI/CD configuration changes
• Code comment changes
• Developer tooling changes that don't affect the agent binary

Usage

• /create-release-note — Interactive: prompts for all details
• /create-release-note fix-ntp-timeout — Pre-fills the topic