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

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