Table of Contents

Code Contribution Workflow

This document outlines the complete workflow for contributing code to Qwestly projects, from feature development through deployment.

Overview

Qwestly follows a feature branch workflow with strict quality gates and SOC2 compliance requirements. Every code change must go through our automated security scanning, peer review, and approval process before reaching production.

Repository Access & Permissions

Team Roles & Access Levels

Role	Access Level	Repositories	Permissions
CTO (Dominick)	Admin	All repositories	Full access, can override protections
CEO (Adam)	Admin	All repositories	Full access, can override protections
Senior Engineers	Write	All repositories	Create branches, submit PRs, review code
Engineers	Write	Assigned repositories	Create branches, submit PRs
Contractors	Write	Specific repositories	Limited to assigned projects

Required Setup

2FA enabled on GitHub account (SOC2 requirement)
SSH keys configured for repository access
Git user configuration with company email
GitHub CLI installed and authenticated (recommended)
Branch protection rules understood and followed

GitHub CLI Setup

Installation

macOS (Homebrew)

brew install gh

macOS (MacPorts)

sudo port install gh

Windows (Chocolatey)

choco install gh

Windows (Scoop)

scoop install gh

Linux (apt)

sudo apt update
sudo apt install gh

Linux (dnf)

sudo dnf install gh

Authentication

# Authenticate with GitHub
gh auth login

# Follow the prompts:
# 1. Choose "GitHub.com"
# 2. Choose "HTTPS" or "SSH" (SSH recommended if keys are set up)
# 3. Choose "Login with a web browser"
# 4. Copy the one-time code and open in browser
# 5. Complete authentication in browser

# Verify authentication
gh auth status

Basic Configuration

# Set default editor for GitHub CLI
gh config set editor "code --wait"  # VS Code
# or
gh config set editor "vim"          # Vim
# or  
gh config set editor "nano"         # Nano

# Set default protocol
gh config set git_protocol ssh      # Use SSH (recommended)
# or
gh config set git_protocol https    # Use HTTPS

# View current configuration
gh config list

Branch Strategy

Branch Naming Convention

feature/short-description     # New features
bugfix/issue-description      # Bug fixes  
hotfix/critical-issue         # Production hotfixes
chore/maintenance-task        # Maintenance work
docs/documentation-update     # Documentation changes

Protected Branches

main - Production branch, fully protected
develop - Integration branch (if used)

Branch Protection Rules

✅ Require pull request reviews (minimum 1 approver)
✅ Require status checks to pass (CI/CD pipeline)
✅ Require branches to be up to date before merging
✅ Include administrators in restrictions
✅ Restrict pushes that create files over 100MB

Development Workflow

1. Starting New Work

# Start from main branch
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/add-candidate-profile-anonymization

# Verify you're on the correct branch
git branch --show-current

2. Development Process

# Make your changes
# ... edit files ...

# Stage changes
git add .

# Commit with descriptive message (conventional commits)
git commit -m "feat: implement candidate profile anonymization

- Add anonymization service for removing PII
- Implement field-level data masking
- Add tests for anonymization logic
- Update API endpoints to use anonymized data

Closes #123"

3. Keeping Branch Updated (Rebase Workflow)

Important: We use rebase over merge to maintain a clean commit history.

Option A: Interactive Rebase (Recommended)

# Fetch latest changes
git fetch origin

# Interactive rebase to clean up commits
git rebase -i origin/main

# In the editor that opens, you can:
# - pick: keep commit as-is
# - reword: change commit message
# - edit: modify commit content
# - squash: combine with previous commit
# - fixup: combine with previous commit, discard message
# - drop: remove commit entirely

Option B: Simple Rebase

# Fetch latest changes
git fetch origin

# Rebase your branch onto latest main
git rebase origin/main

# If conflicts occur, resolve them:
git status                    # See conflicted files
# ... edit files to resolve conflicts ...
git add .                     # Stage resolved files
git rebase --continue         # Continue rebase

