Skip to content

Commit 013e450

Browse files
Kyle-Nealeclaude
andcommitted
Reserve .changed changelog type for breaking changes only
Tighten the changelog guidance in AGENTS.md so agents stop tagging non-breaking work as `.changed`. Rewords the `changed` definition to backward-incompatible changes only, and adds a "Choosing .changed" guardrail that instructs pausing to confirm the change is genuinely breaking before using it. Raised by Eric Weaver in #agent-integrations Slack. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 47bfc7d commit 013e450

1 file changed

Lines changed: 5 additions & 1 deletion

File tree

AGENTS.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,12 +149,16 @@ Changelog entries are required for any change to a file that is shipped with the
149149
The valid types are defined in `ddev/src/ddev/release/constants.py` (`ENTRY_TYPES`):
150150

151151
- `added` - New features. Bumps the **minor** version (e.g., 1.0.0 → 1.1.0).
152-
- `changed` - Breaking changes or significant modifications. Bumps the **major** version (e.g., 1.0.0 → 2.0.0).
152+
- `changed` - Backward-incompatible changes only (e.g. removing or renaming a metric or service check, removing/renaming/retyping a config option, or changing default behavior in a way that alters emitted data). Bumps the **major** version (e.g., 1.0.0 → 2.0.0). Do **not** use for non-breaking improvements — those are `added` or `fixed`.
153153
- `deprecated` - Marks functionality as deprecated. Bumps the **minor** version.
154154
- `removed` - Removes functionality. Bumps the **major** version.
155155
- `fixed` - Bug fixes. Bumps the **patch** version (e.g., 1.0.0 → 1.0.1).
156156
- `security` - Security-related fixes. Bumps the **minor** version.
157157

158+
### Choosing `.changed`
159+
160+
Before writing a `.changed` entry, stop and confirm the change is genuinely breaking for an existing user — something that would break their current configuration, dashboards, monitors, or ingested data. If you cannot name specifically what breaks, it is **not** a `.changed` entry: use `added` for new capability or `fixed` for a bug fix. When in doubt, prefer the non-breaking type or ask the reviewer rather than defaulting to `.changed`.
161+
158162
### Examples
159163

160164
```shell

0 commit comments

Comments
 (0)