From 95b730789278887f7d524c58ff4fd5cface75fb7 Mon Sep 17 00:00:00 2001
From: Jarek Potiuk <jarek@potiuk.com>
Date: Tue, 21 Apr 2026 17:19:40 +0200
Subject: [PATCH] AGENTS: require tracking issue for PRs that apply a
 workaround
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PRs that cap a dependency, disable a feature behind a flag, or
otherwise defer the real fix were sometimes landing with body text
like "will open a tracking issue" and nothing concrete linking to the
follow-up work — making it easy for the deferred work to be forgotten.

Require the tracking issue to be opened first and linked in the PR
body by number, so the workaround and its removal path are visible to
every reviewer.
---
 AGENTS.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 95fdcb1987fd0..c1a5007bffaa1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -224,6 +224,55 @@ Remind the user to:
 2. Add a brief description of the changes at the top of the body.
 3. Reference related issues when applicable (`closes: #ISSUE` or `related: #ISSUE`).
 
+### Tracking issues for deferred work
+
+When a PR applies a **workaround, version cap, mitigation, or partial fix**
+rather than solving the underlying problem (for example: upper-binding a
+dependency to avoid a breaking upstream release, disabling a feature
+behind a flag, reverting a change that needs a better replacement, or
+papering over a bug so a release can ship), the deferred work must be
+captured in a GitHub tracking issue **and** the tracking issue URL must
+appear as a comment at the workaround site in the code.
+
+1. **Open the tracking issue first**, before finalising the PR body.
+2. **Reference it in the PR body by number** — e.g. "full migration is
+   tracked in #65609" — so anyone reviewing the PR can see what was
+   deferred and why.
+3. **Add a link to the tracking issue as a comment at the workaround
+   itself**, so the reference survives after the PR merges and anyone
+   reading the source later can click straight through to the follow-up
+   work. Use the **full issue URL**, not bare `#NNNNN` — bare references
+   do not auto-link outside GitHub's web UI (e.g. when grepping in an
+   editor, browsing a checkout, or reading the file in a terminal).
+   For example:
+
+   ```toml
+   # pyproject.toml
+   # Remove the <1.0 cap after migrating to httpx 1.x;
+   # tracked at https://github.com/apache/airflow/issues/65609
+   "httpx>=0.27.0,<1.0",
+   ```
+
+   ```python
+   # some_module.py
+   # Delete this fallback once the new client is on all workers;
+   # tracked at https://github.com/apache/airflow/issues/65609
+   if old_client:
+       ...
+   ```
+
+4. **Do not** write vague forward-looking phrases like "will open a
+   tracking issue" or "to be filed later" in the PR body or in code
+   comments. Open the issue, link it in both places, then submit the PR.
+5. The tracking issue should describe: what the workaround is, why it
+   was chosen, the concrete follow-up work needed, and any acceptance
+   criteria for removing the workaround.
+
+If a PR you already opened has such forward-looking language, open the
+tracking issue, add a PR comment referencing the issue URL, and push a
+follow-up commit that adds the tracking-issue URL as a comment at the
+workaround site in the code.
+
 ## Boundaries
 
 - **Ask first**