Skip to main content

Development Workflow

This document describes the complete development process that the backend team must follow, from creating a new feature to its deployment in production.

Branching Strategy​

Branch Structure​

We use a simplified branching strategy with three main branches:

Permanent Branches​

  • main: Main branch containing production code

    • Must always be in a deployable state
    • Only updated through merges from stage
    • Automatic deployments to production
    • Note: Versioning will be implemented in the future

  • stage: Staging/pre-production branch

    • Contains code ready for final testing before production
    • Updated from develop when features are complete
    • Testing environment for QA and final validation
    • Automatic deployments to staging environment

  • develop: Main development branch

    • Contains the latest features in development
    • Base for creating new feature branches
    • Development environment for internal testing
    • Automatic deployments to development environment

Temporary Branches​

  • OPD-[number]-[description]: For developing new features and bug fixes

    • ⚠️ MANDATORY: MUST be created exclusively from Jira
    • Manual branch creation is NOT allowed without linking to a Jira task
    • OPD prefix followed by Jira task number
    • Created from develop for features
    • Merged back to develop via Pull Request
    • Examples:
      • OPD-29-frontend-componentizacion-base
      • OPD-45-api-user-authentication
      • OPD-67-fix-database-connection-timeout

  • hotfix/OPD-[number]-[description]: For urgent production fixes

    • ⚠️ MANDATORY: Also MUST be created from Jira
    • Created from main when a critical fix is required
    • Follow the same Jira nomenclature but with hotfix/ prefix
    • Merged directly to main, stage and develop
    • Example: hotfix/OPD-89-security-vulnerability-fix

Workflow by Change Type​

New Feature Development​

  1. ⚠️ MANDATORY - Create branch from Jira:

    • STEP 1: Go to the Jira task (e.g., OPD-29)
    • STEP 2: Click "Create branch" in the development panel
    • STEP 3: Jira will automatically create the branch: OPD-29-frontend-componentizacion-base
    • 🚫 FORBIDDEN: Creating branches manually without linking to Jira
    • 🚫 DO NOT:
    # ❌ INCORRECT - Do not create branches manually
    git checkout -b feature/new-functionality
    git checkout -b fix/some-bug

  2. Develop the functionality:

    • Make commits following the commit structure
    • Include the task number in commits: feat(OPD-29): add base componentization
    • Keep the branch updated with develop
    • Write tests for the new functionality

  3. Prepare for merge:

    git checkout develop
    git pull origin develop
    git checkout OPD-29-frontend-componentizacion-base
    git rebase develop

  4. Create Pull Request (see next section)

    • The title must include the Jira number: [OPD-29] feat: Add base componentization
    • Link the PR with the Jira task automatically

Environment Promotion​

  1. Develop → Stage:

    git checkout stage
    git pull origin stage
    git merge develop
    git push origin stage

  2. Stage → Main (Production):

    git checkout main
    git pull origin main
    git merge stage
    # Note: Versioning with tags will be implemented in the future
    git push origin main

Critical Bug Fix (Hotfix)​

  1. ⚠️ MANDATORY - Create hotfix branch from Jira:

    • STEP 1: Create a "Bug" type task with "Critical" priority in Jira
    • STEP 2: Use EXCLUSIVELY the "Create branch" function from the task
    • STEP 3: Jira will generate: hotfix/OPD-89-security-vulnerability-fix
    • 🚫 FORBIDDEN: Creating hotfix branches manually
    • 🚫 DO NOT:
    # ❌ INCORRECT - Do not create hotfixes manually
    git checkout -b hotfix/urgent-fix
    git checkout -b emergency-fix

  2. Implement the fix:

    • Make the minimum necessary change
    • Include the Jira number in commits: fix(OPD-89): resolve security vulnerability
    • Include tests that verify the fix
    • Update documentation if necessary

  3. Merge to all branches:

    # Merge to main
    git checkout main
    git merge hotfix/OPD-89-security-vulnerability-fix
    # Note: Versioning with tags will be implemented in the future

    # Merge to stage
    git checkout stage
    git merge hotfix/OPD-89-security-vulnerability-fix

    # Merge to develop
    git checkout develop
    git merge hotfix/OPD-89-security-vulnerability-fix

    # Push all changes
    git push origin main stage develop

  4. Update Jira:

    • Move the task to "Done"
    • Link the commit/PR with the task
    • Document the implemented solution

Pull Request Process in Bitbucket​

