How to write a GitHub issue from a code review

Code reviews often uncover areas of improvement or bugs in a project. Turning these insights into actionable GitHub issues ensures that your team can address them systematically. Whether it’s a minor code refactor or a significant architectural improvement, creating issues directly from code reviews keeps your workflow organized and prevents overlooked feedback. This guide will show you how to write a GitHub issue based on your code review, as well as take a look into how to leverage Graphite's PR inbox for more organized code reviews.

Prerequisites for writing GitHub issues from code reviews

• GitHub repository access: Ensure you have contributor or higher access to create issues.
• Contextual understanding: Reviewers should understand the scope and impact of the feedback they provide.

Steps to write a GitHub issue from your code review

1. Identify actionable feedback during code review

Reviewers should differentiate between minor suggestions and issues requiring follow-up. Use blocking comments for critical issues and nitpicks for minor improvements. For example:

• Blocking: "This function's complexity is too high. Consider refactoring into smaller functions."
• Nitpick: "Add a comment to explain this regex."

In this case, the high complexity is an actionable issue worth logging.

2. Use the Graphite PR inbox for effective tracking

Graphite's PR inbox organizes your reviews into sections like "Needs your review" or "Returned to you". You can review the "Needs your review" section to focus on active PRs and identify unresolved issues.

3. Create a GitHub issue

After identifying actionable feedback:

1. Navigate to the GitHub repository.
2. Go to the "Issues" tab.
3. Click "New Issue" and provide a clear title and description. Follow this structure:

Example issue

Title: Refactor high-complexity function processUserData Description:

During code review, the function processUserData in userService.js was identified as overly complex, exceeding the team's cyclomatic complexity threshold.

Steps to address:

• Break down processUserData into smaller functions.
• Add unit tests for each new function.

References:

PR link: #123 Code snippet:

Terminal

function processUserData(user) {
  // overly complex logic here
}

4. Reference the PR and reviewer feedback

In your issue, link to the relevant PR and reference the reviewer’s feedback. This provides context and ensures that anyone picking up the issue knows its origin.

5. Assign appropriate labels, assignees, and milestones

Organize your issue with metadata to make it actionable:

• Labels: Use tags like refactor, bug, or enhancement.
• Assignees: Assign the issue to a developer with relevant expertise.
• Milestones: Add the issue to a sprint or milestone.

Example with labels

Labels: [refactor], [high priority]
Assignees: @developerName
Milestones: Sprint 34

6. Share the issue with teammates

Leverage Graphite's filtering and sharing features to notify team members. For instance, you can filter PRs tied to unresolved issues and share these insights dynamically with your team.

Automating GitHub issue creation with tools

To speed up the process, you can integrate GitHub APIs or third-party tools. For example, using a GitHub Action, you can automatically generate an issue when a specific label like needs follow-up is applied during a code review.

Example GitHub Action

name: Create Issue from Code Review
on:
  issues:
    types: [labeled]
jobs:
  create-issue:
    runs-on: ubuntu-latest
    steps:
      - name: Generate issue
        uses: actions/create-issue-action@v1
        with:
          title: Refactor high-complexity function
          body: |
            The function `processUserData` exceeds the complexity threshold...

Best practices for creating issues during code reviews

• Be concise but detailed: Avoid vague titles like “Refactor code”. Instead, specify the file or function involved.
• Provide code snippets: Highlight the exact code needing attention to save time during debugging.
• Use tools effectively: Graphite’s PR inbox enhances visibility, helping you stay on top of unresolved feedback.

By following these steps, you can seamlessly turn code review feedback into actionable GitHub issues, ensuring your team remains productive and organized.