tomevault-io 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
Resources
Converted and distributed by TomeVault — claim your Tome and manage your conversions.