# If you need to abort the rebase:
git rebase --abort

Option C: Rebase and Squash Local Commits

# Squash last 3 commits into one
git rebase -i HEAD~3

# Or squash all commits in your branch
git rebase -i origin/main

4. Force Push After Rebase

⚠️ Important: After rebasing, you'll need to force push since you've rewritten history.

# Force push (safer option)
git push --force-with-lease origin feature/add-candidate-profile-anonymization

# Only use --force if you're sure no one else is working on the branch
git push --force origin feature/add-candidate-profile-anonymization

Why --force-with-lease? It's safer because it will fail if someone else has pushed to your branch, preventing accidental overwrites.

Pull Request Process

1. Creating a Pull Request

Using GitHub CLI (Recommended)

# Create PR from current branch
gh pr create

# Follow the interactive prompts or use flags:
gh pr create \
  --title "feat: implement candidate profile anonymization" \
  --body "## Summary
Implement anonymization service for candidate profiles...

## Changes Made
- Add anonymization service
- Implement field-level masking
- Add comprehensive tests

## Testing
- [x] Unit tests added
- [x] E2E tests updated
- [x] Manual testing completed"

# Create draft PR
gh pr create --draft

# Create PR with specific reviewers
gh pr create --reviewer dominick,adam

# Create PR with labels
gh pr create --label "enhancement,security"

# Create PR using a template (if .github/pull_request_template.md exists)
gh pr create --template .github/pull_request_template.md

Using GitHub Web Interface

If you prefer the web interface, push your branch and visit the repository to create a PR.

PR Title Format

Follow conventional commit format:

feat: implement candidate profile anonymization
fix: resolve authentication timeout issue  
docs: update API documentation for new endpoints
chore: upgrade dependencies for security patches

PR Description Template

## Summary
Brief description of what this PR does and why.

## Changes Made
- [ ] List specific changes
- [ ] Include any new dependencies
- [ ] Note any breaking changes

## Testing
- [ ] Unit tests added/updated
- [ ] E2E tests added/updated  
- [ ] Manual testing completed
- [ ] Security implications reviewed

## Screenshots/Videos
Include if UI changes are involved.

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Tests pass locally
- [ ] Documentation updated
- [ ] No secrets or sensitive data included

## Related Issues
Closes #123
Relates to #456

2. Automated Checks

Every PR triggers our CI/CD pipeline:

Security Scanning ✅

Trivy vulnerability scanning - Checks dependencies for known vulnerabilities
TruffleHog secret scanning - Prevents accidental secret commits
SARIF upload - Results appear in GitHub Security tab

Code Quality ✅

ESLint + Prettier - Code formatting and style
TypeScript compilation - Type safety validation
Unit tests - Automated test execution
E2E tests - Critical user journey validation (where enabled)

Compliance ✅

Branch protection validation - Ensures proper workflow
Audit trail generation - SOC2 compliance logging

3. Review Requirements

Who Can Approve?

CTO (Dominick) - All repositories
CEO (Adam) - All repositories
Senior Engineers - Assigned repositories
External reviewers - As designated

Review Criteria

Reviewers should check for:

Code Quality:

Code is readable and well-documented
Follows established patterns and conventions
No code duplication or obvious inefficiencies
Proper error handling implemented

Security:

No hardcoded secrets or credentials
Input validation and sanitization
Proper authentication/authorization
No obvious security vulnerabilities

Functionality:

Changes match the requirements
Edge cases considered and handled
No breaking changes without proper migration
Tests adequately cover new functionality

Architecture:

Changes align with system architecture
Dependencies are justified and secure
Performance implications considered
Scalability impact assessed

4. Managing Pull Requests with GitHub CLI

Viewing PRs

# List all open PRs in current repository
gh pr list

# List PRs with specific filters
gh pr list --state closed
gh pr list --author @me
gh pr list --assignee dominick
gh pr list --label "bug"

# View PR details
gh pr view 123                    # View PR #123
gh pr view --web                  # Open current branch's PR in browser
gh pr view 123 --web             # Open specific PR in browser

