PR Workflow Skill

Guidance for creating, managing, and merging PRs with Jira integration and deployment best practices.

Branch Naming

Format: <type>/<jira-key>-<short-description>

Types: feature, bugfix, hotfix, refactor, docs, test, chore, perf

Rules: lowercase, hyphens, max 50 chars, include Jira key

Example: feature/LOBBI-1234-member-dashboard

Commit Messages

Format:

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci

Rules: lowercase subject, no period, imperative mood, max 50 chars

Footers: Closes PROJ-123, BREAKING CHANGE: description, Refs PROJ-456

PR Title & Description

Title: [JIRA-KEY] Type: Brief description

Description checklist items:

Jira issue link
Changes made (bullet points)
Technical details (architecture, database, API changes)
Testing: unit, integration, E2E, manual steps
Screenshots/videos if UI changes
Risk assessment (Low/Medium/High/Critical)
Deployment prerequisites & migration steps
Dependencies (related PRs, blocked by, blocks)
Checklist: code style, tests, docs, no console.log, no commented code

Review Process

Reviewer selection:

Code owner (required, auto-assigned via CODEOWNERS)
Subject matter expert (complex/security/performance)
Team lead (major architectural changes, breaking changes)

Review labels: needs-review, needs-changes, approved, security-review, breaking-change, hotfix, size/small|medium|large, wip

Merge requirements:

All CI/CD checks pass
Required approvals received
Branch up-to-date with main
Documentation complete
Conversations resolved

Merge Strategies

Strategy	Best For	Benefit
Squash	Features, bug fixes, WIP commits	Clean history
Merge Commit	Long-lived branches, team effort	Preserves history
Rebase	Clean commits, small focused PRs	Linear history

Decision Matrix:

Feature + WIP commits → Squash
Hotfix (single commit) → Rebase
Large feature (team) → Merge Commit
Bug fix (2-3 commits) → Squash
Refactor (logical steps) → Merge Commit

Jira Integration

Automatic linking: Include Jira key in branch name, PR title, or commits

Status transitions:

PR opened → To Do → In Progress
Ready for review → In Review
Changes requested → In Progress
Approved → Ready for Merge
Merged → Done
Closed (not merged) → Cancelled

Automatic Jira comments post:

PR opened notification with metadata
Status updates on approval
Merge/close notifications

Deployment

Risk assessment checklist:

Database schema changes
API breaking changes
Third-party integration changes
Auth/authorization changes
Performance-critical code
High-traffic endpoints
Data migration required

Rollback procedure:

Immediate: alert team, document in incident channel
Execute: kubectl rollout undo / helm rollback / vercel rollback
Verify: health checks, error rates, user traffic
Database: run down migration if needed
Post: update Jira, notify stakeholders, schedule post-mortem

Feature flags: Use gradual rollout (10%, 50%, 100%) with kill switches

Common Workflows

Create Feature PR:

git checkout -b feature/PROJ-123-new-dashboard
# Make changes
git add . && git commit -m "feat: add dashboard"
git push -u origin feature/PROJ-123-new-dashboard
# Create PR via Harness Code API

Address Feedback:

git add . && git commit -m "fix: address review feedback"
git fetch origin && git rebase origin/main
git push --force-with-lease
# Re-request review

Merge PR (via Harness Code):

# Verify all pipeline checks pass via Harness Code API
harness_get_pull_request_checks --pr-number 123
# Merge via Harness Code API
harness_merge_pull_request --pr-number 123 --strategy squash
git checkout main && git pull origin main
# Verify deployment via Harness Pipeline

Troubleshooting

Merge conflicts:

Update main: git checkout main && git pull origin main
Rebase: git checkout feature && git rebase main
Resolve files and git add . && git rebase --continue
Force push: git push --force-with-lease

Failed CI checks:

View logs via Harness Pipeline execution logs
Run locally: npm test && npm run lint && npm run type-check
Fix and push again

Large PR feedback:

Create feature base branch
Split into logical chunks
Create sub-PRs against base, then final PR to main

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

Hotfix: < 1 hour
Bug fix: < 4 hours
Small feature: < 1 day
Medium feature: < 2 days
Large feature: < 3 days

Best Practices

Keep PRs focused on single concern
Write descriptive titles and descriptions
Link to Jira tickets
Include tests and documentation
Respond to feedback promptly
Use draft PRs for early feedback
Clean up commits before merging
Delete branches after merge
Monitor post-deployment

pr-workflow