This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git


The following commit(s) were added to refs/heads/main by this push:
     new c4aa191bf63 Keep what contributors need about fork CI in the 
contributor docs (#77133)
c4aa191bf63 is described below

commit c4aa191bf63d1f896f1f8bc4458d55f685cef2e4
Author: Jarek Potiuk <[email protected]>
AuthorDate: Mon Nov 16 00:28:26 2026 +0100

    Keep what contributors need about fork CI in the contributor docs (#77133)
    
    * Keep what contributors need about fork CI in the contributor docs
    
    The contributor docs and the fork CI design doc overlapped, and the
    contributor section mixed what to do with why the monitor does it, as
    was raised on the dev list. Contributors now find what their pull
    request shows and what to do in one place, with links to the design
    doc for the reasons, and the design doc points them there.
    
    Generated-by: Claude Opus 5
    Claude-Session: https://claude.ai/code/session_01NyQq9U7i5HhjDgrQ9qd3gq
    
    * Separate the two ways a fork CI pull request is closed for the gate
    
    A pull request closed because project CI ran for it although it should
    not have stays closed when its author reopens it; only a maintainer can
    reopen it, unlike one closed for changing the gate.
    
    Generated-by: Claude Opus 5
    Claude-Session: https://claude.ai/code/session_01NyQq9U7i5HhjDgrQ9qd3gq
    
    * Describe fork CI once and link to it from the other docs
    
    The pull request guide, the breeze CI commands page and the triage guide
    each restated part of how fork CI works, and the breeze page had gone
    stale (a one-week closure, drafting until green). Each now keeps what
    its reader acts on and links to the contributor section or the design.
    
    Generated-by: Claude Opus 5
    Claude-Session: https://claude.ai/code/session_01NyQq9U7i5HhjDgrQ9qd3gq
    
    * Tell maintainers to rebase or reopen after adding use project ci
    
    Adding the label by hand starts no project CI, and until the next
    monitor run a green fork result still lets the pull request merge. A
    rebase moves the head past that result, and a close and reopen starts
    project CI.
    
    Generated-by: Claude Opus 5
    Claude-Session: https://claude.ai/code/session_01NyQq9U7i5HhjDgrQ9qd3gq
---
 contributing-docs/05_pull_requests.rst             |  18 ++--
 contributing-docs/18_contribution_workflow.rst     | 105 ++++++++++++++++-----
 contributing-docs/25_maintainer_pr_triage.md       |  36 ++++---
 dev/breeze/doc/08_ci_tasks.rst                     |  31 +++---
 .../doc/ci/08_fork_ci_for_external_contributors.md |  13 ++-
 5 files changed, 123 insertions(+), 80 deletions(-)

diff --git a/contributing-docs/05_pull_requests.rst 
b/contributing-docs/05_pull_requests.rst
index d927b218f7c..5c48d35ba9d 100644
--- a/contributing-docs/05_pull_requests.rst
+++ b/contributing-docs/05_pull_requests.rst
@@ -94,14 +94,9 @@ these guidelines:
 
     The Airflow repo uses `GitHub Actions 
<https://help.github.com/en/actions>`_ to
     run the tests and `codecov <https://codecov.io/gh/apache/airflow>`_ to 
track
-    coverage. Fork CI is being piloted: it applies to pilot participants and 
to pull requests a
-    maintainer labels ``use fork ci``, and to every external contributor only 
once it is switched
-    on for everyone. Until then, enabling the ``Tests (AMD)`` workflow in your 
fork outside the
-    pilot runs CI twice for each pull request, in your fork and in 
apache/airflow. When fork CI
-    applies to you, enable that workflow and every push to your fork runs CI 
for free; pull
-    requests labelled ``fork ci required`` take their CI result from your fork 
and stay in draft
-    until that run is green. See `CI in your fork 
<18_contribution_workflow.rst#ci-in-your-fork>`__
-    and run ``breeze ci audit``, which tells you whether fork CI applies to 
you yet.
+    coverage. If your pull request's CI runs in your fork (fork CI is being 
piloted), see
+    `CI in your fork <18_contribution_workflow.rst#ci-in-your-fork>`__; 
``breeze ci audit`` tells
+    you whether it applies to you yet.
     Also we advise to install locally `prek hooks 
<08_static_code_checks.rst#prek-hooks>`_ to
     apply various checks, code generation and formatting at the time you make 
a local commit - which
     gives you near-immediate feedback on things you need to fix before you 
push your code to the PR, or in
@@ -273,10 +268,9 @@ and approves them automatically when all of these hold:
 If your PR's CI runs in your fork (it carries the ``fork ci required`` label), 
the CI run in
 ``apache/airflow`` only checks that, so none of the rules above apply. The 
``CI run started`` check
 waits until the fork CI monitor sees your fork's run, usually within 5 to 10 
minutes, and then links it. Its runs are approved
-automatically unless the PR changes files that decide which CI jobs run and on 
which runners:
-anything under ``.github/``, ``dev/breeze/src/`` or ``scripts/ci/prek/``, or
-``dev/breeze/pyproject.toml``, ``dev/breeze/uv.lock`` or 
``scripts/ci/install_breeze.sh``. Then
-the runs wait for a maintainer and a comment on the PR explains why. Changes 
to the other files
+automatically unless the PR changes files that decide which CI jobs run and on 
which runners (see
+`Changes to CI files <18_contribution_workflow.rst#changes-to-ci-files>`__). 
Then the runs wait for
+a maintainer and a comment on the PR explains why. Changes to the other files
 CI uses are not held, but a one-time comment points them out to the reviewer. 
CI in your fork
 runs either way.
 
diff --git a/contributing-docs/18_contribution_workflow.rst 
b/contributing-docs/18_contribution_workflow.rst
index 14c0c8b4b50..c59408e624e 100644
--- a/contributing-docs/18_contribution_workflow.rst
+++ b/contributing-docs/18_contribution_workflow.rst
@@ -137,9 +137,7 @@ capacity of the Apache Software Foundation (`ADIP-12, 
formerly AIP-120
 CI on a public fork costs you nothing and has no minute limit; it runs on 
every push to your
 fork, so you get feedback before a maintainer looks at your pull request. The 
change is being
 piloted: until it is switched on for everyone, it applies to pilot 
participants (see below) and
-to pull requests a maintainer labels ``use fork ci``. The `pull request 
lifecycle
-<../dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md#pull-request-lifecycle>`__
 diagram
-shows what your pull request shows at each step and who acts next.
+to pull requests a maintainer labels ``use fork ci``.
 
 Set up your checkout and fork once:
 
@@ -183,27 +181,81 @@ Set up your checkout and fork once:
 
       breeze ci audit
 
-When fork CI applies to your pull request, it is labelled ``fork ci required`` 
and kept in draft
-until the ``Tests (AMD)`` workflow runs in your fork for its latest commit. A 
failed run does not
-draft it. A
-``Fork CI / Tests (AMD)`` status on the pull request links to that run, and 
one comment on the pull
-request explains the current state. Once the run is green, a pull request the 
monitor drafted is
-marked ready for review and labelled ``ready for maintainer review``; a pull 
request you drafted
-yourself stays a draft, and gets the label, once you mark it ready. Marking a 
draft ready needs a
-free slot under the `limit on open pull requests 
<32_open_pull_request_limit.rst>`__: at the limit,
-GitHub refuses it, also when a maintainer tries, so close or finish one of 
your other open pull
-requests first. A pull request whose fork CI
-does not run for 30 days is closed with an explanation; you can reopen it 
after setting up fork CI. If your pull request changes
-files that decide which CI jobs run and where, such as ``.github/``, the 
breeze sources or
-``scripts/ci/prek/``, a green fork run is not enough: a maintainer reviews the 
change and runs project CI for it.
+GitHub reports a committer whose membership of the ``apache`` GitHub 
organisation is private as an
+external contributor, so once fork CI is switched on for everyone, their pull 
requests use it. Make
+the membership public at https://github.com/orgs/apache/people to avoid that; 
``breeze ci audit``
+reports it.
+
+What your pull request shows
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When fork CI applies to your pull request, it is labelled ``fork ci 
required``. The fork CI monitor
+checks it about every 5 minutes and keeps one comment on the pull request up 
to date with the
+current state and what to do next. It posts a new comment only when you need 
to act, for example
+to push again after you enabled the workflow. The `pull request lifecycle
+<../dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md#pull-request-lifecycle>`__
+diagram shows each step and who acts next.
+
+The checks of your pull request:
+
+* ``Fork CI / Tests (AMD)`` is the result of the ``Tests (AMD)`` run in your 
fork for the latest
+  commit and links to it: red when the workflow is not set up or the run 
failed, yellow while the
+  monitor waits for your push or the run is in progress, green when it passed.
+* ``Fork CI job / <job name>`` shows each finished job of that run and links 
to it in your fork.
+  These are for information only.
+* ``CI run started`` turns green once the monitor sees the run in your fork, 
usually within 5 to
+  10 minutes of your push.
+* ``CI passed`` is the check that merging requires. It is set when the fork 
run is green, your
+  branch is close enough to the target branch (see below) and the pull request 
does not change
+  CI files (see below).
+
+Draft state and labels:
+
+* The pull request is kept in draft until the ``Tests (AMD)`` workflow runs in 
your fork for its
+  latest commit. A failed run does not draft it.
+* Once the run is green, a pull request the monitor drafted is marked ready 
for review and labelled
+  ``ready for maintainer review``. A pull request you drafted yourself stays a 
draft, and gets the
+  label, once you mark it ready. A new push removes the label until the new 
run is green.
+* Marking a draft ready needs a free slot under the `limit on open pull 
requests
+  <32_open_pull_request_limit.rst>`__: at the limit, GitHub refuses it, also 
when a maintainer
+  tries, so close or finish one of your other open pull requests first.
+* A pull request whose fork CI has not run for 30 days, with no comments or 
reviews from people in
+  that time, is closed with an explanation. You can reopen it after setting up 
fork CI; reopening
+  restarts the 30 days.
+* A maintainer can move a single pull request to project CI with the ``use 
project ci`` label.
+  Project CI then runs on your next push, or when a maintainer closes and 
reopens the pull request.
 
 Like project CI, fork CI tests your branch merged with the target branch, as 
the target branch was
 when the run started; a push that conflicts with it fails at once and asks you 
to rebase. The
 ``CI passed`` check that merging requires is reported only when that commit of 
the target branch is
 fewer than 200 commits behind the target branch. Otherwise the pull request 
comment asks you to
-rebase on ``upstream/main`` (or the target branch) and push, which runs fork 
CI again.
-
-**Joining the pilot.** Open a pull request that adds your GitHub login to the 
``[pilot]`` table in
+rebase on ``upstream/main`` (or the target branch) and push, which runs fork 
CI again. Details:
+`Tested base 
<../dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md#tested-base>`__.
+
+Changes to CI files
+^^^^^^^^^^^^^^^^^^^
+
+If your pull request changes files that decide which CI jobs run and where 
(anything under
+``.github/``, ``dev/breeze/src/`` or ``scripts/ci/prek/``, or 
``dev/breeze/pyproject.toml``,
+``dev/breeze/uv.lock`` or ``scripts/ci/install_breeze.sh``), a green fork run 
is not enough, because
+that run used the files you changed. The pull request is labelled ``needs 
project ci`` instead of
+``ready for maintainer review``, ``Fork CI / Tests (AMD)`` stays yellow and 
``CI passed`` is not
+reported. A maintainer reviews the CI change and adds ``use project ci`` to 
run project CI for it.
+Why: `Trusting a green fork run
+<../dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md#trusting-a-green-fork-run>`__.
+
+A pull request using fork CI must not change the fork CI gate: the ``gate`` 
job of ``ci-amd.yml``,
+``dev/breeze/src/airflow_breeze/utils/fork_ci_gate.py``, the fork CI monitor or
+``.github/fork-ci-gate.toml``, except for your own ``[pilot]`` line. Such a 
pull request is closed
+with an explanation. If the change was accidental, revert it and reopen the 
pull request; if it is
+wanted, a maintainer adds ``use project ci``. A pull request for which project 
CI ran although it
+should not have is closed too, and only a maintainer can reopen it. Details: 
`Gate protection
+<../dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md#gate-protection>`__.
+
+Joining and leaving the pilot
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To join, open a pull request that adds your GitHub login to the ``[pilot]`` 
table in
 ``.github/fork-ci-gate.toml``, with a join instant after the expected merge, 
for example the next day
 at 00:00 UTC:
 
@@ -214,13 +266,14 @@ at 00:00 UTC:
 
 Every pull request you open after that instant uses fork CI. Your earlier pull 
requests keep project
 CI until you push to them, rebase them or close and reopen them after that 
instant, and use fork CI
-from then on. To leave the pilot, open a pull request that removes the line. 
Your own ``[pilot]`` line is
-the only part of the fork CI gate a pull request using fork CI may change: one 
that changes the
-gate's code, the rest of its configuration or the ``gate`` job of 
``ci-amd.yml`` is closed with an
-explanation. A pilot entry gates your pull
-requests whatever your role, so a committer in the pilot also enables the 
workflow;
-``breeze ci audit`` tells you which applies to you. The design is described in
-`Fork CI for external contributors 
<../dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md>`__.
+from then on. A pilot entry gates your pull requests whatever your role, so a 
committer in the pilot
+also enables the workflow; ``breeze ci audit`` tells you which applies to you.
+
+To leave, open a pull request that removes your line. Pull requests already 
labelled
+``fork ci required`` stay on fork CI until a maintainer adds ``use project 
ci`` to them.
+
+The design, for maintainers, is described in `Fork CI for external contributors
+<../dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md>`__.
 
 Step 3: Connect with People
 ---------------------------
diff --git a/contributing-docs/25_maintainer_pr_triage.md 
b/contributing-docs/25_maintainer_pr_triage.md
index eba118abdeb..79354a0ffd5 100644
--- a/contributing-docs/25_maintainer_pr_triage.md
+++ b/contributing-docs/25_maintainer_pr_triage.md
@@ -273,26 +273,22 @@ for them, and the triage skill must treat those pull 
requests as out of scope fo
   `close_after_days`.
 
 Everything else the skill does (quality criteria, pings, suspicious-change 
flags) applies as
-usual. The `Fork CI / Tests (AMD)` commit status shows the fork CI state and 
links to the run in
-the fork. To move a single pull request back to project CI, add `use project 
ci`; the reconciler
-releases it on its next run; removing `fork ci required` by hand is not 
enough, the next run
-labels a gated pull request again. The run that releases the pull request sets 
its `CI passed`
-status to `pending` until project CI has passed on the head commit, so the 
pull request cannot
-merge on the fork result from then on. Until that run, normally within 15 
minutes of the label
-and longer when GitHub delays a scheduled run, it still can: wait for the 
`pending` before merging
-or enabling auto-merge, or start the monitor by hand (`gh workflow run 
fork-ci-monitor.yml -R
-apache/airflow`). After project CI has passed the status turns `success` on 
the next monitor run,
-within about 15 minutes. Adding the label does not start project CI by itself, 
and the
-reconciler deletes the gated `Tests (AMD)` runs, so there is usually nothing 
to re-run: close and
-reopen the pull request (`gh pr close <n> -R apache/airflow && gh pr reopen 
<n> -R apache/airflow`),
-or ask the author to push. Pull requests that change CI-defining files are not 
drafted
-and get no `ready for maintainer review` label even when the fork run is 
green. Their
-`Fork CI / Tests (AMD)` status stays pending without `CI passed`, and they are 
labelled
-`needs project ci` until a maintainer reviews the CI change and adds `use 
project ci`, unless
-the author keeps the pull request a draft. For every other pull request, when 
the fork run is green and trusted, the reconciler also posts the
-`CI passed` status the merge ruleset requires, so it can be merged or 
auto-merged without project
-CI. See
-[Fork CI for external 
contributors](../dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md).
+usual. To move a single pull request to project CI:
+
+- Add `use project ci`. Removing `fork ci required` by hand is not enough: the 
next monitor run
+  labels a gated pull request again.
+- Right after adding the label, rebase the pull request (or ask the author to 
push), or close and
+  reopen it (`gh pr close <n> -R apache/airflow && gh pr reopen <n> -R 
apache/airflow`). Adding the
+  label does not start project CI, and the gated `Tests (AMD)` runs are 
deleted, so there is
+  nothing to re-run. A rebase also moves the head to a commit that has no fork 
result.
+- After a close and reopen, wait for the `CI passed` status to turn `pending` 
before merging or
+  enabling auto-merge: until the next monitor run, a green fork result on the 
head commit still
+  counts. To shorten the wait, start the monitor by hand
+  (`gh workflow run fork-ci-monitor.yml -R apache/airflow`).
+
+Why, and how `CI passed` is reported for gated pull requests:
+[The `CI passed` 
check](../dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md#the-ci-passed-check).
+What contributors are told to do is in [CI in your 
fork](18_contribution_workflow.rst#ci-in-your-fork).
 
 ## For contributors
 
diff --git a/dev/breeze/doc/08_ci_tasks.rst b/dev/breeze/doc/08_ci_tasks.rst
index c4001b658c0..5192d88dc66 100644
--- a/dev/breeze/doc/08_ci_tasks.rst
+++ b/dev/breeze/doc/08_ci_tasks.rst
@@ -186,13 +186,10 @@ Reconciling pull requests gated to fork CI
 
 Pull requests from external contributors can run their CI in the contributor's 
fork instead of in
 ``apache/airflow`` (AIP-120). The ``fork-ci-reconcile`` command, run every 5 
minutes by the
-``fork-ci-monitor.yml`` workflow, is the only place that changes those pull 
requests: it labels newly
-gated pull requests ``fork ci required``, keeps them in draft until the fork 
run is green, maintains
-one state comment and a ``Fork CI / Tests (AMD)`` commit status linking to the 
run in the fork, closes
-pull requests without fork CI activity for a week, closes gated pull requests 
that made project CI run
-by changing workflows, and writes everything it could not classify to a Slack 
message. With
-``--dry-run`` it prints the changes instead of applying them. See
-`Fork CI for external contributors 
<ci/08_fork_ci_for_external_contributors.md>`_ for the design.
+``fork-ci-monitor.yml`` workflow, is the only place that changes those pull 
requests: their labels,
+draft state, state comment and commit statuses. With ``--dry-run`` it prints 
the changes instead of
+applying them. What it does is described in
+`Fork CI for external contributors 
<ci/08_fork_ci_for_external_contributors.md#reconciler>`_.
 
 These are all available flags of ``fork-ci-reconcile`` command:
 
@@ -205,19 +202,13 @@ Approving workflow runs of external contributors
 ------------------------------------------------
 
 The ``auto-approve-workflow-runs`` workflow runs ``approve-workflow-runs`` 
every 15 minutes. It approves
-the waiting workflow runs of external contributors' PRs to ``main`` whose CI 
jobs are estimated at no more
-than 310 job-minutes, that change at most 100 lines of source code and that do 
not touch CI definition files, and labels the other PRs ``need workflow 
approval``, with a pending
-``Workflow approval`` commit status on their head commit that gives the 
reason. Once a maintainer
-approves the runs and they start, the ``mark-workflow-runs-approved`` workflow 
removes the label and
-turns the status green. PRs whose CI runs in
-the contributor's fork (AIP-120) only run the fork CI gate in 
``apache/airflow``, so their runs are
-approved whatever their size unless they change CI definition files; such a PR 
gets a comment
-instead of the label, explaining that its CI change needs a maintainer. The 
runs of PRs from the repositories of trusted
-stakeholders (Amazon, Google, Astronomer) are always approved. For every PR it 
also
-estimates the CI jobs selective checks will run and how long they take, and 
writes them to the job
-summary. Use ``--report-only`` to see the decisions without approving runs or 
changing labels or
-statuses. The rules
-are described in `CI workflows <ci/05_workflows.md>`_.
+the waiting workflow runs of external contributors' PRs that its rules allow, 
and labels the other PRs
+``need workflow approval``, with a pending ``Workflow approval`` commit status 
on their head commit
+that gives the reason. For every PR it also estimates the CI jobs selective 
checks will run and how
+long they take, and writes them to the job summary. Use ``--report-only`` to 
see the decisions without
+approving runs or changing labels or statuses. The rules, including those for 
PRs whose CI runs in
+the contributor's fork, are described in
+`Approval of pull request runs 
<ci/05_workflows.md#approval-of-pull-request-runs>`_.
 
 These are all available flags of ``approve-workflow-runs`` command:
 
diff --git a/dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md 
b/dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md
index 450d7ea54f6..0add70130a4 100644
--- a/dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md
+++ b/dev/breeze/doc/ci/08_fork_ci_for_external_contributors.md
@@ -40,6 +40,13 @@
 
 # Fork CI for external contributors (AIP-120)
 
+> **Note:** This is the maintainer and design reference for fork CI. If you 
are a contributor
+> setting up CI in your fork or working out what the bot's comment, labels and 
statuses on your
+> pull request mean, read
+> [CI in your 
fork](../../../../contributing-docs/18_contribution_workflow.rst#ci-in-your-fork)
+> instead. Maintainers triaging gated pull requests also see
+> [Pull requests gated to fork 
CI](../../../../contributing-docs/25_maintainer_pr_triage.md#pull-requests-gated-to-fork-ci).
+
 This document is the design of the CI changes implementing
 [AIP-120: Run CI for external contributions in contributor 
forks](https://cwiki.apache.org/confluence/spaces/AIRFLOW/pages/451974711/AIP-120+Run+CI+for+external+contributions+in+contributor+forks).
 The policy itself and its rationale live in the AIP and in the dev list 
discussions
@@ -1119,8 +1126,10 @@ run.
   before the label stays until the next monitor run that completes: normally 
within one cadence
   (5 minutes), longer when GitHub delays or drops a scheduled run or a run 
fails, and one more
   cycle when the label arrives after a run has taken its snapshot of the pull 
request. The pull
-  request can merge on the fork result in that window. A maintainer who adds 
the label to a pull
-  request whose fork CI is green waits for the `pending` before merging or 
enabling auto-merge,
+  request can merge on the fork result in that window. A maintainer who adds 
the label by hand
+  then rebases the pull request or closes and reopens it, since the label does 
not start project
+  CI. A rebase moves the head to a commit without the fork result, which 
closes the window; after a
+  close and reopen, the maintainer waits for the `pending` before merging or 
enabling auto-merge,
   or starts the monitor by hand (`workflow_dispatch`). A strict merge-time 
guarantee needs a
   required check bound to a source, which is out of scope here. Revoking a 
`success` is never
   limited by the per-run budget of commit statuses; posting the project CI 
`success` is.

Reply via email to