# View PR diff
gh pr diff 123
gh pr diff                        # Current branch's PR

Checking Out PRs for Review

# Check out a PR locally for testing
gh pr checkout 123               # Check out PR #123
gh pr checkout feature/my-branch # Check out by branch name

# View PR status and checks
gh pr status
gh pr checks                     # View CI/CD status
gh pr checks --watch             # Watch checks in real-time

Reviewing PRs

# Start a review
gh pr review 123

# Review with specific action
gh pr review 123 --approve
gh pr review 123 --request-changes
gh pr review 123 --comment

# Add review comments
gh pr review 123 --body "Great work! Just a few minor suggestions..."

# Review interactively
gh pr review --approve --body "LGTM! Tests pass and code looks good."

Updating PRs

# Edit PR title and body
gh pr edit 123
gh pr edit 123 --title "New title"
gh pr edit 123 --body "Updated description"

# Add reviewers
gh pr edit 123 --add-reviewer dominick,adam

# Add labels
gh pr edit 123 --add-label "enhancement,security"

# Convert to/from draft
gh pr ready 123                  # Mark draft as ready
gh pr draft 123                  # Convert to draft

Merging PRs

# Merge PR (uses repository's default merge method)
gh pr merge 123

# Merge with specific strategy
gh pr merge 123 --squash         # Squash and merge (recommended)
gh pr merge 123 --rebase         # Rebase and merge
gh pr merge 123 --merge          # Create merge commit

# Auto-merge when checks pass
gh pr merge 123 --auto --squash

# Delete branch after merge
gh pr merge 123 --squash --delete-branch

Closing PRs

# Close PR without merging
gh pr close 123

# Reopen closed PR
gh pr reopen 123

5. Addressing Review Feedback

# Make requested changes
# ... edit files based on feedback ...

# Commit changes
git add .
git commit -m "fix: address review feedback

- Update error handling for edge cases
- Add missing input validation
- Improve test coverage for new methods"

# Push changes (no need to force push unless you rebased)
git push origin feature/add-candidate-profile-anonymization

6. Final Approval and Merge

Once approved and all checks pass, you can merge using GitHub CLI:

# Check if PR is ready to merge
gh pr status
gh pr checks

# Merge using recommended squash strategy
gh pr merge --squash --delete-branch

# Or let GitHub handle it through the web interface
gh pr view --web

Traditional merge process:

Reviewer approves the PR
Status checks pass (all CI/CD pipeline stages)
Branch is up to date with main (rebase if needed)
Author or reviewer merges the PR

Merge Strategies

Squash and Merge (Recommended)

When: Feature branches with multiple commits
Result: Clean, linear history with one commit per feature
Use case: Most feature development

Rebase and Merge

When: Clean commit history that tells a story
Result: Linear history preserving individual commits
Use case: Well-crafted commit sequences

Merge Commit

When: Rarely used (emergency situations)
Result: Preserves branch history but creates merge commits
Use case: Hotfixes or when history preservation is critical

Repository Management with GitHub CLI

Cloning and Repository Setup

# Clone repository with GitHub CLI
gh repo clone qwestly/qwestly-app
gh repo clone qwestly/candidate
gh repo clone qwestly/api-python

# Clone to specific directory
gh repo clone qwestly/qwestly-app ~/Work/qwestly-workspace/qwestly-app

# Fork a repository
gh repo fork qwestly/qwestly-app

# View repository information
gh repo view
gh repo view qwestly/qwestly-app
gh repo view --web  # Open in browser

Issue Management

# List issues
gh issue list
gh issue list --state closed
gh issue list --assignee @me
gh issue list --label "bug"

# Create new issue
gh issue create
gh issue create --title "Bug: Authentication timeout" --body "Description of the issue..."

# View issue details
gh issue view 123
gh issue view 123 --web

# Comment on issues
gh issue comment 123 --body "I'm working on this issue"

# Close/reopen issues
gh issue close 123
gh issue reopen 123

