feat: add PR draft explainer workflow

[parvninama]

Added :

• Adds PR Draft Explainer workflow triggered on pull_request: converted_to_draft
• Adds bot-pr-draft-explainer.js to handle the automation logic
• Ensures the bot only comments when a CHANGES_REQUESTED review exists
• Adds workflow_dispatch with dry_run support for manual testing

Testing :

The workflow was tested using workflow_dispatch with DRY_RUN=true.

• PR not draft
  https://github.com/parvninama/hiero-sdk-python/actions/runs/22733624043/job/65929092608

• Draft PR without CHANGES_REQUESTED
  https://github.com/parvninama/hiero-sdk-python/actions/runs/22734149228/job/65930898806

• Draft PR with CHANGES_REQUESTED
  https://github.com/parvninama/hiero-sdk-python/actions/runs/22733854438/job/65929873543

Linked Issue :

• Fixes [Beginner]: Create a workflow if a PR is moved to draft with changes requested, it comments explaining #1723

[github-actions]

Hi @parvninama, this is **LinkBot** 👋

Linking pull requests to issues helps us significantly with reviewing pull requests and keeping the repository healthy.

🚨 This pull request does not have an issue linked.
If this PR remains unlinked, it will be automatically closed.

Please link an issue using the following format:

Fixes #123

📖 Guide:
docs/sdk_developers/how_to_link_issues.md

If no issue exists yet, please create one:
docs/sdk_developers/creating_issues.md

Thanks!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main    #1907   +/-   ##
=======================================
  Coverage   93.53%   93.53%           
=======================================
  Files         141      141           
  Lines        9146     9146           
=======================================
  Hits         8555     8555           
  Misses        591      591           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a GitHub Actions workflow and a companion script that runs when a PR is converted to draft (or manually). The script paginates comments to avoid duplicates, checks for CHANGES_REQUESTED reviews, supports DRY_RUN, and posts a formatted explainer comment or skips with safe logging.

Changes

Cohort / File(s)	Summary
Bot script .github/scripts/bot-pr-draft-explainer.js	New exported script module.exports = async ({ github, context }). Resolves PR number from payload or env, paginates comments (up to pages) to detect a unique HTML marker to prevent duplicate posts, checks for at least one CHANGES_REQUESTED review (falls back to posting if review lookup fails), supports DRY_RUN, and posts a formatted explainer comment. Handles missing PR data and errors gracefully.
Workflow .github/workflows/bot-pr-draft-explainer.yaml	New workflow triggered on pull_request: types: [converted_to_draft] and workflow_dispatch. Sets permissions and concurrency per PR, uses hardened runner+checkout, and invokes the local bot script via actions/github-script, passing GITHUB_TOKEN, DRY_RUN, and PR_NUMBER.
Changelog CHANGELOG.md	Added entry under .github documenting the new PR draft explainer workflow that comments when PRs are converted to draft after changes are requested.

Sequence Diagram(s)

sequenceDiagram
    participant GHA as GitHub Actions
    participant Script as Bot Script
    participant CommentsAPI as PR Comments API
    participant ReviewsAPI as PR Reviews API

    GHA->>Script: Trigger (converted_to_draft or manual)
    activate Script

    Script->>Script: Resolve PR number & validate payload/env
    Script->>CommentsAPI: List comments (paginated)
    activate CommentsAPI
    CommentsAPI-->>Script: Return comments
    deactivate CommentsAPI

    Script->>Script: Check for duplicate marker
    alt Duplicate found
        Script-->>GHA: Exit (skip posting)
    else No duplicate
        Script->>ReviewsAPI: List PR reviews
        activate ReviewsAPI
        ReviewsAPI-->>Script: Return reviews
        deactivate ReviewsAPI

        Script->>Script: Check for CHANGES_REQUESTED
        alt CHANGES_REQUESTED exists
            Script->>CommentsAPI: Create explanation comment (or simulate in DRY_RUN)
            activate CommentsAPI
            CommentsAPI-->>Script: Comment created
            deactivate CommentsAPI
            Script-->>GHA: Log success
        else No CHANGES_REQUESTED
            Script-->>GHA: Skip posting
        end
    end

    deactivate Script

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add PR draft explainer workflow' clearly and concisely summarizes the main change: adding a new GitHub Actions workflow for PR draft explanations.
Description check	✅ Passed	The description is well-structured and directly related to the changeset, detailing what was added (workflow and bot script), testing performed, and linking to issue #1723.
Linked Issues check	✅ Passed	The PR fully implements all coding requirements from issue #1723: creates the workflow file, implements the bot script with duplicate prevention, CHANGES_REQUESTED review check, dry-run support, and adds changelog entry.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the PR draft explainer workflow from issue #1723; no out-of-scope modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: b1d0cf0b-f2f9-4c7b-9731-4096255aba42

