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

[exploreriii]

🐥 Beginner Friendly

This issue is intended for contributors who have previously completed a Good First Issue in Hiero and are at a beginner level.
We recognize that gaining confidence and building skills are equally important steps in the open-source contributor journey.
The purpose of this issue—and others listed under Find a beginner issue—is to provide a supportive, low-pressure environment where you can learn, practice, and grow your contribution skills with confidence.

👾 Description of the issue

Our current workflow moves a PR to draft status if changes are requested
This works because draft PRs are not ready to be reviewed

However, we don't explain to users why their PR is changed to draft, which can be jarring

💡 Proposed Solution

We can create a workflow that listens for changes from ready to review to draft status, then posts a friendly comment eg

Hi X, we have suggested some changes and have moved your PR to draft status while you apply this feedback.
Please do let us know it is ready for review again by clicking the 'Ready for Review' button or commenting /review
(something better if possible!)

👩‍💻 Implementation Steps

Create a .github/workflows/pr-draft-explainer.yml

Trigger is when a PR is switched from ready to review --> draft AND has changes requested

on:
  pull_request:
    types: [converted_to_draft]

https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows

permissions:
  pull-requests: write

it will need to checkout the

        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1

just the file needed:

        with:
          sparse-checkout: |
            .github/scripts/pr-draft-explainer.js
          sparse-checkout-cone-mode: false

then it should call the logic script

          script: |
            const explain = require('./.github/scripts/pr-draft-explainer.js');
            await explain({ github, context, core });

There are many similar examples in /workflows

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

• it should avoid duplicating

eg

const COMMENT_MARKER = '<!-- pr-draft-explainer -->';

module.exports = async ({ github, context, core }) => {
  const pr = context.payload.pull_request;
  const { owner, repo } = context.repo;

  if (!pr) {
    core.info("No pull request found in payload. Exiting.");
    return;
  }

  const prNumber = pr.number;
  const author = pr.user.login;

  core.info(`PR #${prNumber} was converted to draft. Checking if explanation is needed.`);

  // Check if we've already posted this message before
  const comments = await github.paginate(github.rest.issues.listComments, {
    owner,
    repo,
    issue_number: prNumber,
    per_page: 100,
  });

  const alreadyExplained = comments.some(comment =>
    comment.body?.includes(COMMENT_MARKER)
  );

  if (alreadyExplained) {
    core.info("Draft explanation comment already exists. Skipping.");
    return;
  }

  // Optional: Only post if there is a CHANGES_REQUESTED review
  try {
    const reviews = await github.rest.pulls.listReviews({
      owner,
      repo,
      pull_number: prNumber,
    });

    const hasChangeRequest = reviews.data.some(
      review => review.state === "CHANGES_REQUESTED"
    );

    if (!hasChangeRequest) {
      core.info("No change-request review found. Skipping explanation comment.");
      return;
    }
  } catch (error) {
    core.info(`Review lookup failed (${error.message}). Posting explanation anyway.`);
  }

  const message = `${COMMENT_MARKER}
Hi @${author}! 👋

We’ve suggested a few updates and moved this PR to **draft** while you apply the feedback. This just means it’s temporarily out of the review queue.

### What happens next?
- Make the requested changes ✨  
- When you're ready, click **"Ready for review"** at the top of the PR  
  **or** comment \`/ready\` and we’ll take another look

Thanks again for your contribution — we’re excited to get this merged! 🚀
`;

  await github.rest.issues.createComment({
    owner,
    repo,
    issue_number: prNumber,
    body: message,
  });

  core.info(`Posted draft explanation comment on PR #${prNumber}.`);
};

it should be tested as per docs/sdk_developers/training/testing_forks.md

✅ Acceptance Criteria

• The issue is solved:
  My changes do exactly what the issue asked for.

• I did not add extra changes:
  I did not modify anything that was not mentioned in the issue description.

• Nothing else was broken:
  All existing features still work the same as before.

• All checks pass:
  The automated tests (unit and integration tests) run successfully.

📋 Step-by-Step Contribution Guide

• Assignment: You must be assigned to the issue, comment: /assign in the issue to get assigned see guide
• Fork, Branch and Work on the issue: Create a copy of the repository, create a branch for the issue and solve the problem. For instructions, please read our Contributing guide file. Further help can be found at Set-up Training (including the Windows Setup Guide for Windows users) and Workflow Training.
• DCO and GPG key sign each commit : each commit must be -s and -S signed. An explanation on how to do this is at Signing Guide
• Add a Changelog Entry : your pull request will require a changelog. Read Changelog Entry Guide to learn how.
• Push and Create a Pull Request : Once your issue is resolved, and your commits are signed, and you have a changelog entry, push your changes and create a pull request. Detailed instructions can be found at Submit PR Training, part of Workflow Training.
• You did it 🎉: A maintainer or committer will review your pull request and provide feedback. If approved, we will merge the fix in the main branch. Thanks for being part of the Hiero community as an open-source contributor ❤️

IMPORTANT You will ONLY be assigned to the issue if you comment: /assign
IMPORTANT Your pull request CANNOT BE MERGED until you add a changelog entry AND sign your commits each with git commit -S -s -m "chore: your commit message" with a GPG key setup.