# Link issues to PRs (in PR description)
# "Closes #123" or "Fixes #123" will auto-close the issue when PR merges

Release Management

# List releases
gh release list

# View release details
gh release view v1.2.0

# Create release
gh release create v1.2.0 --title "Version 1.2.0" --notes "Release notes..."

# Download release assets
gh release download v1.2.0

Hotfix Workflow

For critical production issues:

# Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/fix-authentication-bug

# Make minimal changes to fix the issue
# ... make changes ...

# Commit and push
git add .
git commit -m "hotfix: resolve authentication timeout issue

- Increase session timeout from 1h to 4h
- Add retry logic for token refresh
- Update error messages for better UX

Fixes critical issue affecting 15% of users"

git push origin hotfix/fix-authentication-bug

# Create hotfix PR with GitHub CLI
gh pr create \
  --title "hotfix: resolve authentication timeout issue" \
  --body "## Critical Issue
Resolving authentication timeout affecting 15% of users.

## Changes
- Increase session timeout from 1h to 4h
- Add retry logic for token refresh  
- Update error messages for better UX

## Testing
- [x] Manual verification completed
- [x] Production monitoring enabled

Fixes critical issue affecting 15% of users" \
  --reviewer dominick,adam \
  --label "hotfix,critical"

# Fast-track the review and merge
gh pr merge --squash --delete-branch

Hotfix PR Requirements:

Expedited review (same-day approval target)
Minimal scope (only fix the specific issue)
Extra testing (manual verification required)
Documentation (incident post-mortem if needed)

Common Rebase Scenarios

Scenario 1: Update Branch with Latest Main

# Your feature branch is behind main
git checkout feature/my-feature
git fetch origin
git rebase origin/main

# If conflicts:
# 1. Resolve conflicts in files
# 2. git add .
# 3. git rebase --continue
# 4. Repeat until complete

git push --force-with-lease origin feature/my-feature

Scenario 2: Clean Up Commit History

# You have 5 messy commits to clean up
git rebase -i HEAD~5

# In editor, change 'pick' to:
# pick   abc123 feat: initial implementation
# squash def456 fix typos  
# squash ghi789 address review comments
# squash jkl012 fix tests
# fixup  mno345 remove debug code

# Result: One clean commit with all changes

Scenario 3: Split a Large Commit

# Start interactive rebase
git rebase -i HEAD~1

# Change 'pick' to 'edit' for the commit to split
# When rebase pauses:
git reset HEAD~1          # Unstage all changes
git add file1.js          # Stage first logical group
git commit -m "feat: add user validation"
git add file2.js file3.js # Stage second logical group  
git commit -m "feat: update UI components"
git rebase --continue     # Finish rebase

Scenario 4: Fix a Commit Message

# Fix the last commit message
git commit --amend -m "feat: implement correct feature description"

# Fix an older commit message
git rebase -i HEAD~3      # Go back 3 commits
# Change 'pick' to 'reword' for commits to fix
# Edit messages in subsequent editors

Troubleshooting Common Issues

Rebase Conflicts

# When you see conflicts during rebase:
git status                # See which files have conflicts

# Edit files to resolve conflicts (look for <<<<<<< markers)
# Remove conflict markers and choose the correct code

git add .                 # Stage resolved files
git rebase --continue     # Continue rebase

# If you get stuck:
git rebase --abort        # Start over

Force Push Issues

# Error: "Updates were rejected because the tip of your current branch is behind"
# This happens when someone else pushed to your branch

# Fetch latest changes
git fetch origin

# See what changed
git log HEAD..origin/feature/my-feature

# If safe to overwrite:
git push --force-with-lease origin feature/my-feature

# If you need to integrate their changes:
git pull --rebase origin feature/my-feature
git push origin feature/my-feature

Lost Commits After Rebase

# Find your lost commits
git reflog

# Look for your commits and note the hash
# Restore lost work:
git cherry-pick <commit-hash>

