Skip to content

Refine AGENTS.md changelog guidance: silence Codex noise and reserve .changed for breaking changes #24275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Kyle-Neale wants to merge 2 commits into
base: master
Choose a base branch
from
+11 −1
Open

Refine AGENTS.md changelog guidance: silence Codex noise and reserve .changed for breaking changes #24275

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
47bfc7d
Tell Codex review bot not to flag missing changelog entries
Kyle-Neale Jun 30, 2026
013e450
Reserve `.changed` changelog type for breaking changes only
Kyle-Neale Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,12 +149,16 @@ Changelog entries are required for any change to a file that is shipped with the
The valid types are defined in `ddev/src/ddev/release/constants.py` (`ENTRY_TYPES`):

- `added` - New features. Bumps the **minor** version (e.g., 1.0.0 → 1.1.0).
- `changed` - Breaking changes or significant modifications. Bumps the **major** version (e.g., 1.0.0 → 2.0.0).
- `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`.
- `deprecated` - Marks functionality as deprecated. Bumps the **minor** version.
- `removed` - Removes functionality. Bumps the **major** version.
- `fixed` - Bug fixes. Bumps the **patch** version (e.g., 1.0.0 → 1.0.1).
- `security` - Security-related fixes. Bumps the **minor** version.

### Choosing `.changed`

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

### Examples

```shell
Expand All @@ -165,6 +169,12 @@ echo "Bump OpenSSL in confluent-kafka to 3.4.1 on Windows." > kafka_consumer/cha
echo "Fix a bug where ``tempdb`` is wrongly excluded from database files metrics." > sqlserver/changelog.d/23701.fixed
```

## Review Guidelines

These guidelines apply to automated code review (the Codex review bot). They do not relax any requirement above for code you author.

- Do not raise findings for a missing changelog entry. Changelog files are named `<INTEGRATION>/changelog.d/<PR_NUMBER>.<TYPE>`, so they can only be created after the PR number is assigned; their absence when a PR is first opened is expected rather than a defect. The requirement is already enforced by the `check_changelog` job in `.github/workflows/pr-quick-check.yml`.

## Pull Requests

- Open PRs in draft mode unless explicitly asked otherwise; mark them ready for review once the work is complete and CI passes.
Expand Down
Loading