move required status checks into Merge Queue ruleset (#4113)

* move required status checks into Merge Queue ruleset

* Let committers bypass the Merge Queue ruleset for urgent fixes

Replace classic branch protection with an equivalent ruleset, since
classic protection blocks ruleset bypass, and add apache/iceberg-public
as a pull-request bypass actor on the Merge Queue ruleset. Ports
apache/iceberg-rust#3458, #3481, and #3489.

* Move urgent PR merge docs to end of contributing guide

Keep the committer-only procedure out of the contributor setup flow, and
indent the code block 4 spaces so mkdocs renders it inside the list.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Kevin Liu <kevin.jq.liu@gmail.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: 3 people

.asf.yaml

@@ -33,38 +33,60 @@ github:
     squash: true
     squash_commit_message: PR_TITLE_AND_COMMIT_DETAILS
     rebase: true
-  protected_branches:
-    main:
-      required_status_checks:
-        contexts:
-          # Repository policy and security checks.
-          - Analyze Actions
-          - Run zizmor 🌈
-          - asf-allowlist-check
-          - rat
-
-          # Documentation checks.
-          - docs
-          - markdown-link-check
-
-          # Python workflow gates.
-          - python-ci-required
-          - python-integration-required
-
+  # Disabled: GitHub blocks ruleset bypass while classic protection exists.
+  # The "Default Branch Protection" ruleset replaces it.
+  protected_branches: ~
+  rulesets:
+    - name: "Default Branch Protection"
+      type: branch
+      branches:
+        includes:
+          - "~DEFAULT_BRANCH"
+        excludes: []
+      bypass_teams:
+        - root
+      restrict_deletion: true
+      restrict_force_push: true
+      required_linear_history: true
       required_pull_request_reviews:
         required_approving_review_count: 1
-
-      required_linear_history: true
-  rulesets:
     - name: Merge Queue
       target: branch
       enforcement: active
+      bypass_actors:
+        # apache/root (ASF Infra).
+        - actor_id: 118420
+          actor_type: Team
+          bypass_mode: always
+        # apache/iceberg-public. Iceberg committers can opt into this team via
+        # https://gitbox.apache.org/boxer/.
+        - actor_id: 20107235
+          actor_type: Team
+          bypass_mode: pull_request
       conditions:
         ref_name:
           include:
             - "~DEFAULT_BRANCH"
           exclude: []
       rules:
+        - type: required_status_checks
+          parameters:
+            # Merge Queue already tests each entry against the latest main
+            strict_required_status_checks_policy: false
+            required_status_checks:
+              # Repository policy and security checks.
+              - context: Analyze Actions
+              - context: Run zizmor 🌈
+              - context: asf-allowlist-check
+              - context: rat
+
+              # Documentation checks.
+              - context: docs
+              - context: markdown-link-check
+
+              # Python workflow gates.
+              - context: python-ci-required
+              - context: python-integration-required
         - type: merge_queue
           parameters:
             check_response_timeout_minutes: 90

AGENTS.md

@@ -68,7 +68,7 @@ lives under `pyiceberg/`, organized by concern rather than by engine:
 
 ### Required CI and Merge Queue
 
-- Keep the `required_status_checks.contexts` list in `.asf.yaml` synchronized whenever a required job/check is added, renamed, or removed. Each entry is a job/check context name, not a workflow filename.
+- Keep the `required_status_checks` list in the `Merge Queue` ruleset in `.asf.yaml` synchronized whenever a required job/check is added, renamed, or removed. Each entry is a job/check context name, not a workflow filename.
 - Verify that every required context reports for both `pull_request` and `merge_group`. Its producer workflow must run on both events.
 - When a workflow uses an aggregate required job, such as `python-ci-required`, keep `if: always()` and its `needs` list in sync with every job whose result should block merging.
 - Do not use `pull_request` path filters in workflows that produce required contexts. A skipped workflow does not report its required context, which blocks pull requests and causes Merge Queue entries to time out.

mkdocs/docs/contributing.md

@@ -338,3 +338,17 @@ For the type annotation the types from the `Typing` package are used.
 ### Third party libraries
 
 PyIceberg naturally integrates into the rich Python ecosystem, however it is important to be hesitant adding third party packages. Adding a lot of packages makes the library heavyweight, and causes incompatibilities with other projects if they use a different version of the library. Also, big libraries such as `s3fs`, `adlfs`, `pyarrow`, `thrift` should be optional to avoid downloading everything, while not being sure if is actually being used.
+
+## Merging an urgent PR
+
+Committers can merge an urgent, approved pull request without waiting for the merge queue or required checks (for example, a security fix while CI is stuck). Use this only when necessary; otherwise, let the merge queue run.
+
+<!-- markdown-link-check-disable-next-line -->
+1. Join the [`apache/iceberg-public`](https://github.com/orgs/apache/teams/iceberg-public) team via [Boxer](https://gitbox.apache.org/boxer/) (one-time; membership syncs in about 15 minutes).
+2. Get the pull request approved by a committer.
+3. If the pull request is in the merge queue, click **Remove from queue**.
+4. Merge it directly:
+
+    ```sh
+    gh pr merge <number> --squash --admin
+    ```