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.