Create PR - Automated Pull Request Creation

Automatically create high-quality Pull Requests using GitHub MCP tools, following conventional commit specifications.

When to Use

Trigger when user requests PR creation, for example:

•"Create a PR"
•"Help me create a pull request"
•"I finished the refactoring work, can you create a PR?"
•"Create PR for current branch"

Prerequisites:

•Code changes are committed to a git branch
•Current branch is not the default branch (main/master)
•Branch is pushed to remote repository (or needs to be pushed before creating PR)

Workflow

Step 1: Branch Detection and Validation

Use Bash tool to check current git status:

bash

# Get current branch
git branch --show-current

# Check for unpushed commits
git status -sb

# Check differences from base branch
git log origin/main..HEAD --oneline

Validation checklist:

•Current branch is not main/master
•Branch has unmerged commits
•Branch is pushed to remote (if not, push first)

Step 2: Gather PR Information

Use MCP GitHub tools to fetch commit history:

bash

# Use MCP tool to get commits for current branch
mcp__github__list_commits owner=<owner> repo=<repo> sha=<current_branch>

# Or use git command to get complete diff and commit info
git log origin/main..HEAD --format="%h %s%n%b"
git diff origin/main...HEAD --stat

Extract information:

•Extract PR title and description from commit messages
•Identify target base branch (usually main or develop)
•Collect file change statistics
•Find related issue references (e.g., "fix #123")

Step 3: Generate PR Title and Description

Title format (strictly follow conventional commit):

code

<type>(<scope>): <summary>

•Type: feat, fix, perf, test, docs, refactor, build, ci, chore, revert
•Scope (optional): e.g., core, API, output, config
•
Summary rules:
- •All content MUST be written in English (including PR title and description)
- •Must start with a lowercase letter
- •Use imperative present tense ("add" not "added")
- •Must not end with a period
- •For breaking changes, add ! before the colon
- •To exclude from changelog, add (no-changelog) suffix

Validation regex:

code

^(feat|fix|perf|test|docs|refactor|build|ci|chore|revert)(\([a-zA-Z0-9 ]+( Node)?\))?!?: [a-z].+[^.]$

Description template (Paper Tracker format):

markdown

## Summary

<1-2 paragraph overview of what this PR does and why>

**Key changes (if applicable):**
- <Key change 1>
- <Key change 2>
- <Key change 3>

### Changes

<Detailed changes, organized by module/component if complex>

- **Module/Component Name** (if multiple modules affected)
  - <Specific change 1>
  - <Specific change 2>
- <Simple change 1>
- <Simple change 2>

## Breaking Changes

<Description of breaking changes, if any. Otherwise omit this section>

## Testing

<Testing approach>
- Tests performed: <description>
OR
- Not run (not requested)
OR
- Not run (docs-only changes)

## Related Issues

<Issue references like "Closes #123" or "N/A">

### Notes

<Optional additional context, caveats, or follow-up items>

Step 4: Create Pull Request

Use MCP GitHub tool to create PR:

bash

mcp__github__create_pull_request \
  owner=<owner> \
  repo=<repo> \
  title="<conventional_commit_title>" \
  head=<current_branch> \
  base=<base_branch> \
  body="<pr_description>"

Optional parameters:

•draft=true - Create draft PR
•maintainer_can_modify=true - Allow maintainer edits

Step 5: Confirm and Report

After successful creation, report to user:

•PR number and URL
•PR title and target branch
•Number of changed files and statistics

Title Format Examples

Good examples:

•feat(core): add config override support
•fix(output): fix markdown rendering in tables
•docs: update environment variables guide
•refactor(API)!: change query parameter structure
•test(core): add tests for deduplication logic
•chore: update dependencies (no-changelog)

Bad examples (avoid):

•feat: Add feature - Summary should start with lowercase
•update code - Missing type
•fix(core): fixed bug. - Past tense and ends with period
•feature: add support - Wrong type (should be feat)

Project-Specific Conventions

For Paper Tracker project:

Common scopes:

•core - Core logic (query, deduplication, etc.)
•llm - LLM integration and services
•output - Output formatting and rendering
•config - Configuration system
•API - API interaction
•cli - Command line interface
•database - Database schema and storage

PR Description Guidelines:

•Summary section: Provide 1-2 paragraphs explaining what and why
•Changes section: List specific changes, group by module for complex PRs
•Breaking Changes: Only include if there are actual breaking changes
•
Testing: Be explicit about test status:
- •Describe tests run, OR
- •State "Not run (not requested)", OR
- •State "Not run (docs-only changes)"
•Related Issues: Use "N/A" if no related issues

Reference recent commits:

bash

# View project commit history to understand style
git log --oneline -n 10

Error Handling

Common issues and solutions:

•
Branch not pushed:
bash
```
git push -u origin <branch_name>
```
•
No unique commits:
- •Inform user that current branch is same as base branch
- •Suggest making code changes and committing first
•
MCP tool failure:
- •Provide clear error messages
- •Suggest checking network connection or GitHub authentication
•
Title format validation failure:
- •Display validation errors
- •Provide correct example format
- •Ask user to confirm modified title

Best Practices

•
Auto-detect project conventions:
- •Look for .github/pull_request_template.md
- •If template exists, use its structure
•
Extract issue references:
- •Find fix #123, closes #456 etc. in commit messages
- •Automatically add to "Related Issue" section of PR description
•
Branch naming hints:
- •If type can be inferred from branch name (e.g., feature/xxx, fix/xxx), prioritize it
- •Cross-validate type consistency with commit messages
•
Interactive confirmation:
- •Show preview after generating PR info
- •Ask user if modifications are needed
- •Create PR after confirmation

Usage Examples

Scenario 1: Feature PR

code

User: "Create a PR"
Assistant: Detected current branch feature/markdown-export, creating PR based on 5 commits
          Title: feat(output): add markdown export functionality

          Description preview:
          ## Summary

          Adds markdown export functionality to Paper Tracker, allowing users to export
          paper search results in a customizable markdown format.

          ### Changes
          - Add markdown renderer with template support
          - Add configuration for markdown output
          - Update documentation

          ## Testing
          - Manual testing with sample data

          ## Related Issues
          N/A

          Confirm creation? (use AskUserQuestion tool)

Scenario 2: Refactoring with no changelog

code

User: "Create PR for config nesting refactor"
Assistant: Title: refactor(core): nest LLM config (no-changelog)

          This will be excluded from changelog due to (no-changelog) marker.

Scenario 3: Breaking change

code

User: "Create a PR for this API refactoring"
Assistant: Detected breaking changes in configuration schema
          Title: refactor(config)!: change output format structure

          Description will include:
          ## Breaking Changes
          - Configuration field `output.format` renamed to `output.formats`
          - Field now accepts a list instead of single value

Important Notes

•❌ Don't guess remote repository info, always verify
•❌ Don't assume branch is pushed before creating PR
•✅ Ensure all commits are pushed
•✅ Maintain context awareness of project-specific conventions
•✅ Provide clear error messages and recovery suggestions
•✅ Generated PR description should include sufficient context