Proposal: workflow labels to move PRs/MRs forward

[wasphin]

When many pull requests or merge requests (PRs/MRs) are open, maintainers need to
quickly distinguish new work, reviews already being handled, author follow-ups,
and changes ready for a maintainer decision or merge.

The goal is a clear next-action queue with little extra process. The usual path
is: new change -> AI review -> author fixes or maintainer review -> merge.
AI review helps with initial triage; maintainers retain the final decision and
can review directly whenever that is more useful.

Labels and maintainer attention

Use the hosting platform's Draft/WIP capability while a change is being prepared,
without a workflow label. Once it is ready, use one of these mutually exclusive
labels:

• status/ready-for-review: New or revised work waiting for review to be arranged. Maintainers can trigger an AI review first or review directly.
• status/review-in-progress: The current review has been taken up by a person or an AI service. Maintainers can normally leave it to proceed.
• status/awaiting-author: Review has identified changes or clarification that need an author response before the change can advance.
• status/awaiting-maintainer: Review or an author response needs a maintainer decision, verification, or approval.
• status/ready-to-merge: Required approvals and checks are satisfied, with no blocking feedback remaining; ready to merge.
• status/blocked: An external dependency prevents progress; the reason and unblock condition are stated.

For daily triage, maintainers can focus on ready-for-review,
awaiting-maintainer, and ready-to-merge. review-in-progress and
awaiting-author normally do not need another maintainer pass until the next
handoff. A failed or stalled review must return to the attention queue rather
than remain hidden as in progress.

Labels describe the main pending action, not permissions or exclusive ownership.
Anyone may contribute a review. Reviewers do not need to claim the change,
declare a scope, or submit an extra status report. Maintainers or automation can
maintain the labels using ordinary review activity.

Normal handoffs

1. Ready for review. A change opened ready for review, or moved out of
   Draft/WIP, enters status/ready-for-review.
2. Arrange the review. A maintainer can trigger an AI review and move the
   change to status/review-in-progress once the service accepts the task.
   This includes an accepted task waiting to run. A failed request leaves it
   ready for review. A human reviewer starting work can use the same in-progress
   state.
3. Review completes. If feedback needs an author response before the change
   can advance, move to status/awaiting-author. Otherwise, move to
   status/awaiting-maintainer.
   Existing blocking feedback must still be addressed, even if the latest review
   found no new problems.
4. Author responds. After code changes are ready for another review, return
   to status/ready-for-review, or directly to in progress if that review is
   already taken up. A clarification requested by a maintainer returns directly
   to status/awaiting-maintainer; it need not repeat AI review. Disputed AI
   findings also go to a maintainer for a decision.
5. Maintainer decides. Questions or required changes go to
   status/awaiting-author. If further AI or specialist review is useful, arrange
   that review. Otherwise, approve and move to status/ready-to-merge when all
   merge conditions are satisfied, then merge.

A maintainer can review a change directly without a preliminary AI pass. They
may keep status/awaiting-maintainer while making the final decision, or use
status/review-in-progress if it is being handled over a longer review session.
There is no need to visit every state for a small change.

AI access or credits are not required from authors. Maintainers can arrange an
available AI review; authors may also arrange one themselves. A review already
arranged by the author can enter in progress directly, without a duplicate launch.
AI findings are advisory. Authors can address them through code changes or an
explanation; unresolved disagreements go to a maintainer for a decision. An
author response requests the next handoff; it does not by itself establish that
all merge conditions are satisfied. Non-blocking suggestions do not delay
handoffs or merging.

Parallel reviews

Human reviewers and AI agents may independently review the same scope or the
entire change. review-in-progress helps maintainers avoid unnecessary duplicate
triage; it does not prohibit another review.

The label follows the current handoff, not a count of all reviewers. Once the
review being used for that handoff finishes, move to author or maintainer as
appropriate. Additional optional reviews do not keep the change in progress or
hold up merging simply because they are still running. Any blocking findings
they raise still need to be considered. One positive review cannot clear another
review's outstanding blocking feedback.

State transitions

The diagram shows the main path and its common returns. Draft/WIP and merged
are native lifecycle states, not additional workflow labels.

