diff --git a/.agents/skills/airflow-pr-draft-summary/SKILL.md b/.agents/skills/airflow-pr-draft-summary/SKILL.md new file mode 100644 index 00000000000..780f6c82b96 --- /dev/null +++ b/.agents/skills/airflow-pr-draft-summary/SKILL.md @@ -0,0 +1,119 @@ +--- +name: airflow-pr-draft-summary +description: Draft Apache Airflow commit messages, PR titles and descriptions, or GitHub comments and reviews. Also use for release-note decisions when preparing a contribution. +--- + + + +# Draft Airflow contribution text + +Use the sections below for the requested contribution text. For PR descriptions, +follow [the repository template](../../../.github/PULL_REQUEST_TEMPLATE.md), keep +titles under 70 characters, and complete the Gen-AI checkbox and `Generated-by:` +attribution when applicable. Report only checks actually executed and their outcomes. +For release-note decisions, also follow the newsfragment constraints in root +[`AGENTS.md`](../../../AGENTS.md#coding-standards). + +When deciding whether an issue is needed or preparing authorized publication, use +[Publish Airflow changes](../airflow-publish-changes/SKILL.md). Return the requested +text for a drafting request; drafting alone does not authorize posting. + +## Commit messages, PR titles and release notes + +Write commit messages focused on user impact, not implementation details. + +- **Good:** `Fix airflow dags test command failure without serialized Dags` +- **Good:** `UI: Fix Grid view not refreshing after task actions` +- **Good:** `Update foo function` +- **Bad:** `Initialize Dag bundles in CLI get_dag function` +- **Bad:** `Update foo function (#12345)` +- **Bad:** `fix(cli): dags test failure` — Airflow does not use Conventional Commits + (`feat:`, `fix:`, `chore:` …). Write the subject as plain prose. A `commit-msg` + prek hook (`check-no-conventional-commit-message`) rejects these, and CI checks + every commit of the PR. + +**Always run `prek install` before committing any code.** It installs the +`commit-msg` hook (in addition to `pre-commit`) so the Conventional Commits guard +runs locally; a clone that ran `prek install` before this hook existed must re-run +it to pick up the new hook type. + +Use the **imperative mood** and a plain message — do **not** use Conventional Commits prefixes +(`fix:`, `feat:`, `chore:`, `docs:`, `refactor:`, …). apache/airflow does not follow that +convention. (Area tags the project already uses, like `UI:` / `API:` / `Helm:`, are fine; +Conventional-Commit `type:` tokens are not.) The same rule applies to PR titles. + +Do not include an issue or PR number in the PR title. GitHub already appends +the actual PR number automatically when a PR is squash-merged (this is why +Airflow's git history is full of titles like `... (#71609)`). Manually +adding a number in the title duplicates that auto-added number, and readers +cannot tell whether the number in the title refers to an issue or a PR — +which is misleading in the commit history and changelog. Reference the +issue only in the PR description, not the title + +The commit message **body** should describe **why** the change is made — the motivation and +context — and **never what** the change is. The diff already shows what changed; restating it in +prose adds noise. + +For `airflow-core` (and `chart/`, `dev/mypy/`) **user-facing** changes, add a newsfragment in that distribution's `newsfragments/` directory. **Golden rule: only add a newsfragment when you are certain the change is visible to users; when in doubt, do not add one** — a maintainer will request one in review if it is needed. Build/release tooling, CI, packaging, internal refactors, and dev-only scripts are not user-facing and must not get a newsfragment: +`echo "Brief description" > airflow-core/newsfragments/{PR_NUMBER}.{bugfix|feature|improvement|doc|misc|significant}.rst` + +**Do not add newsfragments for `providers/` or `airflow-ctl/`** — their release managers regenerate the changelog from `git log` and do not consume newsfragments. Update the changelog directly when needed: `providers//docs/changelog.rst` (see `providers/AGENTS.md`) or `airflow-ctl/RELEASE_NOTES.rst`. Changes to `task-sdk/` use `airflow-core/newsfragments/` since task-sdk ships in airflow-core. + +- NEVER add Co-Authored-By with yourself as co-author of the commit. Agents cannot be authors, humans can be, Agents are assistants. + +## GitHub messages drafted by agents + +Anything an agent drafts that ends up posted to GitHub on the user's +account — PR / issue comments, PR-level reviews, line-level review +comments, discussion replies — must end with an attribution footer. +The footer is required whether or not a human reviewed the draft +first; what changes between the two cases is the wording. + +Place the footer on its own paragraph at the end of the message, +separated from the body by a blank line and a horizontal rule. Use +the same agent name string used in `Generated-by:` on PR bodies (for +example, `Claude Code (Opus 4.7)`). + +- **Agent draft, posted without prior human review** (autonomous / + routine work, scheduled triage, etc.): + + ``` + --- + Drafted-by: (no human review before posting) + ``` + +- **Agent draft, reviewed and approved by a human maintainer before + posting:** + + ``` + --- + Drafted-by: ; reviewed by @ before posting + ``` + + The `@` is the human who actually read the draft + and said "post it as-is" (or similar). It is not the user the agent + is "running on behalf of" if no review took place — that case is the + first form, not this one. + +This footer is in addition to, not a replacement for, any per-tool +disclosure rules (the PR body still keeps its own `Generated-by:` +block under the AI-disclosure checkbox; commit messages still follow +the no-self-as-co-author rule above). Do not skip the footer to +shorten a message — attribution applies regardless of message length. + +### Do not tag individuals + +AI agents MUST NOT mention or tag individual contributors, committers, +PMC members, or maintainers using GitHub usernames (e.g. `@user`) unless +explicitly instructed by a human reviewer. When suggesting who might be +relevant to a discussion, refer to roles, teams, code ownership +information, labels, or components instead of individuals. This keeps +notification noise down and avoids pulling people into threads they have +not chosen to join. + +The only exceptions are mentions a human has explicitly authorized — +including the `@` in the `Drafted-by: … reviewed by +@` footer above, which names the reviewer who approved the +message — and replying within a thread to people already actively +participating in that same PR/issue discussion. diff --git a/.agents/skills/airflow-publish-changes/SKILL.md b/.agents/skills/airflow-publish-changes/SKILL.md new file mode 100644 index 00000000000..cc4fe94beb7 --- /dev/null +++ b/.agents/skills/airflow-publish-changes/SKILL.md @@ -0,0 +1,234 @@ +--- +name: airflow-publish-changes +description: Prepare or carry out authorized publication of Apache Airflow changes, including remote checks, pre-push verification, PR creation, and tracking deferred work. Also use when planning these steps or managing contribution issues. +--- + + + +# Publish Airflow changes + +For a plan, describe the steps without executing publication. For authorized +publication, preserve existing approval and confirmation boundaries. +Use the sections below for remote setup, existing PR checks, publication and +issue tracking. Follow root [`AGENTS.md`](../../../AGENTS.md) for the applicable +test conventions and generated check commands; for contribution text, use +[Draft Airflow contribution text](../airflow-pr-draft-summary/SKILL.md). + +## Git remote naming conventions + +Airflow standardises on two git remote names, and the rest of this file, the +contributing docs, and the release docs all assume them: + +- **`upstream`** — the canonical `apache/airflow` repository (fetch from here). +- **`origin`** — the contributor's fork of `apache/airflow` (push PR branches here). + +Always push branches to `origin`. Never push directly to `upstream` (and never +push directly to `main` on either remote). + +**Before running any remote-based command, run `git remote -v` and verify the +names match this convention.** If they do not — for example, the upstream remote +is called `apache`, or `origin` points at `apache/airflow` with the fork under a +different name like `fork` — **do not silently go along with the existing +names**. Surface the mismatch to the user and propose the exact rename commands +to bring the checkout in line with the convention, then ask the user to confirm +before running them. Examples: + +- Upstream is named `apache`, fork is `origin` (common legacy layout): + + ```bash + git remote rename apache upstream + ``` + +- `origin` points at `apache/airflow` and the fork is named `fork` (release-manager + / "cloned upstream directly" layout): + + ```bash + git remote rename origin upstream + git remote rename fork origin + ``` + +- Upstream is missing entirely: + + ```bash + git remote add upstream https://github.com/apache/airflow.git + # or, for SSH: + git remote add upstream git@github.com:apache/airflow.git + ``` + +- Fork is missing entirely: + + ```bash + gh repo fork apache/airflow --remote --remote-name origin + ``` + +After any rename/add, re-run `git remote -v` to confirm the new state before +continuing with commands that assume `upstream` / `origin`. + +If a doc, script, or command you're about to run uses the old `apache` name (or +any other variant), **translate it to the `upstream` convention** in what you +propose to the user, rather than perpetuating the old name. Flag the stale +documentation so it can be fixed in a follow-up. + +## Before starting: check for an existing PR + +Before working on an issue, check for open PRs already addressing it +(`gh pr list --search ""`, and look for `closes:` +/ `fixes:` references). Airflow allows parallel work — "better PR wins" +(see `contributing-docs/04_how_to_contribute.rst`) — but it is not the +default: prefer reviewing and building on an existing PR. Open a separate +one only *if your approach is genuinely different*. Do not blindly open +another near-identical PR for an issue that already has one (or several) — +that just adds reviewer noise. + +## Creating Pull Requests + +**Always push to the user's fork (`origin`)**, not to `upstream` (`apache/airflow`). +Never push directly to `main`. + +Before pushing, confirm the remote setup matches the conventions above +(`upstream` → `apache/airflow`, `origin` → your fork). Run `git remote -v` and, +if the names don't match, propose renames as described in "Git remote naming +conventions" — ask the user to confirm before running them. + +If the fork remote does not exist at all, create one: + +```bash +gh repo fork apache/airflow --remote --remote-name origin +``` + +Before pushing, perform a self-review of your changes following the Gen-AI review guidelines +in [`contributing-docs/05_pull_requests.rst`](../../../contributing-docs/05_pull_requests.rst) and the +code review checklist in [`.github/instructions/code-review.instructions.md`](../../../.github/instructions/code-review.instructions.md): + +1. Review the full diff (`git diff main...HEAD`) and verify every change is intentional and + related to the task — remove any unrelated changes. +2. Read `.github/instructions/code-review.instructions.md` and check your diff against every + rule — architecture boundaries, database correctness, code quality, testing requirements, + API correctness, and AI-generated code signals. Fix any violations before pushing. +3. Confirm the code follows the project's coding standards and architecture boundaries + described in root [`AGENTS.md`](../../../AGENTS.md). +4. Run regular (fast) static checks (`prek run --from-ref --stage pre-commit`) + and fix any failures. This includes mypy checks for non-provider projects (airflow-core, task-sdk, airflow-ctl, dev, scripts, devel-common). +5. Run manual (slower) checks + (`prek run --from-ref --stage manual --skip compile-ui-assets-dev --skip view-skill-eval --skip run-skill-eval-codex`) + and fix any failures. The skipped hooks start long-running local servers or provision the + opt-in Codex environment rather than run checks that complete. +6. Run relevant individual tests and confirm they pass. +7. Find which tests to run for the changes with selective-checks and run those tests in parallel to confirm they pass and check for CI-specific issues. +8. Check for security issues — no secrets, no injection vulnerabilities, no unsafe patterns. + +Before pushing, always rebase your branch onto the latest target branch (usually `main`) +to avoid merge conflicts and ensure CI runs against up-to-date code: + +```bash +git fetch upstream +git rebase upstream/ +``` + +If there are conflicts, resolve them and continue the rebase. If the rebase is too complex, +ask the user for guidance. + +Then push the branch to your fork (`origin`) and open the PR creation page in the browser +with the body pre-filled (including the generative AI disclosure already checked): + +```bash +git push -u origin +gh pr create --web --title "Short title (under 70 chars)" --body "$(cat <<'EOF' +Brief description of the changes. + +closes: #ISSUE (if applicable) + +--- + +##### Was generative AI tooling used to co-author this PR? + +- [X] Yes — + +Generated-by: following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions) + +EOF +)" +``` + +The `--web` flag opens the browser so the user can review and submit. The `--body` flag +pre-fills the PR template with the generative AI disclosure already completed. + +Remind the user to: + +1. Review the PR title — keep it short (under 70 chars), in the imperative mood, and focused on user impact. Do not use Conventional Commits prefixes (`fix:`, `feat:`, `chore:`, …). +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`). + +## Golden rule: when a fix is imminent, open the PR, not an issue + +If you already know how to fix the problem and you (or the user) are going to +open the PR shortly, **do not file a GitHub issue first**. Go straight to the +PR. + +- Airflow does not use issues as a changelog, as a parallel bug database, or + as a duplicate record of in-flight work. The PR itself is the canonical + record — title, description, diff, discussion, and merge all live in one + place. An issue that gets closed by a PR a day later is double accounting + that carries no information the PR does not already carry. +- Open issues attract drive-by submissions, often from other agents, that + haven't seen the in-flight work. That produces duplicate fixes, low-quality + PRs that have to be closed, and wasted reviewer time. Not opening the + issue avoids creating that bait in the first place. +- If you catch yourself drafting an issue body that reads like the PR + description you are about to write, that is the signal — skip the issue + and open the PR. + +The one exception is the case covered by the next section: the PR ships a +**workaround, mitigation, or partial fix** and the real follow-up work is +genuinely deferred to a later PR. There, the issue captures work that will +outlive the PR, so the issue is load-bearing rather than duplicate. + +## 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. diff --git a/.claude/skills/airflow-pr-draft-summary b/.claude/skills/airflow-pr-draft-summary new file mode 120000 index 00000000000..f4054ccd600 --- /dev/null +++ b/.claude/skills/airflow-pr-draft-summary @@ -0,0 +1 @@ +../../.agents/skills/airflow-pr-draft-summary \ No newline at end of file diff --git a/.claude/skills/airflow-publish-changes b/.claude/skills/airflow-publish-changes new file mode 120000 index 00000000000..82e7aaf93ac --- /dev/null +++ b/.claude/skills/airflow-publish-changes @@ -0,0 +1 @@ +../../.agents/skills/airflow-publish-changes \ No newline at end of file diff --git a/.gitignore b/.gitignore index 113e360ce5c..35b2f7afa04 100644 --- a/.gitignore +++ b/.gitignore @@ -140,6 +140,8 @@ ENV/ !.claude/skills/ .claude/skills/* !.claude/skills/aip-user-stories +!.claude/skills/airflow-pr-draft-summary +!.claude/skills/airflow-publish-changes !.claude/skills/airflow-translations !.claude/skills/prepare-providers-documentation !.claude/skills/upgrade-fab-provider diff --git a/AGENTS.md b/AGENTS.md index 1b4187e72f5..4b67debf840 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -168,320 +168,22 @@ reported as such are described in "What is NOT considered a security vulnerabili ## Commits and PRs -Write commit messages focused on user impact, not implementation details. - -- **Good:** `Fix airflow dags test command failure without serialized Dags` -- **Good:** `UI: Fix Grid view not refreshing after task actions` -- **Good:** `Update foo function` -- **Bad:** `Initialize Dag bundles in CLI get_dag function` -- **Bad:** `Update foo function (#12345)` -- **Bad:** `fix(cli): dags test failure` — Airflow does not use Conventional Commits - (`feat:`, `fix:`, `chore:` …). Write the subject as plain prose. A `commit-msg` - prek hook (`check-no-conventional-commit-message`) rejects these, and CI checks - every commit of the PR. - -**Always run `prek install` before committing any code.** It installs the -`commit-msg` hook (in addition to `pre-commit`) so the Conventional Commits guard -runs locally; a clone that ran `prek install` before this hook existed must re-run -it to pick up the new hook type. - -Use the **imperative mood** and a plain message — do **not** use Conventional Commits prefixes -(`fix:`, `feat:`, `chore:`, `docs:`, `refactor:`, …). apache/airflow does not follow that -convention. (Area tags the project already uses, like `UI:` / `API:` / `Helm:`, are fine; -Conventional-Commit `type:` tokens are not.) The same rule applies to PR titles. - -Do not include an issue or PR number in the PR title. GitHub already appends -the actual PR number automatically when a PR is squash-merged (this is why -Airflow's git history is full of titles like `... (#71609)`). Manually -adding a number in the title duplicates that auto-added number, and readers -cannot tell whether the number in the title refers to an issue or a PR — -which is misleading in the commit history and changelog. Reference the -issue only in the PR description, not the title - -The commit message **body** should describe **why** the change is made — the motivation and -context — and **never what** the change is. The diff already shows what changed; restating it in -prose adds noise. - -For `airflow-core` (and `chart/`, `dev/mypy/`) **user-facing** changes, add a newsfragment in that distribution's `newsfragments/` directory. **Golden rule: only add a newsfragment when you are certain the change is visible to users; when in doubt, do not add one** — a maintainer will request one in review if it is needed. Build/release tooling, CI, packaging, internal refactors, and dev-only scripts are not user-facing and must not get a newsfragment: -`echo "Brief description" > airflow-core/newsfragments/{PR_NUMBER}.{bugfix|feature|improvement|doc|misc|significant}.rst` - -**Do not add newsfragments for `providers/` or `airflow-ctl/`** — their release managers regenerate the changelog from `git log` and do not consume newsfragments. Update the changelog directly when needed: `providers//docs/changelog.rst` (see `providers/AGENTS.md`) or `airflow-ctl/RELEASE_NOTES.rst`. Changes to `task-sdk/` use `airflow-core/newsfragments/` since task-sdk ships in airflow-core. - -- NEVER add Co-Authored-By with yourself as co-author of the commit. Agents cannot be authors, humans can be, Agents are assistants. - -### Git remote naming conventions - -Airflow standardises on two git remote names, and the rest of this file, the -contributing docs, and the release docs all assume them: - -- **`upstream`** — the canonical `apache/airflow` repository (fetch from here). -- **`origin`** — the contributor's fork of `apache/airflow` (push PR branches here). - -Always push branches to `origin`. Never push directly to `upstream` (and never -push directly to `main` on either remote). - -**Before running any remote-based command, run `git remote -v` and verify the -names match this convention.** If they do not — for example, the upstream remote -is called `apache`, or `origin` points at `apache/airflow` with the fork under a -different name like `fork` — **do not silently go along with the existing -names**. Surface the mismatch to the user and propose the exact rename commands -to bring the checkout in line with the convention, then ask the user to confirm -before running them. Examples: - -- Upstream is named `apache`, fork is `origin` (common legacy layout): - - ```bash - git remote rename apache upstream - ``` - -- `origin` points at `apache/airflow` and the fork is named `fork` (release-manager - / "cloned upstream directly" layout): - - ```bash - git remote rename origin upstream - git remote rename fork origin - ``` - -- Upstream is missing entirely: - - ```bash - git remote add upstream https://github.com/apache/airflow.git - # or, for SSH: - git remote add upstream git@github.com:apache/airflow.git - ``` - -- Fork is missing entirely: - - ```bash - gh repo fork apache/airflow --remote --remote-name origin - ``` - -After any rename/add, re-run `git remote -v` to confirm the new state before -continuing with commands that assume `upstream` / `origin`. - -If a doc, script, or command you're about to run uses the old `apache` name (or -any other variant), **translate it to the `upstream` convention** in what you -propose to the user, rather than perpetuating the old name. Flag the stale -documentation so it can be fixed in a follow-up. - -### Before starting: check for an existing PR - -Before working on an issue, check for open PRs already addressing it -(`gh pr list --search ""`, and look for `closes:` -/ `fixes:` references). Airflow allows parallel work — "better PR wins" -(see `contributing-docs/04_how_to_contribute.rst`) — but it is not the -default: prefer reviewing and building on an existing PR. Open a separate -one only *if your approach is genuinely different*. Do not blindly open -another near-identical PR for an issue that already has one (or several) — -that just adds reviewer noise. - -### Creating Pull Requests - -**Always push to the user's fork (`origin`)**, not to `upstream` (`apache/airflow`). -Never push directly to `main`. - -Before pushing, confirm the remote setup matches the conventions above -(`upstream` → `apache/airflow`, `origin` → your fork). Run `git remote -v` and, -if the names don't match, propose renames as described in "Git remote naming -conventions" — ask the user to confirm before running them. - -If the fork remote does not exist at all, create one: - -```bash -gh repo fork apache/airflow --remote --remote-name origin -``` - -Before pushing, perform a self-review of your changes following the Gen-AI review guidelines -in [`contributing-docs/05_pull_requests.rst`](contributing-docs/05_pull_requests.rst) and the -code review checklist in [`.github/instructions/code-review.instructions.md`](.github/instructions/code-review.instructions.md): - -1. Review the full diff (`git diff main...HEAD`) and verify every change is intentional and - related to the task — remove any unrelated changes. -2. Read `.github/instructions/code-review.instructions.md` and check your diff against every - rule — architecture boundaries, database correctness, code quality, testing requirements, - API correctness, and AI-generated code signals. Fix any violations before pushing. -3. Confirm the code follows the project's coding standards and architecture boundaries - described in this file. -4. Run regular (fast) static checks (`prek run --from-ref --stage pre-commit`) - and fix any failures. This includes mypy checks for non-provider projects (airflow-core, task-sdk, airflow-ctl, dev, scripts, devel-common). -5. Run manual (slower) checks - (`prek run --from-ref --stage manual --skip compile-ui-assets-dev --skip view-skill-eval --skip run-skill-eval-codex`) - and fix any failures. The skipped hooks start long-running local servers or provision the - opt-in Codex environment rather than run checks that complete. -6. Run relevant individual tests and confirm they pass. -7. Find which tests to run for the changes with selective-checks and run those tests in parallel to confirm they pass and check for CI-specific issues. -8. Check for security issues — no secrets, no injection vulnerabilities, no unsafe patterns. - -Before pushing, always rebase your branch onto the latest target branch (usually `main`) -to avoid merge conflicts and ensure CI runs against up-to-date code: - -```bash -git fetch upstream -git rebase upstream/ -``` - -If there are conflicts, resolve them and continue the rebase. If the rebase is too complex, -ask the user for guidance. - -Then push the branch to your fork (`origin`) and open the PR creation page in the browser -with the body pre-filled (including the generative AI disclosure already checked): - -```bash -git push -u origin -gh pr create --web --title "Short title (under 70 chars)" --body "$(cat <<'EOF' -Brief description of the changes. - -closes: #ISSUE (if applicable) - ---- - -##### Was generative AI tooling used to co-author this PR? - -- [X] Yes — - -Generated-by: following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions) - -EOF -)" -``` - -The `--web` flag opens the browser so the user can review and submit. The `--body` flag -pre-fills the PR template with the generative AI disclosure already completed. - -Remind the user to: - -1. Review the PR title — keep it short (under 70 chars), in the imperative mood, and focused on user impact. Do not use Conventional Commits prefixes (`fix:`, `feat:`, `chore:`, …). -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`). - -### Golden rule: when a fix is imminent, open the PR, not an issue - -If you already know how to fix the problem and you (or the user) are going to -open the PR shortly, **do not file a GitHub issue first**. Go straight to the -PR. - -- Airflow does not use issues as a changelog, as a parallel bug database, or - as a duplicate record of in-flight work. The PR itself is the canonical - record — title, description, diff, discussion, and merge all live in one - place. An issue that gets closed by a PR a day later is double accounting - that carries no information the PR does not already carry. -- Open issues attract drive-by submissions, often from other agents, that - haven't seen the in-flight work. That produces duplicate fixes, low-quality - PRs that have to be closed, and wasted reviewer time. Not opening the - issue avoids creating that bait in the first place. -- If you catch yourself drafting an issue body that reads like the PR - description you are about to write, that is the signal — skip the issue - and open the PR. - -The one exception is the case covered by the next section: the PR ships a -**workaround, mitigation, or partial fix** and the real follow-up work is -genuinely deferred to a later PR. There, the issue captures work that will -outlive the PR, so the issue is load-bearing rather than duplicate. - -### 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. - -### GitHub messages drafted by agents - -Anything an agent drafts that ends up posted to GitHub on the user's -account — PR / issue comments, PR-level reviews, line-level review -comments, discussion replies — must end with an attribution footer. -The footer is required whether or not a human reviewed the draft -first; what changes between the two cases is the wording. - -Place the footer on its own paragraph at the end of the message, -separated from the body by a blank line and a horizontal rule. Use -the same agent name string used in `Generated-by:` on PR bodies (for -example, `Claude Code (Opus 4.7)`). - -- **Agent draft, posted without prior human review** (autonomous / - routine work, scheduled triage, etc.): - - ``` - --- - Drafted-by: (no human review before posting) - ``` - -- **Agent draft, reviewed and approved by a human maintainer before - posting:** - - ``` - --- - Drafted-by: ; reviewed by @ before posting - ``` - - The `@` is the human who actually read the draft - and said "post it as-is" (or similar). It is not the user the agent - is "running on behalf of" if no review took place — that case is the - first form, not this one. - -This footer is in addition to, not a replacement for, any per-tool -disclosure rules (the PR body still keeps its own `Generated-by:` -block under the AI-disclosure checkbox; commit messages still follow -the no-self-as-co-author rule above). Do not skip the footer to -shorten a message — attribution applies regardless of message length. - -#### Do not tag individuals - -AI agents MUST NOT mention or tag individual contributors, committers, -PMC members, or maintainers using GitHub usernames (e.g. `@user`) unless -explicitly instructed by a human reviewer. When suggesting who might be -relevant to a discussion, refer to roles, teams, code ownership -information, labels, or components instead of individuals. This keeps -notification noise down and avoids pulling people into threads they have -not chosen to join. - -The only exceptions are mentions a human has explicitly authorized — -including the `@` in the `Drafted-by: … reviewed by -@` footer above, which names the reviewer who approved the -message — and replying within a thread to people already actively -participating in that same PR/issue discussion. +Use the contribution skills below when available. If the runtime does not support +skill discovery, read the linked `SKILL.md` directly. If either skill is +unavailable, do not publish, push, create or modify GitHub issues or pull +requests, or rename or add Git remotes. You may draft text or propose commands, +but must state that the relevant skill could not be read and request confirmation +before any remote-changing action. + +- [Draft contribution text](.agents/skills/airflow-pr-draft-summary/SKILL.md): + commit messages, PR titles/descriptions, release notes and GitHub messages. +- [Publish changes](.agents/skills/airflow-publish-changes/SKILL.md): + existing PR checks, remotes, pre-push review, publication and deferred-work issues. + +Before working on an issue, check for existing PRs. Push only to the user's fork, +never upstream or `main`. Never list an agent as a commit co-author. Retain the +required Gen-AI disclosure and GitHub-message attribution; do not tag individuals +outside the exceptions in the message guidance. Drafting does not authorize posting. ## apache-magpie framework diff --git a/dev/skill-evals/last-eval-hash.txt b/dev/skill-evals/last-eval-hash.txt index 4261daf7f9c..d7d5ed6e509 100644 --- a/dev/skill-evals/last-eval-hash.txt +++ b/dev/skill-evals/last-eval-hash.txt @@ -1,3 +1,3 @@ # Generated by dev/skill-evals/eval.py — do not edit or resolve conflicts by hand. # Run `prek run run-skill-eval --hook-stage manual --all-files` to regenerate. -e1c1913cdf9483da0fd4d41b04c3c8b079f313860e22a4c3fe3945ddee15e0f1 +0931cd86d4490f26696e6a5f5399060666f748d5ed9cb30db0cbe9f84849fddf