apache · potiuk · Mar 2, 2026
diff --git a/contributing-docs/05_pull_requests.rst b/contributing-docs/05_pull_requests.rst
@@ -1,4 +1,4 @@
-
+contributing-docs/05_pull_requests.rst
  .. Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information
@@ -75,6 +75,15 @@ Pull Request guidelines
 Before you submit a Pull Request (PR) from your forked repo, check that it meets
 these guidelines:
 
+-   Start with **Draft**: Until you are sure that your PR passes all the quality checks and tests, keep it
+    in **Draft** status. This will signal to maintainers that the PR is not yet ready
+    for review and it will prevent maintainers from accidentally merging it before
+    it's ready. Once you are sure that your PR is ready for review, you can mark it as
+    "Ready for review" in the GitHub UI. Our regular check will convert all PRs from
+    non-collaborators that do not pass our quality gates to Draft status, so if you see
+    that your PR is in Draft status and you haven't set it to Draft. check the
+    comments to see what needs to be fixed.
+
 -   Include tests, either as doctests, unit tests, or both, to your pull request.
 
     The Airflow repo uses `GitHub Actions <https://help.github.com/en/actions>`_ to
@@ -147,6 +156,57 @@ these guidelines:
 -   Adhere to guidelines for commit messages described in this `article <https://cbea.ms/git-commit/>`_.
     This makes the lives of those who come after you (and your future self) a lot easier.
 
+.. _pull-request-quality-criteria:
+
+Pull Request quality criteria
+-----------------------------
+
+Every open PR must meet the following minimum quality criteria before maintainers will review it.
+PRs that do not meet these criteria may be automatically converted to **draft** status by project
+tooling, with a comment explaining what needs to be fixed.
+
+1. **Descriptive title** — The PR title must clearly describe the change.
+   Generic titles such as "Fix bug", "Update code", "Changes", single-word titles, or titles
+   that only reference an issue number (e.g. "Fixes #12345") do not meet this bar.
+
+2. **Meaningful description** — The PR body must contain a meaningful description of *what* the
+   PR does and *why*. An empty body, a body consisting only of the PR template
+   checkboxes/headers with no added text, or a body that merely repeats the title is not
+   sufficient.
+
+3. **Passing static checks** — The PR's static checks (pre-commit / ruff / mypy) must pass.
+   You can run them locally with ``prek run --ref-from main`` before pushing.
+
+4. **Gen-AI disclosure** — If the PR was created with the assistance of generative AI tools,
+   the description must include a disclosure (see `Gen-AI Assisted contributions`_ below).
+
+5. **Coherent changes** — The PR should contain related changes only. Completely unrelated
+   changes bundled together will be flagged.
+
+**What happens when a PR is converted to draft?**
+
+-  The comment informs you what you need to do.
+-  Fix each issue, then mark the PR as "Ready for review" in the GitHub UI - but only after making sure that all the issues are fixed.
+-  Maintainers will then proceed with a normal review.
+
+Converting a PR to draft is **not** a rejection — it is an invitation to bring the PR up to
+the project's standards so that maintainer review time is spent productively.
+
+**What happens when a PR is closed for quality violations?**
+
+If a contributor has more than 3 open PRs that are flagged for quality issues, maintainers may
+choose to **close** the PR instead of converting it to draft. Closed PRs receive the
+``closed because of multiple quality violations`` label and a comment listing the violations.
+Contributors are welcome to open a new PR that addresses the issues listed in the comment.
+
+**What happens when suspicious changes are detected?**
+
+When maintainers review a PR's diff before approving CI workflow runs and determine that it
+contains suspicious changes (e.g. attempts to exfiltrate secrets, modify CI pipelines
+maliciously, or inject harmful code), **all open PRs by the same author** will be closed
+and labeled ``suspicious changes detected``. A comment is posted on each PR explaining that
+the closure was triggered by suspicious changes found in the flagged PR.
+
 Gen-AI Assisted contributions
 -----------------------------
 

@@ -54,5 +54,5 @@ Example usage:
 
 -----
 