⚠️ MANDATORY PLATFORM: Bitbucket​

All Pull Requests and merges are performed exclusively in Bitbucket:

  • 🔗 Platform: Bitbucket (project repository)
  • 🚫 Forbidden: Using other platforms or tools for PRs
  • ✅ Integration: Bitbucket is automatically integrated with Jira
  • 📋 Pipeline: Bitbucket Pipelines executes CI/CD automatically

Prerequisites​

Before creating a Pull Request, make sure that:

  • Code compiles without errors
  • All existing tests pass
  • Tests have been added for new functionality
  • Code follows coding conventions
  • Documentation is updated
  • Commits follow the established structure

Creating Pull Request in Bitbucket​

Process in Bitbucket​

  1. Access Bitbucket:

    • Go to the project repository in Bitbucket
    • Navigate to the "Pull requests" section
    • Click "Create pull request"

  2. Select branches:

    • Source branch: Your OPD-XX branch (e.g., OPD-29-frontend-componentizacion-base)
    • Destination branch: develop (for features) or main (for hotfixes)
    • Bitbucket will automatically detect changes

  3. Automatic linking with Jira:

    • Bitbucket will automatically detect the OPD-XX number
    • The link with the Jira task will be created
    • The task will automatically move to "Code Review"

PR Title​

Use the format: [OPD-XXX] [TYPE]: Brief description

Examples:

  • [OPD-29] feat: Add base componentization system
  • [OPD-45] feat: Add user authentication system
  • [OPD-67] fix: Resolve database connection timeout
  • [OPD-78] docs: Update API documentation

PR Description​

Include the following information:

## Description
Brief description of the changes made.

## Type of Change
- [ ] Bug fix (change that fixes an issue)
- [ ] New functionality (change that adds functionality)
- [ ] Breaking change (change that causes existing functionality not to work as expected)
- [ ] Documentation change

## How has it been tested?
Describe the tests you have performed to verify your changes.

## Checklist
- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, especially in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes do not generate new warnings
- [ ] I have added tests that prove my fix is effective or my functionality works
- [ ] New and existing unit tests pass locally with my changes

Assignment and Labels in Bitbucket​

PR Configuration in Bitbucket​

  • Assign reviewers:

    • Minimum 2 team reviewers (mandatory in Bitbucket)
    • Use the "Reviewers" function in the Bitbucket interface
    • Bitbucket will send notifications automatically

  • Labels in Bitbucket:

    • feature - For new functionalities
    • bugfix - For bug fixes
    • hotfix - For critical fixes
    • documentation - For documentation changes

  • Milestone/Sprint:

    • Assign to the corresponding sprint in Bitbucket
    • Automatically syncs with Jira

Code Review Guidelines​

For the PR Author​

Before Requesting Review​

  1. Complete self-review:

    • Review each line of modified code
    • Verify there is no unnecessary commented code
    • Ensure there are no console.logs or debugging code

  2. Context documentation:

    • Explain non-obvious design decisions
    • Document any trade-offs made
    • Include screenshots if there are visual changes

  3. Exhaustive testing:

    • Run all tests locally
    • Manually test edge cases
    • Verify that existing functionality is not broken

During Review​

  • Respond constructively to comments
  • Explain the reasoning behind decisions
  • Make requested changes in a timely manner
  • Thank for feedback and suggestions

For Reviewers​

Review Checklist​

Functionality​
  • Does the code do what it's supposed to do?
  • Are edge cases handled correctly?
  • Is there adequate input validation?
  • Is error handling appropriate?
Code Quality​
  • Is the code readable and maintainable?
  • Are naming conventions followed?
  • Is there code duplication that can be refactored?
  • Do methods and classes have clear responsibility?
Performance and Security​
  • Are there potential performance issues?
  • Are sensitive data handled correctly?
  • Are there obvious security vulnerabilities?
  • Are technology best practices used?
Testing​
  • Is there sufficient test coverage?
  • Are tests meaningful and not trivial?
  • Do tests fail when they should fail?
Documentation​
  • Is relevant documentation updated?
  • Are code comments useful?
  • Are public APIs documented?

Comment Types​

Use prefixes to clarify intention:

  • nit: - Minor suggestions, non-blocking
  • question: - Questions to better understand the code
  • suggestion: - Optional improvements
  • issue: - Problems that must be resolved
  • praise: - Recognition of good code

Approval Criteria​