🤖 AI Usage Guidelines

You are welcome to use AI to help you understand and solve this issue.

Because AI tools can sometimes make mistakes, please take care to:

• Only implement what is described in this issue
• Avoid changing anything else in the file
• Be careful when modifying parameters or return statements, as this may affect runtime behavior

If you're unsure, ask your mentor or the maintainers for help — they can provide expert Python SDK guidance and point you to the right examples or methods.

🤔 Additional Information

For more help, we have extensive documentation:

• SDK Developer Docs
• SDK Developer Training

Additionally, we invite you to join our community on our Discord server.

We also invite you to attend each Wednesday, 2pm UTC our Python SDK Office Hour and Community Calls. The Python SDK Office hour is for hands-on-help and the Community Call for general community discussion.

You can also ask for help in a comment below!

[github-actions]

@coderabbitai plan

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch details of issue `#1723` from the hiero-sdk-python repository
gh issue view 1723 --repo hiero-ledger/hiero-sdk-python --json title,body,labels,author,createdAt

Length of output: 9376

---

@github-actions[bot], I'll create a plan for implementing the PR draft explainer workflow.

Task: Create PR Draft Explainer Workflow

This issue requests adding a GitHub Actions workflow that automatically posts a friendly explanation when a PR is moved to draft status after changes are requested. This will help contributors understand why their PR status changed.

Plan Overview:

1. Create the workflow file that triggers on PR converted to draft
2. Create the JavaScript logic file that posts the explanation comment
3. Ensure proper testing as per repository guidelines

';