stateDiagram-v2
    state "Draft / WIP" as Draft
    state "status/ready-for-review" as Reviewable
    state "status/review-in-progress" as Reviewing
    state "Review handoffs" as Handoffs {
        direction LR
        state "status/awaiting-author" as Author
        state "status/awaiting-maintainer" as Maintainer
        Maintainer --> Author: Questions or changes needed
        Author --> Maintainer: Clarification or disputed finding
    }
    state "status/ready-to-merge" as Ready
    state "status/blocked" as Blocked
    state "Merged" as Merged

    [*] --> Draft: Open as draft
    [*] --> Reviewable: Open ready for review
    Draft --> Reviewable: Author marks ready
    Reviewable --> Reviewing: AI task accepted or human review starts
    Reviewable --> Maintainer: Maintainer reviews directly
    Reviewing --> Author: Author response needed
    Reviewing --> Maintainer: No author action needed
    Reviewing --> Maintainer: Review failed or stalled
    Author --> Reviewable: Revised code ready for review
    Author --> Reviewing: Follow-up review already taken up
    Maintainer --> Reviewable: Further review needed
    Maintainer --> Reviewing: Further review already taken up
    Maintainer --> Ready: Approved and all merge conditions satisfied
    Ready --> Reviewable: New revision needs review
    Ready --> Merged: Merge
    Merged --> [*]

    Maintainer --> Blocked: External dependency
    Blocked --> Maintainer: Dependency resolved, resume decision

    note right of Reviewing
        Normally no maintainer action is needed here.
        Parallel reviews of the same scope are welcome.
        A late result cannot overwrite a newer handoff.
    end note

    note right of Blocked
        One blocking path is shown.
        Any review state may be blocked.
        Resume according to the remaining work.
    end note

Loading

Avoiding lost or misleading states

• A review cannot start or finish. A rejected launch stays ready for review.
  An accepted review that fails, is cancelled, or stalls returns to
  status/awaiting-maintainer for retry, replacement, or direct review, provided
  it is still the current handoff. A superseded task's failure must not overwrite
  a newer state. Failure must not be treated as a successful review. Automation
  should detect missing completion; in manual use, a stalled review needs a
  maintainer follow-up.
• The author pushes commits. A push alone neither requests author action nor
  proves that existing feedback is resolved. Keep status/awaiting-author until
  the author submits the revision or a maintainer accepts the response. If a new
  revision supersedes an in-progress review or merge readiness, arrange review of
  that revision and use ready for review or in progress as appropriate.
• A late result arrives. An obsolete review cannot overwrite a newer handoff
  or mark a new revision ready to merge. Automation should check the revision and
  current handoff before updating labels; useful earlier findings remain available.
• Checks are pending or fail. Routine CI execution is not an external blocker.
  If review is otherwise complete, keep awaiting maintainer until the required
  checks permit merge readiness. Code failures needing author changes go to
  awaiting author; infrastructure failures preventing progress may be blocked.
  If a ready-to-merge change loses a required condition, remove that label and
  return it to the appropriate author or maintainer queue.
• An external dependency blocks progress. Use status/blocked with a brief
  reason and unblock condition. Once resolved, choose the next state from the
  remaining work rather than blindly restoring an old in-progress state.
• The author returns to Draft/WIP. Clear the workflow label and pause normal
  handoffs. Preserve existing feedback, and prevent superseded tasks from
  advancing the change. A change may also be closed from any open state.

Platform independence and rollout

The states and handoff rules apply across hosting systems. Use labels or an
equivalent filterable field, and map Draft/WIP, reviews, checks, approvals, and
merge outcomes to each platform's facilities. No specific bot, comment command,
review provider, or CI product is required.

Start with manual labels and a small trial. Discuss the definitions before
building automation. After community agreement, document the workflow in a
contribution guide and provide an agent skill that follows the same definitions.

Feedback on the labels and handoff rules is welcome.

[wwbmmm]

Maybe we need to use AI to automatically manage these labels.

[chenBright]

Agreed.

[wasphin]

Definitely. Once we agree on the workflow, humans, agents, and bots can all follow it to move things forward.