majiayu000 PR Workflow Skill
This skill provides comprehensive guidance for creating, managing, and merging pull requests with Jira integration, following industry best practices for code review, deployment safety, and team collaboration.
Table of Contents
- Branch Naming Conventions
- Commit Message Standards
- PR Title and Description
- PR Templates
- Review Process
- Merge Strategies
- Jira Integration
- Deployment Notes
- Common Workflows
- Troubleshooting
Branch Naming Conventions
Standard Format
<type>/<jira-key>-<short-description>
Branch Types
| Type | Purpose | Example |
|---|---|---|
feature |
New features | feature/PROJ-123-user-authentication |
bugfix |
Bug fixes | bugfix/PROJ-456-login-error |
hotfix |
Urgent production fixes | hotfix/PROJ-789-payment-failure |
refactor |
Code refactoring | refactor/PROJ-234-database-queries |
docs |
Documentation only | docs/PROJ-567-api-documentation |
test |
Adding/updating tests | test/PROJ-890-integration-tests |
chore |
Maintenance tasks | chore/PROJ-345-dependency-update |
perf |
Performance improvements | perf/PROJ-678-query-optimization |
Naming Best Practices
- Use lowercase with hyphens
- Include Jira ticket key
- Keep description short but meaningful (max 50 chars)
- Use present tense verbs
- Avoid special characters except
-and/
Examples
# Good
feature/LOBBI-1234-member-dashboard
bugfix/LOBBI-5678-email-validation
hotfix/LOBBI-9012-critical-auth-bug
# Bad
feature/add_new_feature
LOBBI-1234
my-branch
fix-bug-in-production
Commit Message Standards
Format
<type>(<scope>): <subject>
<body>
<footer>
Types
feat: New featurefix: Bug fixdocs: Documentation changesstyle: Code style changes (formatting, no logic change)refactor: Code refactoringperf: Performance improvementstest: Adding or updating testschore: Maintenance tasksbuild: Build system changesci: CI/CD changesrevert: Reverting previous commits
Subject Line Rules
- Start with lowercase
- No period at the end
- Use imperative mood ("add" not "added")
- Max 50 characters
- Include Jira key if not in branch name
Body Guidelines
- Wrap at 72 characters
- Explain what and why, not how
- Use bullet points for multiple changes
- Reference related issues
Footer
- Breaking changes:
BREAKING CHANGE: description - Closes issues:
Closes PROJ-123 - References:
Refs PROJ-456, PROJ-789
Examples
# Simple commit
feat(auth): add OAuth2 login support
# With body
fix(api): resolve race condition in user creation
The user creation endpoint could create duplicate users when
called simultaneously. Added database-level unique constraint
and proper error handling.
Closes LOBBI-5678
# Breaking change
feat(api): update authentication flow
BREAKING CHANGE: Authentication now requires API version header.
Clients must include 'X-API-Version: 2.0' in all requests.
Refs LOBBI-1234
# Multiple changes
refactor(database): optimize query performance
- Add indexes to frequently queried columns
- Use eager loading for related entities
- Implement query result caching
- Remove N+1 query patterns
Performance improved by 60% in testing.
Closes LOBBI-3456
PR Title and Description
Title Format
[JIRA-KEY] Type: Brief description
Title Examples
[LOBBI-1234] Feature: Add member dashboard with activity feed
[LOBBI-5678] Fix: Resolve email validation error on signup
[LOBBI-9012] Hotfix: Critical authentication bug in production
[LOBBI-3456] Refactor: Optimize database query performance
[LOBBI-7890] Docs: Update API documentation for v2.0
Description Template
Use this template for all PRs:
## Summary
[Brief overview of changes - 2-3 sentences]
## Jira Ticket
- **Issue:** [PROJ-123](https://your-jira.atlassian.net/browse/PROJ-123)
- **Type:** Feature | Bug Fix | Hotfix | Refactor | Documentation
- **Priority:** Critical | High | Medium | Low
## Changes Made
- List key changes
- Use bullet points
- Be specific and concise
## Technical Details
### Architecture Changes
- Describe any architectural decisions
- Explain design patterns used
### Database Changes
- Schema migrations
- New tables/columns
- Index additions
### API Changes
- New endpoints
- Modified endpoints
- Breaking changes
## Testing
### Test Coverage
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] E2E tests added/updated
- [ ] Manual testing completed
### Test Instructions
1. Step-by-step instructions for reviewers
2. Include test data or scenarios
3. Expected outcomes
### Test Results
- Coverage: XX%
- All tests passing: Yes/No
- Performance benchmarks: [if applicable]
## Screenshots/Videos
[If UI changes, include before/after screenshots or demo video]
## Deployment Notes
### Risk Assessment
- **Risk Level:** Low | Medium | High | Critical
- **Rollback Plan:** [Describe rollback procedure]
### Prerequisites
- [ ] Database migrations ready
- [ ] Environment variables configured
- [ ] Feature flags set
- [ ] Dependencies updated
### Migration Steps
1. Run migrations: `npm run migrate:up`
2. Deploy application
3. Verify health checks
4. Enable feature flag (if applicable)
### Rollback Procedure
1. Disable feature flag
2. Revert deployment
3. Run down migration: `npm run migrate:down`
## Dependencies
- Related PRs: #123, #456
- Blocked by: #789
- Blocks: #234
## Checklist
- [ ] Code follows project style guide
- [ ] Self-review completed
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No console.log or debug code
- [ ] No commented-out code
- [ ] Environment variables documented
- [ ] CHANGELOG.md updated
- [ ] Breaking changes documented
- [ ] Jira ticket updated
## Additional Notes
[Any other context, concerns, or discussion points]
PR Templates
Feature PR Template
## Feature Summary
[What feature is being added and why]
## Jira Ticket
- **Issue:** [PROJ-123](https://jira.example.com/browse/PROJ-123)
- **Epic:** [PROJ-100](https://jira.example.com/browse/PROJ-100)
## User Story
As a [user type],
I want [goal],
So that [benefit].
## Implementation Details
### New Components
- Component A: Purpose and functionality
- Component B: Purpose and functionality
### Modified Components
- Component C: What changed and why
### New Dependencies
- package-name@version: Why it's needed
## API Changes
### New Endpoints
POST /api/v1/resource GET /api/v1/resource/:id PUT /api/v1/resource/:id DELETE /api/v1/resource/:id
### Request/Response Examples
```json
// POST /api/v1/resource
{
"name": "Example",
"type": "demo"
}
// Response
{
"id": "123",
"name": "Example",
"type": "demo",
"created_at": "2025-12-17T10:00:00Z"
}
Testing Strategy
- Unit tests for business logic
- Integration tests for API endpoints
- E2E tests for user flows
- Performance testing completed
- Security review completed
Feature Flags
- Flag name:
enable_new_feature - Default:
false - Rollout plan: Gradual release to 10%, 50%, 100%
Documentation
- API documentation updated
- User guide updated
- Admin guide updated (if applicable)
- Technical design document linked
Deployment
- Target Environment: Production
- Deployment Window: [Date/Time]
- Monitoring Plan: [Metrics to watch]
### Bugfix PR Template
```markdown
## Bug Description
[What was broken and how it manifested]
## Jira Ticket
- **Issue:** [PROJ-456](https://jira.example.com/browse/PROJ-456)
- **Severity:** Critical | High | Medium | Low
## Root Cause
[Technical explanation of what caused the bug]
## Solution
[How the bug was fixed]
## Code Changes
### Files Modified
- `src/path/to/file.ts`: Fixed [specific issue]
- `tests/path/to/test.ts`: Added regression test
### Before (Problematic Code)
```javascript
// Code that caused the issue
function buggyFunction() {
// problematic logic
}
After (Fixed Code)
// Fixed code
function fixedFunction() {
// corrected logic
}
Testing
Regression Test
describe('bugfix PROJ-456', () => {
it('should handle edge case correctly', () => {
// Test that prevents regression
});
});
Manual Testing Steps
- Navigate to [page/endpoint]
- Perform [action]
- Verify [expected behavior]
Impact Analysis
- Users Affected: [Number/Percentage]
- Environments Affected: Production | Staging | Development
- Data Integrity: No impact | Requires data migration
Verification
- Bug reproduced in development
- Fix verified in development
- Regression test added
- No side effects identified
- Tested in staging
### Hotfix PR Template
```markdown
## HOTFIX - URGENT
## Critical Issue
[Clear description of the production issue]
## Jira Ticket
- **Issue:** [PROJ-789](https://jira.example.com/browse/PROJ-789)
- **Severity:** CRITICAL
- **Incident Report:** [Link to incident]
## Impact
- **Users Affected:** [Estimate]
- **Business Impact:** [Revenue, reputation, compliance]
- **Started:** [Timestamp]
- **Duration:** [How long issue has existed]
## Root Cause
[Quick analysis of what went wrong]
## Immediate Fix
[What this PR does to stop the bleeding]
## Long-term Solution
[Follow-up work needed - create Jira tickets]
## Fast-Track Approval
- [ ] Tested in staging replica
- [ ] Rollback plan ready
- [ ] On-call team notified
- [ ] Monitoring alerts configured
## Deployment
- **Deploy ASAP:** YES
- **Requires Downtime:** Yes/No
- **Rollback Time:** [Estimate]
## Post-Deployment
- [ ] Verify fix in production
- [ ] Monitor for 30 minutes
- [ ] Update incident report
- [ ] Schedule post-mortem
Review Process
Requesting Reviews
Reviewer Selection
Code Owner (Required)
- Automatically assigned via CODEOWNERS
- Must approve before merge
Subject Matter Expert (Optional)
- For complex technical areas
- Security changes
- Performance-critical code
Team Lead (For Major Changes)
- Architectural decisions
- Breaking changes
- Cross-team impact
Review Labels
| Label | Purpose | When to Use |
|---|---|---|
needs-review |
Awaiting initial review | When PR is ready |
needs-changes |
Changes requested | After review feedback |
approved |
Ready to merge | All reviews approved |
security-review |
Requires security check | Auth, permissions, data handling |
breaking-change |
Contains breaking changes | API changes, deprecations |
hotfix |
Urgent production fix | Critical issues |
wip |
Work in progress | Not ready for review |
size/small |
< 100 lines changed | Auto-applied |
size/medium |
100-500 lines | Auto-applied |
size/large |
> 500 lines | Auto-applied, consider splitting |
Review Checklist
For Reviewers
## Code Quality
- [ ] Code is readable and maintainable
- [ ] Follows project style guide
- [ ] No code smells or anti-patterns
- [ ] DRY principle followed
- [ ] SOLID principles applied
## Functionality
- [ ] Changes match PR description
- [ ] Edge cases handled
- [ ] Error handling appropriate
- [ ] Input validation present
- [ ] No hardcoded values
## Testing
- [ ] Tests are comprehensive
- [ ] Tests are readable
- [ ] Coverage is adequate
- [ ] Tests actually test the right things
- [ ] No flaky tests
## Security
- [ ] No sensitive data exposed
- [ ] Authentication/authorization correct
- [ ] Input sanitization present
- [ ] SQL injection prevented
- [ ] XSS prevention in place
## Performance
- [ ] No obvious performance issues
- [ ] Database queries optimized
- [ ] Proper indexing used
- [ ] No N+1 queries
- [ ] Caching considered
## Documentation
- [ ] Code comments where needed
- [ ] API documentation updated
- [ ] README updated if needed
- [ ] CHANGELOG updated
- [ ] Breaking changes documented
Merge Requirements
Before merging, ensure:
Status Checks Pass
- All CI/CD pipelines green
- Tests passing
- Linting passing
- Security scans clean
Approvals Met
- Required reviewers approved
- No pending change requests
- Conversations resolved
Branch Up-to-Date
- Rebased on latest main/master
- Merge conflicts resolved
- No divergent changes
Documentation Complete
- CHANGELOG updated
- Jira ticket linked
- Breaking changes noted
Merge Strategies
Squash and Merge (Recommended for Most PRs)
When to Use:
- Feature branches
- Bug fixes
- Multiple WIP commits
Benefits:
- Clean, linear history
- Single commit per feature
- Easy to revert
Process:
# GitHub will squash automatically, or manually:
git checkout main
git merge --squash feature/PROJ-123-new-feature
git commit -m "feat: add new feature [PROJ-123]"
git push origin main
Merge Commit (For Complex Features)
When to Use:
- Long-lived feature branches
- Multiple contributors
- Want to preserve commit history
Benefits:
- Preserves all commits
- Shows collaboration history
- Clear feature boundaries
Process:
git checkout main
git merge --no-ff feature/PROJ-123-new-feature
git push origin main
Rebase and Merge (For Clean History)
When to Use:
- Small, focused PRs
- Already clean commit history
- Linear history preference
Benefits:
- No merge commits
- Clean linear history
- Each commit is meaningful
Process:
git checkout feature/PROJ-123-new-feature
git rebase main
git push --force-with-lease origin feature/PROJ-123-new-feature
# Then merge via GitHub
Strategy Decision Matrix
| Scenario | Strategy | Reason |
|---|---|---|
| Feature with multiple WIP commits | Squash | Clean up history |
| Hotfix (single commit) | Rebase | Keep linear |
| Large feature (team effort) | Merge Commit | Preserve history |
| Bug fix (2-3 commits) | Squash | Simplify |
| Refactoring (many logical steps) | Merge Commit | Show progression |
Jira Integration
Linking PRs to Jira Issues
Automatic Linking
Include Jira key in:
- Branch name:
feature/PROJ-123-description - PR title:
[PROJ-123] Add new feature - Commit messages:
feat: add feature (PROJ-123)
Manual Linking
In PR description:
## Jira Ticket
- **Issue:** [PROJ-123](https://jira.example.com/browse/PROJ-123)
- **Type:** Feature
- **Priority:** High
Closes PROJ-123
Jira Status Transitions
PRs should trigger automatic status updates:
| PR Event | Jira Status Transition |
|---|---|
| PR opened | To Do → In Progress |
| PR ready for review | In Progress → In Review |
| Changes requested | In Review → In Progress |
| PR approved | In Review → Ready for Merge |
| PR merged | Ready for Merge → Done |
| PR closed (not merged) | Any → Cancelled |
Jira Comment Updates
Automatically post to Jira:
Pull Request opened: [PR #123](https://github.com/org/repo/pull/123)
**Title:** [PROJ-123] Add new feature
**Author:** @developer
**Status:** Ready for Review
**Files Changed:** 15
**Lines Added:** +250, Removed: -100
[View Pull Request](https://github.com/org/repo/pull/123)
Deployment Notes
Risk Assessment Template
## Risk Assessment
### Risk Level: [Low | Medium | High | Critical]
### Risk Factors
- [ ] Database schema changes
- [ ] API breaking changes
- [ ] Third-party integration changes
- [ ] Authentication/authorization changes
- [ ] Performance-critical code modified
- [ ] High-traffic endpoints affected
- [ ] Data migration required
### Impact Analysis
- **User Impact:** [Describe who is affected]
- **System Impact:** [Services/components affected]
- **Data Impact:** [Any data modifications]
- **Downtime Required:** Yes/No - [Duration]
### Mitigation Strategies
1. [Strategy to reduce risk]
2. [Backup plan]
3. [Monitoring approach]
Rollback Procedures
Standard Rollback
## Rollback Procedure
### Triggers
- Critical bug discovered
- Performance degradation > 20%
- User-reported issues spike
- Health checks failing
### Steps
1. **Immediate Actions** (0-5 minutes)
- Alert on-call team
- Document issue in incident channel
- Prepare rollback command
2. **Execute Rollback** (5-10 minutes)
```bash
# Kubernetes
kubectl rollout undo deployment/app-name -n namespace
# Helm
helm rollback release-name -n namespace
# Vercel
vercel rollback [deployment-url]
Verify Rollback (10-15 minutes)
- Check health endpoints
- Verify user traffic
- Monitor error rates
- Test critical flows
Database Rollback (if needed)
# Run down migration npm run migrate:down # or npx prisma migrate reset --to-migration [previous-migration]Post-Rollback (15-30 minutes)
- Update Jira ticket
- Notify stakeholders
- Schedule post-mortem
- Create fix plan
### Feature Flags
```markdown
## Feature Flag Strategy
### Flag Configuration
```yaml
feature_flags:
new_dashboard:
enabled: false
rollout:
- percentage: 10
start_date: 2025-12-17
- percentage: 50
start_date: 2025-12-20
- percentage: 100
start_date: 2025-12-24
kill_switch: true
Implementation
// Using LaunchDarkly, Split.io, or custom solution
if (featureFlags.isEnabled('new_dashboard', userId)) {
return renderNewDashboard();
} else {
return renderOldDashboard();
}
Rollout Plan
10% - Internal Users (Day 1-3)
- Monitor closely
- Gather feedback
- Fix critical issues
50% - Beta Users (Day 4-7)
- Broader testing
- Performance validation
- UX feedback
100% - All Users (Day 8+)
- Full rollout
- Remove old code after 30 days
### Migration Steps
```markdown
## Database Migration
### Schema Changes
```sql
-- Migration Up (20251217_add_user_preferences.sql)
CREATE TABLE user_preferences (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
preferences JSONB NOT NULL DEFAULT '{}',
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_user_preferences_user_id ON user_preferences(user_id);
-- Migration Down
DROP TABLE IF EXISTS user_preferences;
Deployment Steps
Pre-deployment (30 minutes before)
# Backup database pg_dump -h host -U user -d database > backup_$(date +%Y%m%d_%H%M%S).sqlDeployment Window
# 1. Run migrations npm run migrate:up # 2. Deploy application kubectl set image deployment/app app=org/app:v2.0.0 -n production # 3. Wait for rollout kubectl rollout status deployment/app -n productionPost-deployment Verification
# Check migration status npm run migrate:status # Verify data integrity psql -c "SELECT COUNT(*) FROM user_preferences;" # Test endpoints curl https://api.example.com/health
---
## Common Workflows
### Creating a Feature PR
```bash
# 1. Create and checkout feature branch
git checkout -b feature/PROJ-123-new-dashboard
# 2. Make changes and commit
git add .
git commit -m "feat(dashboard): add user activity widget"
# 3. Push branch
git push -u origin feature/PROJ-123-new-dashboard
# 4. Create PR via GitHub CLI
gh pr create \
--title "[PROJ-123] Feature: Add user activity dashboard" \
--body "$(cat .github/pull_request_template.md)" \
--label "feature,needs-review" \
--reviewer team-lead,code-owner
# 5. Update Jira
# PR link automatically added via GitHub-Jira integration
Updating PR with Review Feedback
# 1. Make requested changes
git add .
git commit -m "fix: address review feedback"
# 2. Rebase if main has updates
git fetch origin
git rebase origin/main
# 3. Force push (safe because it's your branch)
git push --force-with-lease
# 4. Respond to review comments
gh pr comment 123 --body "Updated per your feedback!"
# 5. Re-request review
gh pr ready 123
Merging a PR
# 1. Final checks
gh pr checks 123
# 2. Update Jira status
# (Automated via webhook)
# 3. Merge via GitHub
gh pr merge 123 --squash --delete-branch
# 4. Update local main
git checkout main
git pull origin main
# 5. Verify deployment (if auto-deploy enabled)
kubectl get pods -n production
# 6. Close Jira ticket
# (Automated via webhook)
Troubleshooting
Merge Conflicts
# 1. Update main
git checkout main
git pull origin main
# 2. Rebase feature branch
git checkout feature/PROJ-123-feature
git rebase main
# 3. Resolve conflicts
# Edit conflicted files, then:
git add .
git rebase --continue
# 4. Force push
git push --force-with-lease origin feature/PROJ-123-feature
Failed CI/CD Checks
# 1. Check failure logs
gh run view [run-id]
# 2. Run tests locally
npm test
npm run lint
npm run type-check
# 3. Fix issues and push
git add .
git commit -m "fix: resolve CI failures"
git push origin feature/PROJ-123-feature
Large PR Feedback
If reviewer says "PR too large":
# 1. Create feature branch for series
git checkout -b feature/PROJ-123-new-feature-base
# 2. Create sub-branches for logical chunks
git checkout -b feature/PROJ-123-part-1-models
# Make changes, commit, push
# 3. Create first PR against base branch
gh pr create --base feature/PROJ-123-new-feature-base
# 4. Repeat for each logical chunk
git checkout feature/PROJ-123-new-feature-base
git checkout -b feature/PROJ-123-part-2-api
# Continue...
# 5. Final PR merges base into main
gh pr create --base main
Advanced Tips
PR Size Guidelines
- Small: < 100 lines - Ideal, easy to review
- Medium: 100-500 lines - Acceptable
- Large: 500-1000 lines - Consider splitting
- Too Large: > 1000 lines - Must split
Review Turnaround Expectations
- Hotfix: < 1 hour
- Bug fix: < 4 hours
- Small feature: < 1 day
- Medium feature: < 2 days
- Large feature: < 3 days
Best Practices Summary
- Keep PRs focused on single concern
- Write descriptive titles and descriptions
- Link to Jira tickets
- Include tests
- Update documentation
- Respond to feedback promptly
- Use draft PRs for early feedback
- Clean up commits before merging
- Delete branches after merge
- Monitor post-deployment
Resources
Last Updated: 2025-12-17 Skill Version: 1.0.0 Maintained By: Claude Orchestration Team