module.exports = async ({ github, context, core }) => {
const pr = context.payload.pull_request;
const { owner, repo } = context.repo;

if (!pr) {
core.info("No pull request found in payload. Exiting.");
return;
}

const prNumber = pr.number;
const author = pr.user.login;

core.info(PR #${prNumber} was converted to draft. Checking if explanation is needed.);

// Check if we've already posted this message before
const comments = await github.paginate(github.rest.issues.listComments, {
owner,
repo,
issue_number: prNumber,
per_page: 100,
});

const alreadyExplained = comments.some(comment =>
comment.body?.includes(COMMENT_MARKER)
);

if (alreadyExplained) {
core.info("Draft explanation comment already exists. Skipping.");
return;
}

// Optional: Only post if there is a CHANGES_REQUESTED review
try {
const reviews = await github.rest.pulls.listReviews({
owner,
repo,
pull_number: prNumber,
});

const hasChangeRequest = reviews.data.some(
  review => review.state === "CHANGES_REQUESTED"
);

if (!hasChangeRequest) {
  core.info("No change-request review found. Skipping explanation comment.");
  return;
}

} catch (error) {
core.info(Review lookup failed (${error.message}). Posting explanation anyway.);
}

const message = `${COMMENT_MARKER}
Hi @${author}! 👋

We've suggested a few updates and moved this PR to draft while you apply the feedback. This just means it's temporarily out of the review queue.

What happens next?

• Make the requested changes ✨
• When you're ready, click "Ready for review" at the top of the PR
  or comment `/ready` and we'll take another look

Thanks again for your contribution — we're excited to get this merged! 🚀
`;

await github.rest.issues.createComment({
owner,
repo,
issue_number: prNumber,
body: message,
});

core.info(Posted draft explanation comment on PR #${prNumber}.);
};

</requirement> -->

## Testing Instructions

After implementing the changes, the workflow should be tested according to `docs/sdk_developers/training/testing_forks.md`:

1. Test on a forked repository first
2. Create a test PR in your fork
3. Request changes on the test PR
4. Convert the PR to draft status
5. Verify that the friendly explanation comment is posted
6. Convert the PR back and forth again to ensure duplicate comments are not posted

## Acceptance Criteria

✅ Workflow file created at `.github/workflows/pr-draft-explainer.yml`
✅ Logic script created at `.github/scripts/pr-draft-explainer.js`
✅ Workflow triggers only on `converted_to_draft` event
✅ Comment is posted only when changes are requested
✅ Duplicate comments are prevented
✅ Comment includes friendly explanation and clear next steps
✅ All commits are signed with GPG key (`-S`) and DCO (`-s`)
✅ Changelog entry added
✅ Tested in fork before submitting PR

---

💡 Use `@coderabbitai` plan to create a plan for code changes


<!-- <agentComponentType>chat-answer</agentComponentType> -->

<!-- <rawResChunk><answer><details>
<summary>🧩 Analysis chain</summary>

🏁 Script executed:

#!/bin/bash

Fetch details of issue #1723 from the hiero-sdk-python repository

gh issue view 1723 --repo hiero-ledger/hiero-sdk-python --json title,body,labels,author,createdAt

Length of output: 9376

---



</details>

`@github-actions`[bot], I'll create a plan for implementing the PR draft explainer workflow.



## Task: Create PR Draft Explainer Workflow

This issue requests adding a GitHub Actions workflow that automatically posts a friendly explanation when a PR is moved to draft status after changes are requested. This will help contributors understand why their PR status changed.

**Plan Overview:**
1. Create the workflow file that triggers on PR converted to draft
2. Create the JavaScript logic file that posts the explanation comment
3. Ensure proper testing as per repository guidelines

&lt;!-- <requirement>
[requirement create_pr_draft_explainer_1/2 create_workflow_file]
Create the GitHub Actions workflow file `.github/workflows/pr-draft-explainer.yml` that triggers when a PR is converted to draft status.

**File:** `.github/workflows/pr-draft-explainer.yml`

```yaml
name: PR Draft Explainer

on:
  pull_request:
    types: [converted_to_draft]

permissions:
  pull-requests: write

jobs:
  explain:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          sparse-checkout: |
            .github/scripts/pr-draft-explainer.js
          sparse-checkout-cone-mode: false

      - name: Post draft explanation
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
        with:
          script: |
            const explain = require('./.github/scripts/pr-draft-explainer.js');
            await explain({ github, context, core });

-->

<!--
[requirement create_pr_draft_explainer_2/2 create_logic_script]
Create the JavaScript logic file .github/scripts/pr-draft-explainer.js that handles the comment posting logic, checks for duplicate comments, and verifies changes were requested.

File: .github/scripts/pr-draft-explainer.js

const COMMENT_MARKER = '<!-- pr-draft-explainer -->';

module.exports = async ({ github, context, core }) => {
  const pr = context.payload.pull_request;
  const { owner, repo } = context.repo;

  if (!pr) {
    core.info("No pull request found in payload. Exiting.");
    return;
  }

  const prNumber = pr.number;
  const author = pr.user.login;

  core.info(`PR #${prNumber} was converted to draft. Checking if explanation is needed.`);

  // Check if we've already posted this message before
  const comments = await github.paginate(github.rest.issues.listComments, {
    owner,
    repo,
    issue_number: prNumber,
    per_page: 100,
  });

  const alreadyExplained = comments.some(comment =>
    comment.body?.includes(COMMENT_MARKER)
  );

  if (alreadyExplained) {
    core.info("Draft explanation comment already exists. Skipping.");
    return;
  }

  // Optional: Only post if there is a CHANGES_REQUESTED review
  try {
    const reviews = await github.rest.pulls.listReviews({
      owner,
      repo,
      pull_number: prNumber,
    });

    const hasChangeRequest = reviews.data.some(
      review => review.state === "CHANGES_REQUESTED"
    );

    if (!hasChangeRequest) {
      core.info("No change-request review found. Skipping explanation comment.");
      return;
    }
  } catch (error) {
    core.info(`Review lookup failed (${error.message}). Posting explanation anyway.`);
  }

  const message = `${COMMENT_MARKER}
Hi @${author}! 👋

We've suggested a few updates and moved this PR to **draft** while you apply the feedback. This just means it's temporarily out of the review queue.

### What happens next?
- Make the requested changes ✨  
- When you're ready, click **"Ready for review"** at the top of the PR  
  **or** comment \`/ready\` and we'll take another look

Thanks again for your contribution — we're excited to get this merged! 🚀
`;

  await github.rest.issues.createComment({
    owner,
    repo,
    issue_number: prNumber,
    body: message,
  });

  core.info(`Posted draft explanation comment on PR #${prNumber}.`);
};

-->

Testing Instructions

After implementing the changes, the workflow should be tested according to docs/sdk_developers/training/testing_forks.md:

1. Test on a forked repository first
2. Create a test PR in your fork
3. Request changes on the test PR
4. Convert the PR to draft status
5. Verify that the friendly explanation comment is posted
6. Convert the PR back and forth again to ensure duplicate comments are not posted

Acceptance Criteria

✅ Workflow file created at .github/workflows/pr-draft-explainer.yml
✅ Logic script created at .github/scripts/pr-draft-explainer.js
✅ Workflow triggers only on converted_to_draft event
✅ Comment is posted only when changes are requested
✅ Duplicate comments are prevented
✅ Comment includes friendly explanation and clear next steps
✅ All commits are signed with GPG key (-S) and DCO (-s)
✅ Changelog entry added
✅ Tested in fork before submitting PR

---

💡 Use @coderabbitai plan to create a plan for code changes

-->

[Subhrasameerdash]

/assign

[github-actions]

👋 Hi @Subhrasameerdash, you already have 2 open assignments. Please finish one before requesting another.

[exploreriii]

Hi @Subhrasameerdash assigned, sorry for the delay at reviewing your PR. Please also check your other outstanding one 👍
Thanks again, happy to see you here

[Subhrasameerdash]

Hii @exploreriii i have created the files required. Are there any tests that I should perform before pushing the changes

[github-actions]

Hi @Subhrasameerdash 👋

This issue has been assigned but no pull request has been created yet.
Are you still planning on working on it?
If you are, please create a draft PR linked to this issue or comment /working to let us know.
If you’re no longer able to work on this issue, you can comment /unassign to release it.

From the Python SDK Team

[Subhrasameerdash]

/working

[Subhrasameerdash]

Hii @exploreriii i have created the files required. Are there any tests that I should perform before pushing the changes

Any update @exploreriii