📥 Commits

Reviewing files that changed from the base of the PR and between a9a8789 and f2b1953.

📒 Files selected for processing (3)

• .github/scripts/bot-pr-draft-explainer.js
• .github/workflows/bot-pr-draft-explainer.yaml
• CHANGELOG.md

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0dc19081-d61e-4017-94ca-8eb9cae9211a

📥 Commits

Reviewing files that changed from the base of the PR and between f2b1953 and ff5a25d.

📒 Files selected for processing (1)

• .github/scripts/bot-pr-draft-explainer.js

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

.github/scripts/bot-pr-draft-explainer.js (1)

13-15: 🧹 Nitpick | 🔵 Trivial

Consider parsing manualPRNumber for type safety.

When prNumber comes from pr?.number it's a number, but from process.env.PR_NUMBER it's a string. While GitHub's API coerces strings, explicit parsing catches invalid input early.

♻️ Suggested improvement

 const COMMENT_MARKER = "<!-- pr-draft-explainer -->";
 const DRY_RUN = process.env.DRY_RUN === "true";
-const manualPRNumber = process.env.PR_NUMBER;
+const manualPRNumber = process.env.PR_NUMBER ? parseInt(process.env.PR_NUMBER, 10) : undefined;

Then update validation in main function:

     let prNumber = pr?.number || manualPRNumber;
     const { owner, repo } = context.repo;

-    if (!prNumber) {
+    if (!prNumber || Number.isNaN(prNumber)) {
         console.log("No PR number found in payload or environment. Exiting.");
         return;
     }

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 49e123db-095e-4dca-887e-f499d85958c6

📥 Commits

Reviewing files that changed from the base of the PR and between ff5a25d and 63e9309.

📒 Files selected for processing (1)

• .github/scripts/bot-pr-draft-explainer.js

[github-actions]

Hi, this is WorkflowBot.
Your pull request cannot be merged as it is not passing all our workflow checks.
Please click on each check to review the logs and resolve issues so all checks pass.
To help you:

• DCO signing guide
• Changelog guide
• Merge conflicts guide
• Rebase guide
• Testing guide
• Discord
• Community Calls
  Thank you for contributing!
  From the Hiero Python SDK Team

[parvninama]

@manishdait Thanks for the review! I've addressed the requested changes :)

[github-actions]

Hi, this is MergeConflictBot.
Your pull request cannot be merged because it contains merge conflicts.

Please resolve these conflicts locally and push the changes.

Quick Fix for CHANGELOG.md Conflicts

If your conflict is only in CHANGELOG.md, you can resolve it easily using the GitHub web editor:

1. Click on the "Resolve conflicts" button in the PR
2. Accept both changes (keep both changelog entries)
3. Click "Mark as resolved"
4. Commit the merge

For all other merge conflicts, please read:

• Resolving Merge Conflicts
• Rebasing Guide

Thank you for contributing!

[github-actions]

Hello, this is the OfficeHourBot.

This is a reminder that the Hiero Python SDK Office Hours are scheduled in approximately 4 hours (14:00 UTC).

This session provides an opportunity to ask questions regarding this Pull Request.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here for any changes.

From,
The Python SDK Team