A PR can be approved when:

  • ✅ All automated tests pass
  • ✅ At least 2 reviewers have approved
  • ✅ All "issue" comments have been resolved
  • ✅ Code meets quality standards
  • ✅ Functionality is completely implemented

Merge Process in Bitbucket​

Merge Types in Bitbucket​

  1. Squash and Merge (Recommended for features):

    • Where: "Merge" button → Select "Squash"
    • When: For feature branches (OPD-XX)
    • Benefit: Maintains clean history in develop
    • Message: Bitbucket will use the PR title automatically

  2. Merge Commit (For releases and hotfixes):

    • Where: "Merge" button → Select "Merge commit"
    • When: For promotions between develop → stage → main
    • Benefit: Preserves branch context and facilitates tracking

Merge Process in Bitbucket​

  1. PR Approval:

    • Minimum 2 reviewers must approve in Bitbucket
    • All Bitbucket Pipelines checks must pass (✅)
    • Resolve all comments marked as "blocking"

  2. Execute Merge from Bitbucket:

    • Click the "Merge" button in the Bitbucket interface
    • Select the appropriate merge type
    • Bitbucket will execute the merge automatically

  3. Automatic cleanup:

    • ✅ Bitbucket automatically deletes the remote branch after merge
    • You only need to clean up the local branch:
    git checkout develop
    git pull origin develop
    git branch -d OPD-29-frontend-componentizacion-base

  4. Automatic Jira update:

    • ✅ Bitbucket automatically updates the task in Jira
    • The task automatically moves to "Done" when the merge is done
    • The commit and PR are recorded in the task history

Jira Integration​

⚠️ MANDATORY RULES​

🚫 STRICT PROHIBITIONS:

  • Manual branch creation is NOT allowed without an associated Jira task
  • PRs will NOT be accepted from branches that don't follow OPD-XX nomenclature
  • You cannot work on code without having an assigned task in Jira
  • Skipping the Jira creation process is NOT allowed

✅ OBLIGATIONS:

  • ALL branches MUST be created from Jira
  • ALL commits MUST include the task number
  • ALL PRs MUST be linked with Jira
  • ALL tasks MUST be in "In Progress" before creating the branch

Creating Branches from Jira​

The workflow is integrated with Jira to maintain complete traceability between tasks and code:

MANDATORY Standard Process​

  1. Task Assignment:

    • Take a task from the backlog in Jira
    • MANDATORY: Move the task to "In Progress"
    • Verify that the task has all necessary information
    • DO NOT proceed without having the task assigned and in progress

  2. Branch Creation (ONLY ALLOWED METHOD):

    • STEP 1: In the Jira task, go to the "Development" panel
    • STEP 2: Click "Create branch" (ONLY allowed method)
    • STEP 3: Jira will automatically generate: OPD-[number]-[description-kebab-case]
    • STEP 4: Select develop as base branch (for features)
    • ⚠️ IMPORTANT: This is the ONLY authorized method to create branches

  3. Automatic Nomenclature:

    • Features: OPD-29-frontend-componentizacion-base
    • Bugs: OPD-67-fix-database-connection-timeout
    • Tasks: OPD-45-setup-authentication-system
    • Hotfixes: hotfix/OPD-89-security-vulnerability-fix

Automatic Linking​

  • Commits: Include task number in the message

    git commit -m "feat(OPD-29): implement base component structure"
    git commit -m "fix(OPD-67): resolve database timeout issue"

  • Pull Requests: The title must include the Jira number

    [OPD-29] feat: Implement base component structure
    [OPD-67] fix: Resolve database timeout issue

  • Automatic Transitions:

    • When creating PR → Task moves to "Code Review"
    • When merging PR → Task moves to "Done"

Jira Status Flow​

To Do → In Progress → Code Review → Testing → Done
  ↓         ↓            ↓           ↓        ↓
Assign   Create      Create PR    Deploy    Merge PR
 task    branch                  staging

States and Actions​

  1. To Do: Task in backlog, ready to be taken
  2. In Progress: Developer working, branch created
  3. Code Review: PR created, waiting for review
  4. Testing: PR approved, code in staging for QA
  5. Done: PR merged, functionality in production

Best Practices with Jira​

Commit Nomenclature​

  • Always use the task number: feat(OPD-XX): description
  • Follow conventional commits: type(scope): description
  • Be descriptive: Explain what was done, not how

