This is an automated email from the ASF dual-hosted git repository. potiuk pushed a commit to branch fork-ci-pr-lifecycle-diagram in repository https://gitbox.apache.org/repos/asf/airflow.git
commit 5f3c94b0fba3a0e9c2222fe57f3a711809511564 Author: Jarek Potiuk <[email protected]> AuthorDate: Tue Nov 10 06:15:51 2026 -0700 Add a pull request lifecycle diagram for fork CI The design document only had the reconciler's internal state machine. Add the contributor's and maintainer's view: what a gated pull request shows at each step, from opening to merge or close, and who acts next. Link it from the contributor docs, and point their ADIP-12 link at the renamed wiki page. Generated-by: Claude Opus 5 --- contributing-docs/18_contribution_workflow.rst | 8 ++-- .../doc/ci/08_fork_ci_for_external_contributors.md | 52 ++++++++++++++++++++++ 2 files changed, 57 insertions(+), 3 deletions(-) diff --git a/contributing-docs/18_contribution_workflow.rst b/contributing-docs/18_contribution_workflow.rst index 065dfb0cab1..5431cc5e3c9 100644 --- a/contributing-docs/18_contribution_workflow.rst +++ b/contributing-docs/18_contribution_workflow.rst @@ -132,12 +132,14 @@ CI in your fork Pull requests from contributors who are not committers or collaborators are moving to running their CI in the contributor's own fork, on GitHub's free runners, instead of on the shared CI -capacity of the Apache Software Foundation (`AIP-120 -<https://cwiki.apache.org/confluence/spaces/AIRFLOW/pages/451974711/AIP-120+Run+CI+for+external+contributions+in+contributor+forks>`__). +capacity of the Apache Software Foundation (`ADIP-12, formerly AIP-120 +<https://cwiki.apache.org/confluence/spaces/AIRFLOW/pages/451974711>`__). 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``. +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. Set up your checkout and fork once: 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 abe89ba3a7c..36118c452c6 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 @@ -109,6 +109,58 @@ Four pieces, in dependency order: Plus `breeze ci audit` for the contributor's local setup, and documentation. +### Pull request lifecycle + +What a gated pull request shows, and who acts next, from the moment it is opened until it is merged +or closed. The [state machine](#state-machine) below is the reconciler's view of the same flow; this +diagram is the contributor's and the maintainer's view. Pull requests of committers, collaborators +and exempted organisations are not gated and follow the usual project CI flow. + +```mermaid +%%{init: {'theme': 'neutral'}}%% +stateDiagram-v2 + state "Waiting for the author: draft, fork CI not set up or no run for the head commit" as waiting + state "Fork CI running" as running + state "Fork CI failed: out of the review queue" as failed + state "Green: ready for maintainer review, CI passed" as ready + state "Green, base too old: ready for maintainer review, CI passed pending until a rebase" as rebase + state "Green, CI files changed: needs project ci" as needs_project_ci + state "Project CI: use project ci" as project_ci + state "Approved" as approved + state "Merged" as merged + state "Closed after 30 days without fork CI activity" as closed + + [*] --> waiting: an external contributor opens a pull request + waiting --> running: the author enables the fork workflow and pushes + running --> failed: a job fails, times out or is cancelled, or the run cannot start + running --> ready: the run passes on a current base + running --> rebase: the run passes, but the base is 200+ commits behind or changed the same files + running --> needs_project_ci: the run passes, and the pull request changes CI-defining files + failed --> running: the author pushes a fix + rebase --> running: the author rebases and pushes + ready --> running: the author pushes + ready --> approved: a maintainer approves + rebase --> approved: a maintainer approves, the merge waits for the rebase + ready --> project_ci: a maintainer adds use project ci + needs_project_ci --> project_ci: a maintainer reviews the CI change and adds use project ci + project_ci --> approved: project CI passes and a maintainer approves + approved --> merged: merged, or auto-merged once CI passed is green + waiting --> closed: 30 days without fork CI activity + closed --> waiting: the author reopens it + merged --> [*] +``` + +- **Draft** is used only while the pull request waits for its author to set up fork CI or push. A + failed run leaves the draft state unchanged and removes `ready for maintainer review`, so a flaky + test after a rebase cannot draft an approved pull request or cancel its auto-merge. +- **`CI passed`** is what merging waits for, by hand or with auto-merge. A green fork run sets it + only on a current base ([Tested base](#tested-base)) and only when the pull request does not change + CI-defining files ([Trusting a green fork run](#trusting-a-green-fork-run)). Otherwise project CI + sets it. +- **`use project ci`** moves a single pull request to project CI at any point; `use fork ci` moves + it back ([Override labels](#override-labels)). + + ## Configuration One file, `.github/fork-ci-gate.toml`, parsed with the standard library `tomllib`:
