[Intermediate]: Expand mentor assignment comment so it actually assigns a mentor

[exploreriii]

🧩 Intermediate Contributors

This issue is intended for contributors who already have some familiarity with the
Hiero Python SDK codebase and contribution workflow.

You should feel comfortable:

• navigating existing source code and examples
• understanding SDK concepts without step-by-step guidance
• following the standard PR workflow without additional onboarding

If this is your very first contribution to the project, we recommend starting with a few
Good First Issues before working on this one.

🐞 Problem Description

We have .github/scripts/bot-mentor-assignment.js

this COMMENTS on a new good first issue starter, that they are assigned a mentor.

To help streamline our SDK, it would be better if the mentor is ASSIGNED to the issue, as well as the comment getting posted

💡 Expected Solution

Edit .github/scripts/bot-mentor-assignment.js ensure a mentor gets assigned, not just commented

🧠 Implementation Notes

Edit .github/scripts/bot-mentor-assignment.js

we first will recognise that this is a qualified new starter that we want to assign a mentor

• immediately add a label 'mentor-duty'
• Assign the mentor second
• post the comment on success

ensure:

const MENTOR_DUTY_LABEL = process.env.MENTOR_DUTY_LABEL || 'mentor-duty';

ADDITIONALLY you'll need to edit:
.github/scripts/bot-gfi-assign-on-comment.js
.github/scripts/bot-beginner-assign-on-comment.js

both these issues should check mentor assignment does not count to their open assignments
i.e. more like this

async function getOpenAssignments({ github, owner, repo, username }) {
    const permissionResp = await github.rest.repos.getCollaboratorPermissionLevel({
        owner,
        repo,
        username,
    });

    const permission = permissionResp.data.permission;

    const issues = await github.paginate(
        github.rest.issues.listForRepo,
        {
            owner,
            repo,
            assignee: username,
            state: 'open',
            per_page: 100,
        }
    );

    return issues.filter(issue => {
        const isPR = !!issue.pull_request;
        if (isPR) return false; // Never count PRs

        const labels = issue.labels?.map(l => l.name) || [];

        if (permission === 'triage' && labels.includes('mentor-duty')) {
            return false; // Mentor work shouldn't count
        }

        return true;
    }).length;
}

This is ranked as an intermediate issue as there are a few bits depending on our triage and mentor logic, so care and tests need to be done

✅ Acceptance Criteria

To merge this issue, the pull request must:

• Fully address the problem described above
• Follow existing project conventions and patterns
• Include tests or example updates where appropriate
• Pass all CI checks
• Include a valid changelog entry
• be a DCO and GPG key signed as git commit -S -s -m "chore: my change" with a GPG key set up

📚 Additional Context or Resources

• SDK Developer Docs
• SDK Developer Training

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Approach

Enhance the mentor assignment bot to actually assign mentors to issues (not just comment), add a 'mentor-duty' label for tracking, and update both GFI and beginner assignment scripts to exclude mentor-duty labeled issues from triage users' open assignment counts.

Observations

The Hiero Python SDK repository uses GitHub Actions with JavaScript bot scripts in .github/scripts/ to manage contributor workflows. The mentor assignment system (bot-mentor-assignment.js) currently only posts welcome comments when new contributors are assigned to Good First Issues—it does not actually assign the mentor to the issue.

Two related scripts (bot-gfi-assign-on-comment.js and bot-beginner-assign-on-comment.js) handle /assign commands and enforce assignment limits via getOpenAssignments() functions that currently count all open issues regardless of label.

All mentors in the roster have triage permission, and the 'mentor-duty' label does not currently exist in the codebase.

Implementation Steps

Phase 1: Enhance Mentor Assignment Script

This phase modifies the core mentor assignment logic to add the mentor-duty label and actually assign the mentor to the issue, following the order specified in the ticket: label first, then assign, then comment.

Task 1: Add Mentor Duty Label Configuration

Add the configurable label constant at the top of the script, following the existing pattern for environment variable configuration.

• Add const MENTOR_DUTY_LABEL = process.env.MENTOR_DUTY_LABEL || 'mentor-duty'; near other configuration constants in .github/scripts/bot-mentor-assignment.js
• Place alongside existing constants like COMMENT_MARKER, MENTOR_TEAM_ALIAS, etc.

Task 2: Implement Label Addition Before Mentor Assignment

After the new contributor validation passes and before any other mentor-related actions, add the mentor-duty label to the issue.

• In .github/scripts/bot-mentor-assignment.js, after the isNewContributor check passes, add logic to apply the label
• Use github.rest.issues.addLabels() with owner, repo, issue_number, and labels array containing MENTOR_DUTY_LABEL
• Wrap in try/catch to handle label addition failures gracefully without blocking subsequent operations
• Respect DRY_RUN mode by logging the intended action instead of executing when dry run is enabled
• Log success/failure appropriately for debugging

Task 3: Implement Mentor Assignment to Issue

After successfully adding the label, assign the selected mentor to the issue as an assignee.

• In .github/scripts/bot-mentor-assignment.js, after label addition, add mentor assignment logic
• Use github.rest.issues.addAssignees() following the existing pattern from bot-gfi-assign-on-comment.js:346-351
• Pass the mentor's GitHub username from the selectMentor() result
• Wrap in try/catch for graceful error handling—label and assignment failures should log warnings but not prevent the comment from being posted
• Respect DRY_RUN mode by logging instead of executing
• Maintain the existing comment posting logic as the final step (only on success of prior operations)

🤖 Prompt for AI agents

Modify the core mentor assignment script
(`.github/scripts/bot-mentor-assignment.js`) to add the mentor-duty label and
actually assign the mentor to the issue, following the sequence: label first,
then assign, then comment.

**Add Configuration Constant:**
- Add `const MENTOR_DUTY_LABEL = process.env.MENTOR_DUTY_LABEL ||
'mentor-duty';` near other configuration constants like `COMMENT_MARKER`,
`MENTOR_TEAM_ALIAS`, etc.

**Implement Label Addition:**
- After the `isNewContributor` check passes and before other mentor-related
actions, add logic to apply the mentor-duty label
- Use `github.rest.issues.addLabels()` with owner, repo, issue_number, and
labels array containing `MENTOR_DUTY_LABEL`
- Wrap in try/catch for graceful error handling
- Respect `DRY_RUN` mode by logging instead of executing
- Log success/failure for debugging

**Implement Mentor Assignment:**
- After label addition, add mentor assignment logic using
`github.rest.issues.addAssignees()`
- Follow the existing pattern from `bot-gfi-assign-on-comment.js:346-351`
- Pass the mentor's GitHub username from the `selectMentor()` result
- Wrap in try/catch—failures should log warnings but not prevent comment posting
- Respect `DRY_RUN` mode
- Maintain existing comment posting logic as the final step (only on success of
prior operations)

Phase 2: Update Assignment Counting Logic

This phase updates both assignment scripts to exclude mentor-duty labeled issues from triage users' open assignment counts, preventing mentorship duties from blocking their ability to take on additional issues.

Task 1: Refactor getOpenAssignments in GFI Script

Update the function to check user permissions and filter out mentor-duty issues for triage users.

• In .github/scripts/bot-gfi-assign-on-comment.js, locate the getOpenAssignments function
• Add a call to github.rest.repos.getCollaboratorPermissionLevel() at the start of the function to get the user's permission level
• Modify the return logic to filter the paginated issues:
  • Exclude items where issue.pull_request exists (these are PRs, not issues)
  • For users with 'triage' permission, also exclude issues that have the 'mentor-duty' label in their labels array
• Extract label names using issue.labels?.map(l => l.name) || [] pattern
• Return the filtered count instead of raw issues.length
• Handle API errors for permission check gracefully (default to counting all issues if permission check fails)

Task 2: Refactor getOpenAssignments in Beginner Script

Apply the same filtering logic to the beginner assignment script for consistency.

• In .github/scripts/bot-beginner-assign-on-comment.js, locate the getOpenAssignments function
• Apply identical changes as Task 2.1: permission check, PR filtering, and mentor-duty label exclusion for triage users
• Ensure the 'mentor-duty' label string is consistent (use literal string since this script doesn't need the env var configuration)
• Match error handling approach from Task 2.1

🤖 Prompt for AI agents

Update both assignment scripts to exclude mentor-duty labeled issues from triage
users' open assignment counts, preventing mentorship duties from blocking their
ability to take on additional issues.

**GFI Script (`bot-gfi-assign-on-comment.js`):**
- Locate the `getOpenAssignments` function
- Add a call to `github.rest.repos.getCollaboratorPermissionLevel()` at the
start to get the user's permission level
- Modify the return logic to filter paginated issues:
  - Exclude items where `issue.pull_request` exists (PRs, not issues)
- For users with 'triage' permission, also exclude issues with the 'mentor-duty'
label
- Extract label names using `issue.labels?.map(l => l.name) || []` pattern
- Return the filtered count instead of raw `issues.length`
- Handle API errors for permission check gracefully (default to counting all
issues if check fails)

**Beginner Script (`bot-beginner-assign-on-comment.js`):**
- Locate the `getOpenAssignments` function
- Apply identical changes: permission check, PR filtering, and mentor-duty label
exclusion for triage users
- Use literal string 'mentor-duty' (this script doesn't need env var
configuration)
- Match error handling approach from GFI script

Phase 3: Documentation and Changelog

Add required changelog entry documenting the new mentor assignment behavior.

Add Changelog Entry

Document the enhancement in the project changelog following the established format.

• Add entry under ## [Unreleased] section in CHANGELOG.md
• Use the Added category for the new label and assignment functionality
• Use the Changed category for the updated assignment counting logic
• Follow the existing entry format: action verb, description, and PR/issue reference in parentheses
• Example entries:
  • "Added mentor assignment and 'mentor-duty' label to Good First Issue mentor workflow (#XXXX)"
  • "Changed assignment counting to exclude mentor-duty issues for triage members (#XXXX)"

🤖 Prompt for AI agents

Document the enhancement in the project changelog following the established
format.

**Update `CHANGELOG.md`:**
- Add entry under `## [Unreleased]` section
- Use the `Added` category for the new label and assignment functionality
- Use the `Changed` category for the updated assignment counting logic
- Follow existing entry format: action verb, description, and PR/issue reference
in parentheses
- Example entries:
- "Added mentor assignment and 'mentor-duty' label to Good First Issue mentor
workflow (`#XXXX`)"
- "Changed assignment counting to exclude mentor-duty issues for triage members
(`#XXXX`)"

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Modify the core mentor assignment script
(`.github/scripts/bot-mentor-assignment.js`) to add the mentor-duty label and
actually assign the mentor to the issue, following the sequence: label first,
then assign, then comment.

**Add Configuration Constant:**
- Add `const MENTOR_DUTY_LABEL = process.env.MENTOR_DUTY_LABEL ||
'mentor-duty';` near other configuration constants like `COMMENT_MARKER`,
`MENTOR_TEAM_ALIAS`, etc.

**Implement Label Addition:**
- After the `isNewContributor` check passes and before other mentor-related
actions, add logic to apply the mentor-duty label
- Use `github.rest.issues.addLabels()` with owner, repo, issue_number, and
labels array containing `MENTOR_DUTY_LABEL`
- Wrap in try/catch for graceful error handling
- Respect `DRY_RUN` mode by logging instead of executing
- Log success/failure for debugging

**Implement Mentor Assignment:**
- After label addition, add mentor assignment logic using
`github.rest.issues.addAssignees()`
- Follow the existing pattern from `bot-gfi-assign-on-comment.js:346-351`
- Pass the mentor's GitHub username from the `selectMentor()` result
- Wrap in try/catch—failures should log warnings but not prevent comment posting
- Respect `DRY_RUN` mode
- Maintain existing comment posting logic as the final step (only on success of
prior operations)
===============================================================================

Task: 2

Update both assignment scripts to exclude mentor-duty labeled issues from triage
users' open assignment counts, preventing mentorship duties from blocking their
ability to take on additional issues.

**GFI Script (`bot-gfi-assign-on-comment.js`):**
- Locate the `getOpenAssignments` function
- Add a call to `github.rest.repos.getCollaboratorPermissionLevel()` at the
start to get the user's permission level
- Modify the return logic to filter paginated issues:
  - Exclude items where `issue.pull_request` exists (PRs, not issues)
- For users with 'triage' permission, also exclude issues with the 'mentor-duty'
label
- Extract label names using `issue.labels?.map(l => l.name) || []` pattern
- Return the filtered count instead of raw `issues.length`
- Handle API errors for permission check gracefully (default to counting all
issues if check fails)

**Beginner Script (`bot-beginner-assign-on-comment.js`):**
- Locate the `getOpenAssignments` function
- Apply identical changes: permission check, PR filtering, and mentor-duty label
exclusion for triage users
- Use literal string 'mentor-duty' (this script doesn't need env var
configuration)
- Match error handling approach from GFI script
===============================================================================

Task: 3

Document the enhancement in the project changelog following the established
format.

**Update `CHANGELOG.md`:**
- Add entry under `## [Unreleased]` section
- Use the `Added` category for the new label and assignment functionality
- Use the `Changed` category for the updated assignment counting logic
- Follow existing entry format: action verb, description, and PR/issue reference
in parentheses
- Example entries:
- "Added mentor assignment and 'mentor-duty' label to Good First Issue mentor
workflow (`#XXXX`)"
- "Changed assignment counting to exclude mentor-duty issues for triage members
(`#XXXX`)"

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[exploreriii]

@ambicuity please ask to get assigned to this issue, we cannot accept PRs from unassigned users

[exploreriii]

@ambicuity outstanding please

[ambicuity]

Hi @exploreriii, I would like to work on this issue. Could you please assign it to me? Thank you!