Task Management​

  • One branch per task: Don't mix multiple tasks in one branch
  • Small tasks: Maximum 3-5 days of work
  • Update progress: Comment in Jira about blockers or changes

Documentation in Jira​

  • Acceptance Criteria: Clearly define what should be implemented
  • Definition of Done: Checklist of what the task must fulfill
  • Technical comments: Document implementation decisions

Best Practices​

Branch Management​

  • Keep branches small: Maximum 400 lines of change
  • Update frequently: Rebase with develop regularly
  • Names from Jira: Use Jira's automatic nomenclature (OPD-XX-description)
  • Regular cleanup: Delete merged branches

Collaboration​

  • Proactive communication: Inform about changes that may affect others
  • Pair programming: For complex or critical functionalities
  • Knowledge sharing: Rotate reviewers to distribute knowledge

Conflict Resolution​

  1. Prevention:

    • Keep branches updated
    • Communicate changes in shared areas
    • Make frequent merges to develop

  2. Resolution:

    git checkout feature/my-branch
    git rebase develop
    # Resolve conflicts manually
    git add .
    git rebase --continue

  3. Post-resolution verification:

    • Run all tests
    • Verify that functionality still works
    • Request additional review if conflicts were complex

Deployment and Release Process​

Versioning Strategy​

📋 Note: The versioning strategy is in the process of definition. We are considering implementing Semantic Versioning (SemVer) in the future to standardize project releases.

Future proposal: MAJOR.MINOR.PATCH format where:

  • MAJOR: Incompatible API changes
  • MINOR: New backward-compatible functionality
  • PATCH: Backward-compatible bug fixes

For now, deployments are performed without formal versioning.

Deployment Environments​

Environment Structure​

  1. Development (dev)

    • Purpose: Internal testing and active development
    • Source: Branch develop
    • Deployment: Automatic on each push to develop
    • URL: https://api-dev.proyecto.com

  2. Staging (staging)

    • Purpose: Pre-production testing and QA
    • Source: Branch stage
    • Deployment: Automatic on each push to stage
    • URL: https://api-staging.proyecto.com

  3. Production (prod)

    • Purpose: Production environment for end users
    • Source: Branch main
    • Deployment: Automatic on each push to main
    • URL: https://api.proyecto.com
    • Note: Versioning with tags will be implemented in the future

CI/CD Pipeline with Bitbucket Pipelines​

Bitbucket Pipelines Configuration​

The Bitbucket Pipelines pipeline runs automatically on the following events:

