From 47bfc7db32d1223fca555765c624df33d73ccb46 Mon Sep 17 00:00:00 2001 From: Kyle-Neale Date: Tue, 30 Jun 2026 16:08:54 -0400 Subject: [PATCH 1/2] Tell Codex review bot not to flag missing changelog entries The Codex code-review bot derives its rules from AGENTS.md and was raising a finding asking for a changelog entry on essentially every non-draft PR. Changelog files are named `/changelog.d/.`, so they can only be created after the PR number is assigned -- their absence at review time is expected, not a defect, and the requirement is already enforced by the check_changelog job in pr-quick-check.yml. Add a Review Guidelines section instructing the reviewer to skip this finding, without relaxing the changelog requirement for authored code. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ed2bcbc2b45fb..d523ad7a10bc6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -165,6 +165,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 `/changelog.d/.`, 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. From 013e450706070602ac267d1fe19a0ac53934dbca Mon Sep 17 00:00:00 2001 From: Kyle-Neale Date: Wed, 1 Jul 2026 17:30:53 -0400 Subject: [PATCH 2/2] 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) --- AGENTS.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d523ad7a10bc6..354ec99ff4bf6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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