Skip to content

[plan] Add documentation for draft/ready_for_review state conflict #5808

@github-actions

Description

@github-actions

Objective

Document the logical conflict between converted_to_draft and ready_for_review pull request event types to help users understand state transitions vs states.

Context

Pull request events include both converted_to_draft and ready_for_review event types. While technically valid to listen for both (they represent state transitions), it may indicate unclear user intent since a PR cannot be both draft and ready simultaneously.

Approach

Add a $comment and enhance the description in the schema to clarify that these are state transitions, not states.

Files to Modify

  • Update: pkg/parser/schemas/main_workflow_schema.json (pull_request.types section)

Implementation

Enhance the types description to include guidance about state transitions:

"types": {
  "type": "array",
  "description": "Pull request event types to trigger on. Note: 'converted_to_draft' and 'ready_for_review' represent state transitions (events) rather than states. While technically valid to listen for both, consider if you need to handle both transitions or just one.",
  "$comment": "converted_to_draft and ready_for_review are logically opposite state transitions. Using both may indicate unclear intent.",
  "items": {
    "type": "string",
    "enum": [
      "assigned",
      "auto_merge_disabled",
      "auto_merge_enabled",
      "closed",
      "converted_to_draft",
      "demilestoned",
      "dequeued",
      "edited",
      "enqueued",
      "labeled",
      "locked",
      "milestoned",
      "opened",
      "ready_for_review",
      "reopened",
      "review_request_removed",
      "review_requested",
      "synchronize",
      "unassigned",
      "unlabeled",
      "unlocked"
    ]
  }
}

Acceptance Criteria

  • Enhanced description added to pull_request.types field
  • $comment added explaining the logical conflict
  • Schema is valid JSON (run make build to verify)
  • Documentation is clear and helpful for users
  • No change to validation behavior (this is documentation only)

Testing

# Rebuild binary with updated schema
make build

# Verify schema is still valid
./gh-aw --version

# Existing behavior unchanged
echo '---
on:
  pull_request:
    types: [converted_to_draft, ready_for_review]
---
Test' > /tmp/test-draft-ready.md

./gh-aw compile /tmp/test-draft-ready.md  # Should succeed (no validation added)

Notes

This is a documentation-only change to help users understand the semantics. No runtime validation is added. Users may legitimately want to trigger on both state transitions (e.g., to track all PR status changes).
Related to #5804

AI generated by Plan Command for discussion #5799

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions