Implement "UnravelDocs Claim" GitHub Bot for Issue Assignment

[aniebietafia]

Feature: Implement "UnravelDocs Claim" GitHub Bot for Issue Assignment

Is your feature request related to a problem? Please describe.
Currently, assigning issues labeled good-first-issue or help-wanted to contributors is a manual process. This can lead to delays in contributors picking up tasks and requires maintainer intervention for a relatively simple action. There's also no automated way to guide contributors on which issues are eligible for self-assignment via a simple command.

Describe the solution you'd like
We propose building a GitHub bot, tentatively named "UnravelDocs Claim Bot," that can be installed in our GitHub organization. This bot will monitor issue comments for a specific trigger phrase.

1. When a user comments 'unraveldocs claim' (case-insensitive) on an issue:
   • If the issue has the label good-first-issue OR help-wanted (or both), the bot should automatically assign the issue to the user who made the comment.
   • If the issue does NOT have either the good-first-issue or help-wanted label, the bot should post a comment on the issue, tagging the user (e.g., @username) and informing them: "Sorry, only issues labeled with good-first-issue or help-wanted can be claimed using this command."

User Stories / Actor Goals:

• As a Contributor, I want to easily claim an available good-first-issue or help-wanted issue by typing a simple comment ('unraveldocs claim') so that I can quickly signal my intent to work on it and have it assigned to me.
• As a Contributor, if I attempt to claim an issue that is not designated as good-first-issue or help-wanted, I want to receive clear feedback from the bot explaining why it cannot be claimed, so I understand the process.
• As a Maintainer, I want the assignment of designated beginner-friendly issues to be automated so that I can reduce manual intervention and allow contributors to self-serve more effectively.
• As an Organization Administrator, I want to install this bot across repositories in my organization to streamline the contribution workflow for specific types of issues.

Acceptance Criteria:

1. Bot Installation: The bot can be installed as a GitHub App within the organization, targeting all or selected repositories.
2. Comment Trigger: The bot listens for new issue comments in repositories where it is active.
3. Successful Claim Logic:
   • If an issue comment's exact body (case-insensitive) is 'unraveldocs claim'.
   • AND the issue has the label good-first-issue OR the label help-wanted (or both).
   • THEN the bot successfully assigns the issue to the GitHub user who authored the comment.
   • (Optional) The bot may post a confirmation comment (e.g., "Issue assigned to @username!").
4. Failed Claim Logic (Incorrect Labels):
   • If an issue comment's exact body (case-insensitive) is 'unraveldocs claim'.
   • AND the issue does NOT have the good-first-issue label AND does NOT have the help-wanted label.
   • THEN the bot posts a comment on the issue: "@<commenter_username> Sorry, only issues labeled with good-first-issue or help-wanted can be claimed using this command."
   • The issue remains unassigned (or retains its current assignee if already assigned by a human).
5. No Action: The bot takes no action if the comment text does not match 'unraveldocs claim'.
6. Permissions: The bot operates with the minimum necessary permissions (e.g., read issues, read/write comments, write assignments).
7. Idempotency (Consideration): If a user tries to claim an issue already assigned to them by the bot, the bot should ideally not error or take redundant actions. (GitHub's assignment API is generally idempotent for assigning the same user).
8. Error Handling: The bot should have basic error handling and logging for unexpected issues (e.g., API failures).

Proposed Technical Details (High-Level):

• Implementation Strategy: A GitHub App is the recommended approach. This allows for fine-grained permissions and event-driven interactions.
  • Frameworks like Probot (Node.js) are common for GitHub Apps.
  • Alternatively, a custom application (e.g., in Java using a GitHub API client library like org.kohsuke:github-api) that listens to webhooks.
• GitHub App Configuration:
  • Permissions:
    • Issues: Read & Write (to read labels, assign users).
    • Issue comments: Read & Write (to read comments, post replies).
    • Metadata: Read-only (standard).
  • Event Subscriptions:
    • issue_comment (on created action).
• Core Logic:
  1. Receive webhook event for issue_comment.created.
  2. Extract comment body, commenter's GitHub username, issue details (ID, labels, repository).
  3. Normalize comment body (e.g., to lowercase, trim whitespace) and check if it matches 'unraveldocs claim'.
  4. If it matches, fetch the issue's current labels using the GitHub API.
  5. Check if good-first-issue or help-wanted is present in the labels.
  6. Based on the label check, use the GitHub API to either:
     • Assign the issue to the commenter.
     • Post the informational comment.
• Authentication: The bot will authenticate with GitHub using the GitHub App's installation token.
• Deployment: The bot will need to be hosted on a server or serverless platform capable of receiving webhooks from GitHub (e.g., AWS Lambda, Google Cloud Functions, Heroku, a dedicated server).

Tasks:

• Phase 1: Setup & Basic Interaction
  • Research and decide on the specific technology stack/framework for the GitHub App (e.g., Probot, Java with GitHub API library).
  • Create a new GitHub App in the organization settings.
  • Configure required permissions and subscribe to the issue_comment webhook.
  • Implement the basic webhook listener that receives and logs comment events.
  • Securely manage GitHub App credentials (App ID, private key, webhook secret).
• Phase 2: Core Logic Implementation
  • Implement logic to parse the comment content and identify the 'unraveldocs claim' command (case-insensitive).
  • Implement logic to fetch issue labels using the GitHub API.
  • Implement the conditional logic:
    • If labels are correct: call GitHub API to assign the issue to the commenter.
    • If labels are incorrect: call GitHub API to post the predefined informational comment, mentioning the commenter.
• Phase 3: Refinements & Testing
  • Add robust error handling for API calls and unexpected scenarios.
  • Implement server-side logging for requests, actions, and errors.
  • Write unit tests for individual logic components (comment parsing, label checking).
  • Conduct integration testing by installing the bot on a test repository and simulating user comments.
  • (Optional) Implement a confirmation message upon successful assignment.
• Phase 4: Deployment & Documentation
  • Choose and configure a hosting environment for the bot.
  • Deploy the bot application.
  • Create documentation for maintainers on how the bot works, its configuration, and how to install/manage it.
  • Announce the bot's availability to contributors.

Open Questions/Considerations:

• Command Case Sensitivity: Confirm if 'unraveldocs claim' should be strictly case-sensitive or case-insensitive (recommendation: case-insensitive for user-friendliness).
• Label Name Exactness: Are the label names good-first-issue and help-wanted exact and fixed, or could they vary (e.g., good first issue)? (Assumption: exact match for now).
• Handling Already Assigned Issues:
  • If an issue has the correct labels but is already assigned to someone else, should the bot override the assignment? (Current proposal: yes, it will assign to the commenter).
  • If an issue is already assigned to the commenter, should the bot do anything? (Current proposal: GitHub API will likely just succeed without change; bot could add a check to avoid redundant API calls/comments).
• Un-claiming: Is an 'unraveldocs unclaim' feature desired in the future? (Out of scope for this initial implementation).
• Rate Limiting: Ensure the bot's interactions with the GitHub API are mindful of rate limits, especially if many comments are made quickly. (GitHub Apps generally have higher rate limits).
• Bot Username/Avatar: Decide on a name and avatar for the bot's GitHub account if it's a dedicated app.
• Configuration: For the initial version, the command phrase and labels can be hardcoded. Should these be configurable per-repository or globally in the future?
• Bot reacting to its own comments: Ensure the bot doesn't get into a loop by reacting to its own informational or confirmation comments. (Usually handled by checking the comment author).

This detailed issue should provide a good starting point for development.