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
commit d45e8ea41496228f7dec950084a4e08b949ffcf5 Author: Jarek Potiuk <[email protected]> AuthorDate: Sun Nov 15 05:00:51 2026 +0100 Add a pull request lifecycle diagram for fork CI (#76839) * 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 * Show the missing exits in the fork CI pull request lifecycle The lifecycle diagram now has the author's draft green state, the way back to running for an approved pull request, for one that needs project CI and for a disabled fork workflow, and says that `use project ci` takes effect on the next push or a close and reopen. Generated-by: Claude Opus 5 --- contributing-docs/18_contribution_workflow.rst | 8 +-- .../doc/ci/08_fork_ci_for_external_contributors.md | 62 ++++++++++++++++++++++ 2 files changed, 67 insertions(+), 3 deletions(-) diff --git a/contributing-docs/18_contribution_workflow.rst b/contributing-docs/18_contribution_workflow.rst index c855ff63b6b..617cf0c6c03 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 6bbe9ea97f1..fcd86b05ccb 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,68 @@ 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, author's draft: stays a draft, no review label until the author marks it ready" as author_draft + 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, runs on the next push or a close and reopen" 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 --> waiting: the fork workflow is disabled + 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 --> author_draft: the run passes, and the author made the pull request a draft + 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 + author_draft --> ready: the author marks it ready for review + failed --> running: the author pushes a fix + rebase --> running: the author rebases and pushes + ready --> running: the author pushes + needs_project_ci --> 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 --> running: the author pushes or rebases + 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. A pull + request its author opened as a draft, or converted to one, stays a draft when fork CI passes and + gets no `ready for maintainer review`: the author marks it ready for review next. +- **`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)). Adding the label does not start project CI: it + runs on the next push, or when a maintainer closes and reopens the pull request, and waits for a + maintainer's approval when the repository's approval setting covers the author. + + ## Configuration One file, `.github/fork-ci-gate.toml`, parsed with the standard library `tomllib`:
