Skip to main content

BitBucket - Git Workflow

Overview

This workflow uses a linear, one-way merge strategy with clear role separation between Developers who create features and Reviewers/Admins who manage releases and maintain code quality.

Workflow Diagram

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   feature/  │───▶│development  │───▶│   staging   │───▶│ production  │
│   branches  │    │             │    │             │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
       │                   │                  │                  │
   DEVELOPER            REVIEWER/         REVIEWER/         REVIEWER/
    ZONE                 ADMIN             ADMIN             ADMIN
       │                 ZONE              ZONE              ZONE
       ▼                   ▼                  ▼                  ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    Local    │    │ Development │    │  Staging    │    │ Production  │
│ Environment │    │ Environment │    │ Environment │    │ Environment │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

👨‍💻 DEVELOPER GUIDE

Role Overview

Developers are responsible for implementing features, fixing bugs, and maintaining code quality in their local environment and feature branches. Developers work exclusively in feature branches and submit changes via Pull Requests.

Developer Workflow

1. Starting a New Feature

Pre-Development Checklist

  • [ ] Feature requirements are clearly defined
  • [ ] Design/architecture approved (if applicable)
  • [ ] Acceptance criteria documented
  • [ ] Local development environment set up

Creating Feature Branch

# 1. Ensure you're on latest development
git checkout development
git pull origin development

# 2. Create feature branch with descriptive name
git checkout -b feature/user-authentication-system

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

Naming Conventions

  • Features/Enhancements: feature/descriptive-name (e.g., feature/payment-integration)
  • Bug fixes: bugfix/fix-login-timeout
  • Hot Fixes: hotfix/fix-database-crash-when-update

2. Development Process

Daily Development Workflow

# Start your day - sync with latest development
git checkout development
git pull origin development
git checkout feature/your-feature-name
git rebase development  # Keep your branch current

# Make your changes
# ... develop feature ...

# Commit frequently with meaningful messages
git add .
git commit -m "feat: implement user registration endpoint"

# Continue development...
git add .
git commit -m "test: add unit tests for user registration"

# Push to remote regularly (backup your work)
git push origin feature/your-feature-name

Developer Commit Standards

Use conventional commit format:

  • feat: add new feature
  • fix: resolve bug in user login
  • docs: update API documentation
  • test: add unit tests for payment module
  • refactor: optimize database query performance
  • style: fix code formatting issues

3. Pre-Submission Checklist

Before creating a Pull Request, ensure:

Code Quality Checklist

  • [ ] All tests pass locally 
    npm test  # or your project's test command
  • [ ] Code follows project style guidelines 
    npm run lint  # or your linting commandnpm run format  # or your formatting command
  • [ ] No console.log or debug code remaining
  • [ ] All new code has appropriate comments
  • [ ] Functions and variables have descriptive names

Feature Completeness Checklist

  • [ ] All acceptance criteria met
  • [ ] Feature works as expected in local environment
  • [ ] Error handling implemented
  • [ ] Edge cases considered and tested
  • [ ] No breaking changes to existing functionality
  • [ ] Database migrations created (if applicable)

Documentation Checklist

  • [ ] README updated (if applicable)
  • [ ] API documentation updated (if applicable)
  • [ ] Inline code documentation added
  • [ ] Changelog entry prepared

4. Submitting Pull Request

Creating the Pull Request

# Final push before PR creation
git push origin feature/your-feature-name

# Create PR via GitHub/GitLab interface:
# Source: feature/your-feature-name
# Target: development

Pull Request Template

## Description
Brief description of what this PR accomplishes.

## Type of Change
- [ ] New feature
- [ ] Bug fix
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] No regression issues found

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No console.log statements
- [ ] Commit messages follow convention

## Breaking Changes
List any breaking changes and migration steps required.

## Additional Notes
Any additional context or notes for reviewers.

5. Responding to Review Feedback

Handling Review Comments

# Make requested changes
# ... implement feedback ...

# Commit changes addressing feedback
git add .
git commit -m "fix: address PR review feedback - update validation logic"

# Push updated changes
git push origin feature/your-feature-name

Review Response Etiquette

  • Respond promptly to review comments
  • Ask for clarification if feedback is unclear
  • Explain your reasoning for any disagreements
  • Thank reviewers for their time and feedback
  • Mark conversations as resolved after addressing feedback

6. Post-Merge Cleanup

Once your PR is merged:

# Switch to development and pull latest changes
git checkout development
git pull origin development

# Delete local feature branch
git branch -d feature/your-feature-name

# Delete remote feature branch (if not auto-deleted)
git push origin --delete feature/your-feature-name

# Verify your feature is in development
git log --oneline -10  # Should see your commits

Developer Don'ts

❌ Never do these things:
  • Don't push directly to development, staging, or production
  • Don't merge your own Pull Requests (unless specifically allowed)
  • Don't create Pull Requests from development to staging or production
  • Don't work directly on development, staging, or production branches
  • Don't force push to shared branches
  • Don't commit secrets, passwords, or API keys
  • Don't leave TODO comments in production code

🔍 REVIEWER/ADMIN GUIDE

Role Overview

Reviewers/Admins are responsible for maintaining code quality, managing releases, and ensuring the stability of shared branches. They have elevated permissions and handle branch-to-branch merges.

Reviewer/Admin Responsibilities

Code Review Responsibilities

  • Review all Pull Requests targeting development
  • Ensure code quality and adherence to standards
  • Verify tests pass and coverage is adequate
  • Check for security vulnerabilities
  • Validate architectural decisions

Release Management Responsibilities

  • Manage development → staging releases
  • Manage staging → production releases
  • Handle hotfix deployments
  • Maintain release documentation and changelogs
  • Coordinate with QA and stakeholders

Reviewer Workflow

1. Code Review Process

Pull Request Review Checklist

When reviewing a developer's PR:

Code Quality Review

  • [ ] Code follows project conventions and style guide
  • [ ] Functions are appropriately sized and focused
  • [ ] Variable and function names are descriptive
  • [ ] No hardcoded values where configuration should be used
  • [ ] Error handling is appropriate and comprehensive
  • [ ] No commented-out code blocks
  • [ ] No console.log or debug statements

Functionality Review

  • [ ] Feature meets acceptance criteria
  • [ ] Logic is sound and efficient
  • [ ] Edge cases are handled
  • [ ] No obvious bugs or issues
  • [ ] Performance impact considered
  • [ ] Security implications reviewed

Testing Review

  • [ ] Adequate test coverage
  • [ ] Tests actually test the functionality
  • [ ] Both positive and negative test cases
  • [ ] Integration points are tested
  • [ ] Tests are maintainable and clear

Documentation Review

  • [ ] Code is self-documenting or has appropriate comments
  • [ ] Complex logic is explained
  • [ ] API changes are documented
  • [ ] README updates included if needed

Review Response Guidelines

## Approving a PR
✅ "LGTM! Great work on the error handling and test coverage."

## Requesting Changes
📝 "Looks good overall, just a few items to address:
1. Line 45: Consider extracting this logic into a helper function
2. Missing test case for the edge case when user is null
3. Please add JSDoc comments for the public API methods"

## Major Issues
❌ "Cannot approve due to security concerns:
1. SQL injection vulnerability on line 78
2. User input not properly validated
3. Authentication bypass possible in edge case
Please address these critical issues before resubmitting."

2. Managing Development Integration

When to Merge Features to Development

Merge criteria:

  • [ ] PR has required approvals (minimum 1 reviewer)
  • [ ] All automated checks pass (CI/CD, tests, linting)
  • [ ] No merge conflicts
  • [ ] Feature is complete (not work-in-progress)
  • [ ] Documentation is updated

Development Branch Health Monitoring

Daily responsibilities:

  • [ ] Monitor development environment for stability
  • [ ] Review failed builds and coordinate fixes
  • [ ] Ensure integration tests pass after merges
  • [ ] Track technical debt and plan cleanup

Admin Release Workflow

3. Development to Staging Release

Pre-Release Preparation

Before merging development → staging:

Release Planning Checklist

  • [ ] All planned features merged to development
  • [ ] Development environment stable for 24+ hours
  • [ ] No critical bugs in development
  • [ ] Stakeholder approval received for release
  • [ ] QA team notified and available for testing
  • [ ] Release notes prepared

Executing Development to Staging

# 1. Verify development branch stability
git checkout development
git pull origin development
git log --oneline -10  # Review recent changes

# 2. Check for any last-minute issues
# Review monitoring, error logs, team feedback

# 3. Merge to staging
git checkout staging
git pull origin staging
git merge development

# 4. Push and trigger staging deployment
git push origin staging

# 5. Create release PR documentation
# Document what's included in this staging release

Post-Staging Deployment

  • [ ] Verify staging deployment successful
  • [ ] Run smoke tests on staging environment
  • [ ] Notify QA team that staging is ready for testing
  • [ ] Update project management tools with release status
  • [ ] Monitor staging environment for issues

4. Staging to Production Release

Pre-Production Release Checklist

Before merging staging → production:

Quality Assurance Verification

  • [ ] All QA tests pass on staging environment
  • [ ] User Acceptance Testing (UAT) completed
  • [ ] Performance testing results acceptable
  • [ ] Security scan passed (if applicable)
  • [ ] No critical bugs found in staging
  • [ ] Stakeholder sign-off received

Production Readiness

  • [ ] Database migrations tested (if applicable)
  • [ ] Deployment script validated
  • [ ] Rollback plan prepared and tested
  • [ ] Monitoring alerts configured
  • [ ] Team available for post-deployment support
  • [ ] Communication plan prepared for users (if needed)

Executing Production Release

# 1. Final verification of staging
git checkout staging
git pull origin staging
git log --oneline -5  # Confirm what's being released

# 2. Create production release
git checkout production
git pull origin production

# 3. Merge staging to production
git merge staging

# 4. Tag the release
git tag -a v1.2.0 -m "Release v1.2.0: User Authentication and Payment Integration"

# 5. Push release and tags
git push origin production --tags

# 6. Deploy to production (trigger deployment pipeline)

Post-Production Deployment

Immediate Actions (0-30 minutes)

  • [ ] Verify deployment successful
  • [ ] Run production smoke tests
  • [ ] Check error monitoring for new issues
  • [ ] Monitor key metrics (response time, error rates)
  • [ ] Verify critical user flows working

Follow-up Actions (1-24 hours)

  • [ ] Monitor application performance
  • [ ] Review error logs for any new issues
  • [ ] Gather user feedback (if applicable)
  • [ ] Update release documentation
  • [ ] Communicate release success to stakeholders

Branch Protection Configuration

Development Branch

Protection Rules:
  - Require pull request reviews: 1
  - Dismiss stale reviews: true
  - Require review from code owners: true
  - Require status checks to pass: true
  - Require branches to be up to date: true
  - Restrict pushes to: Admins only
  - Allow force pushes: false

Staging Branch

Protection Rules:
  - Require pull request reviews: 1 (Admin only)
  - Require status checks to pass: true
  - Restrict pushes to: Release managers only
  - Allow force pushes: false

Production Branch

Protection Rules:
  - Require pull request reviews: 2 (Senior developers/admins)
  - Require status checks to pass: true
  - Require signed commits: true (recommended)
  - Restrict pushes to: Senior admins only
  - Allow force pushes: false

Communication Templates

Release Communication Template

## Release v1.2.0 to Staging
**Release Date:** 2025-01-15
**Target Production Date:** 2025-01-17

### Features Included:
- User authentication system
- Payment gateway integration
- Dashboard performance improvements

### QA Testing Required:
- [ ] User registration/login flow
- [ ] Payment processing
- [ ] Dashboard load testing

### Breaking Changes:
None

### Rollback Plan:
Revert to staging branch commit abc123 if issues found.

cc: @qa-team @product-manager @stakeholders

Monitoring and Metrics

Key Metrics to Track

  • PR Review Time: Target < 24 hours
  • Development Branch Stability: Target > 95% uptime
  • Staging Test Pass Rate: Target > 98%
  • Production Deployment Success: Target > 99%
  • Hotfix Frequency: Target < 1 per month
  • Code Coverage: Target > 80%

Daily Admin Checklist

  • [ ] Review overnight build results
  • [ ] Check environment health dashboards
  • [ ] Review pending PRs requiring attention
  • [ ] Monitor error rates across environments
  • [ ] Update release planning boards
  • [ ] Communicate any blockers to team
No Comments
Back to top