# Or reset to a previous state:
git reset --hard HEAD@{2}  # Go back 2 reflog entries

Best Practices

Commit Best Practices

Atomic commits - One logical change per commit
Descriptive messages - Explain what and why, not how
Test your changes - Every commit should leave the code in a working state
Keep commits focused - Don't mix unrelated changes

Branch Best Practices

Short-lived branches - Merge within 1-2 days when possible
Regular updates - Rebase daily to avoid large conflicts
Descriptive names - Branch name should indicate the work being done
Clean before PR - Rebase and clean up commits before creating PR

Review Best Practices

Review promptly - Aim to review within 24 hours
Be constructive - Suggest improvements, don't just point out problems
Ask questions - If something is unclear, ask for clarification
Test locally - Pull the branch and test changes when needed

Security Best Practices

Never commit secrets - Use environment variables
Review dependencies - Understand what you're adding to the project
Consider privacy - Be mindful of PII in logs and error messages
Follow principle of least privilege - Only request necessary permissions

Emergency Procedures

Reverting a Deployed Change

# If a merged PR causes production issues:

# Option 1: Revert the merge commit
git checkout main
git pull origin main
git revert -m 1 <merge-commit-hash>
git push origin main

# Option 2: Create a hotfix
git checkout -b hotfix/revert-problematic-feature
# Make necessary changes
# Follow hotfix workflow

Rolling Back Deployment

Since we use Vercel for deployment:

Vercel Dashboard - Go to the project and click "Rollback" on a previous deployment
GitHub - Revert the problematic commit and push to main
Emergency contact - Notify team immediately via established channels

Compliance & Audit Trail

SOC2 Requirements Met

✅ All changes reviewed - No direct commits to main
✅ Audit trail maintained - Full history in GitHub
✅ Security scanning - Automated on every commit
✅ Access controls - RBAC with 2FA requirements
✅ Change documentation - PRs provide change rationale

Evidence Collection

Our workflow automatically generates SOC2 evidence:

GitHub audit logs - All access and changes tracked
CI/CD pipeline logs - Security scan results and deployment records
PR approval records - Code review documentation
Branch protection exports - Access control configuration

Quick Reference

Essential Git Commands

# Start new feature
git checkout main && git pull && git checkout -b feature/my-feature

# Update branch with main
git fetch origin && git rebase origin/main

# Clean up commits
git rebase -i origin/main

# Push after rebase
git push --force-with-lease origin feature/my-feature

Essential GitHub CLI Commands

# Setup and authentication
gh auth login
gh auth status

# Repository management
gh repo clone qwestly/qwestly-app
gh repo view --web

# Pull request workflow
gh pr create                           # Create PR interactively
gh pr create --draft                   # Create draft PR
gh pr list                             # List open PRs
gh pr view 123                         # View PR details
gh pr checkout 123                     # Check out PR locally
gh pr review 123 --approve             # Approve PR
gh pr merge 123 --squash --delete-branch # Merge and cleanup

# Issue management
gh issue list                          # List issues
gh issue create                        # Create new issue
gh issue view 123                      # View issue details

Common Rebase Commands

git rebase -i HEAD~3           # Interactive rebase last 3 commits
git rebase -i origin/main      # Interactive rebase entire branch
git rebase --continue          # Continue after resolving conflicts
git rebase --abort             # Cancel rebase and return to original state
git push --force-with-lease    # Safe force push after rebase

GitHub CLI Quick Tips

# Create PR with all the details in one command
gh pr create --title "feat: new feature" --body "Description" --reviewer @me

# Check CI status for current branch
gh pr checks

# Open current PR in browser
gh pr view --web

# Approve and merge in one flow
gh pr review --approve && gh pr merge --squash --delete-branch

Document Owner: Dominick Pham, CTO
Last Updated: July 1, 2025
Next Review: October 1, 2025

For questions about this workflow, create an issue in the qwestly-docs repository or contact the engineering team.

_private/qwestly-docs/Engineering/Code Contribution Workflow.md