# Configuration example (bitbucket-pipelines.yml)
pipelines:
  branches:
    develop:
      - step: &build-and-test
          name: Build and Test
          script:
            - npm ci
            - npm run lint
            - npm run test:coverage
            - npm run build
          artifacts:
            - dist/**
            - coverage/**
      - step:
          name: Deploy to Development
          deployment: development
          script:
            - echo "Deploying to development environment"
            - ./scripts/deploy-dev.sh

    stage:
      - step: *build-and-test
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - echo "Deploying to staging environment"
            - ./scripts/deploy-staging.sh

    main:
      - step: *build-and-test
      - step:
          name: Deploy to Production
          deployment: production
          script:
            - echo "Deploying to production environment"
            - ./scripts/deploy-prod.sh

  pull-requests:
    '**':
      - step: *build-and-test

Pipeline Stages​

  1. Build & Test

    • Dependency installation
    • Linting and formatting
    • Unit and integration test execution
    • Coverage report generation
    • Application build

  2. Security Scan

    • Dependency vulnerability analysis
    • Static code scan (SAST)
    • Secrets and credentials verification

  3. Quality Gates

    • Minimum test coverage (80%)
    • No critical vulnerabilities
    • Code quality metrics compliance

  4. Deployment

    • Automatic deployment to development
    • Manual deployment to staging/production
    • Automatic rollback in case of failure

Release Process​

Release Preparation​

  1. Develop → Stage Promotion

    git checkout stage
    git pull origin stage
    git merge develop
    git push origin stage

  2. Staging Testing

    • Deployment to staging is automatic when pushing to stage
    • Run integration and QA tests
    • Validate functionalities with stakeholders
    • Verify performance and stability

  3. Prepare Release for Production

    • Update package.json with new version
    • Update CHANGELOG.md with changes
    • Create release documentation
    • Obtain necessary approvals

  4. Stage → Main (Production) Promotion

    git checkout main
    git pull origin main
    git merge stage
    # Note: Versioning with tags will be implemented in the future
    git push origin main

  5. Synchronize Develop

    # Ensure develop is updated with main
    git checkout develop
    git merge main
    git push origin develop

Release Notes​

Each release should include:

# Release v1.2.0

## 🚀 New Features
- [FEAT-123] OAuth2 authentication implementation
- [FEAT-124] Push notifications API

## 🐛 Bug Fixes
- [BUG-456] Database connection timeout fix
- [BUG-457] User endpoint validation fix

## 🔧 Improvements
- [IMPROVE-789] Database query optimization
- [IMPROVE-790] Security dependency updates

## 💥 Breaking Changes
- Change in user API response format
- Deprecation of `/api/v1/old-endpoint` endpoint

## 📋 Migration Guide
To migrate from v1.1.x:
1. Update user API calls
2. Replace usage of deprecated endpoints

Environment Promotion Workflow​

Development → Staging​

  1. Trigger: Manual through merge from develop to stage
  2. Process: 
    git checkout stage
    git pull origin stage
    git merge develop
    git push origin stage
  3. Validation: Automatic smoke tests
  4. Rollback: Manual if health checks or QA fail

Staging → Production​

  1. Prerequisites:

    • ✅ All staging tests pass
    • ✅ Documentation updated

  2. Deployment Process:

    # Deployment with blue-green strategy
    ./scripts/deploy-production.sh --strategy=blue-green --version=v1.2.0

  3. Post-Deployment Verification:

    • Automatic health checks
    • Production smoke tests
    • Key metrics monitoring
    • Manual verification of critical functionalities

  4. Communication:

    • Notification to team of successful deployment
    • Status page update if applicable
    • Communication to stakeholders

Rollback and Recovery​

Rollback Process​

  1. Problem Detection:

    • Automatic monitoring alerts
    • User reports
    • Degraded performance metrics

  2. Rollback Decision:

    • Impact assessment
    • Team communication

  3. Rollback Execution:

    # Automatic rollback to previous version
    ./scripts/rollback.sh --to-version=v1.1.9

    # Verify successful rollback
    ./scripts/verify-rollback.sh

  4. Post-Rollback:

    • Root cause analysis
    • Incident documentation
    • Correction plan for next release

Recovery Procedures​

  • Database Rollback: Reverse migration scripts
  • Configuration Rollback: Configuration versioning
  • Cache Invalidation: Cache cleanup after rollback
  • Monitoring Reset: Alert and metrics restart

Monitoring and Alerts​

Key Metrics​

  • Performance: Response time, throughput, error rate
  • Infrastructure: CPU, memory, disk usage
  • Business: Successful transactions, active users
  • Security: Unauthorized access attempts, vulnerabilities

Alert Configuration​

# Alert configuration example
alerts:
  - name: "High Error Rate"
    condition: "error_rate > 5%"
    duration: "5m"
    severity: "critical"
    
  - name: "High Response Time"
    condition: "avg_response_time > 2s"
    duration: "10m"
    severity: "warning"
    
  - name: "Low Disk Space"
    condition: "disk_usage > 85%"
    duration: "5m"
    severity: "warning"

Deployment Documentation​

Deployment Runbook​

Each deployment should have documented:

  • Prerequisites: Necessary dependencies and configurations
  • Deployment steps: Step-by-step process
  • Verification: How to validate that deployment was successful
  • Rollback: Rollback procedure in case of problems
  • Contacts: Responsible persons and escalation path

Production Deployment Checklist​

  • Code reviewed and approved
  • Tests passing in all environments
  • Database migrated (if applicable)
  • Configurations updated
  • Monitoring configured
  • Team notified of deployment
  • Rollback plan prepared
  • Documentation updated

Best Practices​

Deployment​

  • Small and frequent deployments: Reduce risk and facilitate debugging
  • Complete automation: Minimize human errors
  • Immutable infrastructure: Avoid manual configurations
  • Feature flags: Allow enabling/disabling functionalities without deployment

Monitoring​

  • Complete observability: Logs, metrics and tracing
  • Intelligent alerts: Avoid alert fatigue
  • Informative dashboards: System status visibility
  • Post-mortem culture: Learn from incidents without blame

Security​

  • Secrets management: Never hardcode credentials
  • Access control: Principle of least privilege
  • Audit trail: Record of all deployments
  • Vulnerability scanning: Continuous security analysis