hiero-ledger / hiero-ledger/hiero-sdk-python

feat: implement revision-guard for automated PR drafting and queue health management

Open
#2,264 14 comments 0 reactions 2 assignees Claimed by @darshit2308 View on GitHub
skill: intermediate
Dominant language
Python
Stars
63
Forks
298
Avg merge
3d 18h
Merged PRs (30d)
38

Description

### Problem

Currently, the PR review lifecycle has a few gaps that can lead to wasted reviewer time and noisy bot interactions:

1. **Stale/Incomplete PRs in the Queue:** When a maintainer clicks "Request Changes" on a PR, the PR remains open. It can easily be accidentally re-reviewed before the author has actually pushed fixes.
2. **Format Failures:** If a PR is opened but fails basic formatting checks (missing DCO, missing issue link, GPG signature missing), it still sits in the open PR list. Reviewers might start looking at structurally invalid PRs.
3. **Notification Spam vs. Silent Failures:** If a bot comments every time a check fails, it spams the PR. If it uses basic deduping (only posting once), authors might not get notified if their second attempt *also* fails.

### Solution

I propose introducing a new, self-contained automation module called **`revision-guard`**.

> **Architecture Note**: This module will be built using the exact same self-contained folder pattern established by `review-sync` (e.g., its own `index.js`, `package.json`, `helpers/`, and `tests/`). This modularity ensures it can be effortlessly migrated to the centralized `sdk-automations` repository in the future.

The `revision-guard` will manage the "draft" lifecycle of PRs using three safe, distinct triggers:

**1. Auto-Draft on `CHANGES_REQUESTED` (Real-Time)**
When a reviewer requests changes, the PR is automatically converted to a Draft.
* **Action:** Converts to Draft, removes any `queue:*` labels, applies `status: needs-revision`, and posts a notification to the author.
* **Security:** Uses the existing safe two-workflow pattern (`pull_request_review` saves an artifact -> `workflow_run` picks it up with write permissions).

**2. Auto-Draft on Format Failures (Cron-Integrated)**
If a PR is missing DCO, issue links, or has merge conflicts, it should not be in the review queue.
* **Action:** We integrate format checks *directly into the `review-sync` cron job*. Before the cron applies a `queue:*` label, it runs format checks. If they fail, `revision-guard` converts the PR to draft, applies `status: needs-revision`, and **skips** applying the queue label.
* **Benefit:** This completely eliminates the "Ready for Review" timing gap. If an author clicks "Ready for review" but hasn't fixed the format, the next cron run will instantly draft it again without ever putting it back in the reviewer queue.

**3. CI Pipeline Failures (Label Only)**
* **Action:** If the actual CI pipeline fails (tests, build), the cron will apply a `status: failed checks` label.
* **Note:** We will *not* auto-draft on CI failures, as these could be due to flaky tests or repo-side infrastructure issues, which isn't the contributor's fault.

**4. Edit-In-Place Notifications (Anti-Spam)**
To solve the notification problem, `revision-guard` will use an "edit-in-place" comment strategy (`postOrUpdateComment`).
* Instead of posting 5 comments for 5 failed attempts, the bot finds its existing notification comment (via HTML markers) and **edits** it with the latest timestamp and failure details.
* Because GitHub sends notifications on comment *edits*, the author is always informed when their PR is kicked back to draft, but the PR timeline remains perfectly clean.

### Alternatives

1. **Auto-undrafting when the user pushes new commits:** Considered and rejected. An author might push a partial fix (e.g., addressing 1 out of 3 comments). It is much safer to let the author manually click the "Ready for review" button when they are completely finished.
2. **Posting new comments on every redraft:** Considered and rejected. This would create massive comment spam on PRs where contributors are struggling with DCO/formatting. The edit-in-place approach provides notifications without the spam.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.