-Next step: Follow the `Advanced Breeze topics <12_advanced_breeze_topics.rst>`__ instructions to learn more
-about advanced Breeze topics and internals.
+Next step: Follow the `Pull request tasks <13_pr_tasks.rst>`__ instructions to learn how to
+manage GitHub pull requests with Breeze.
@@ -0,0 +1,112 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+Pull request tasks
+------------------
+
+There are Breeze commands that help maintainers manage GitHub pull requests for the Apache Airflow project.
+
+Those are all of the available PR commands:
+
+.. image:: ./images/output_pr.svg
+  :target: https://raw.githubusercontent.com/apache/airflow/main/dev/breeze/doc/images/output_pr.svg
+  :width: 100%
+  :alt: Breeze PR commands
+
+Auto-triaging PRs
+"""""""""""""""""
+
+The ``breeze pr auto-triage`` command finds open PRs from non-collaborators that don't meet
+minimum quality criteria and lets maintainers take action on them interactively.
+
+.. image:: ./images/output_pr_auto-triage.svg
+  :target: https://raw.githubusercontent.com/apache/airflow/main/dev/breeze/doc/images/output_pr_auto-triage.svg
+  :width: 100%
+  :alt: Breeze PR auto-triage
+
+The command works in several phases:
+
+1. **Fetch** — Fetches open, non-draft PRs via the GitHub GraphQL API.
+2. **Filter** — Skips collaborators, bot accounts (dependabot, renovate, github-actions),
+   and PRs already labeled ``ready for maintainer review``.
+3. **Assess** — Runs deterministic checks (CI failures, merge conflicts, missing test
+   workflows) and optionally LLM-based quality assessment (via ``claude`` or ``codex`` CLI).
+4. **Triage** — Presents flagged PRs grouped by author. For each PR the maintainer chooses
+   an action:
+
+   * **[D]raft** — Convert to draft and post a comment listing the violations (default for
+     most PRs).
+   * **[C]lose** — Close the PR, add the ``closed because of multiple quality violations``
+     label, and post a comment. This is the suggested default when the author has more than
+     3 flagged PRs.
+   * **[R]eady** — Add the ``ready for maintainer review`` label so the PR is skipped in
+     future runs.
+   * **[S]kip** — Take no action on this PR.
+   * **[Q]uit** — Stop processing.
+
+   The command computes a smart default action based on CI failures, merge conflicts, LLM
+   assessment, and the number of flagged PRs by the same author. In ``--dry-run`` mode the
+   default action is displayed without prompting.
+
+5. **Workflow approval** — PRs with no test workflows run are presented for workflow
+   approval. Before approving, the maintainer reviews the full PR diff to check for
+   suspicious changes (e.g. attempts to exfiltrate secrets or modify CI pipelines). If
+   suspicious changes are confirmed, **all open PRs by that author** are closed, labeled
+   ``suspicious changes detected``, and commented.
+
+Labels used by auto-triage
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The command uses the following GitHub labels to track triage state:
+
+``ready for maintainer review``
+   Applied when a maintainer chooses the **[R]eady** action on a flagged PR. PRs with this
+   label are automatically skipped in future triage runs, indicating the maintainer has
+   reviewed the flags and considers the PR acceptable for review.
+
+``closed because of multiple quality violations``
+   Applied when a maintainer chooses the **[C]lose** action. This label marks PRs that were
+   closed because they did not meet quality criteria and the author had more than 3 flagged
+   PRs open at the time. A comment listing the violations is posted on the PR.
+
+``suspicious changes detected``
+   Applied when a maintainer identifies suspicious changes (e.g. secret exfiltration attempts,
+   malicious CI modifications) while reviewing a PR diff during the workflow approval phase.
+   When this label is applied, **all open PRs by the same author** are closed and labeled,
+   with a comment explaining the reason.
+
+These labels must exist in the GitHub repository before using the command. If a label is
+missing, the command will print a warning and skip the labeling step.
+
+Example usage:
+
+.. code-block:: bash
+
+     # Dry run to see which PRs would be flagged and what action would be taken
+     breeze pr auto-triage --dry-run
+
+     # Run with CI checks only (no LLM)
+     breeze pr auto-triage --check-mode ci
+
+     # Filter by label and author
+     breeze pr auto-triage --label area:core --author some-user
+
+     # Limit to 10 PRs
+     breeze pr auto-triage --max-num 10
+
+     # Verbose mode — show individual skip reasons during filtering
+     breeze pr auto-triage --verbose
@@ -50,6 +50,7 @@ The following documents describe how to use the Breeze environment:
 * `Release management tasks <09_release_management_tasks.rst>`_ - describes how to use Breeze for release management tasks.
 * `UI tasks <10_ui_tasks.rst>`_ - describes how Breeze commands are used to support Apache Airflow project UI.
 * `Issues tasks <11_issues_tasks.rst>`_ - describes how Breeze commands are used to manage GitHub issues.
+* `Pull request tasks <13_pr_tasks.rst>`_ - describes how Breeze commands are used to manage GitHub pull requests.
 * `Advanced Breeze topics <12_advanced_breeze_topics.rst>`_ - describes advanced Breeze topics/internals of Breeze.
 
 You can also learn more context and Architecture Decisions taken when developing Breeze in the