GitHub Workflow & Etiquette

When working in a multi-team, multi-feature environment, strict adherence to Git protocols prevents merge conflicts and deployment blockages. This document outlines the standard operating procedure for our repositories.

1. Branching Strategy

We use a modified Git Flow architecture. All new features must branch off develop, not main.

gitGraph
    commit
    branch develop
    checkout develop
    commit
    branch feature/auth
    checkout feature/auth
    commit id: "add JWT"
    commit id: "fix tests"
    checkout develop
    merge feature/auth
    checkout main
    merge develop tag: "v1.2.0"

Branch Naming Conventions

• Features: feature/<ticket-id>-<short-desc> (e.g., feature/AUTH-123-jwt-login)
• Bugfixes: bugfix/<ticket-id>-<short-desc>
• Hotfixes: hotfix/<ticket-id>-<short-desc> (Branches directly from main)

2. Commit Etiquette

We strictly enforce Conventional Commits. This allows our CI/CD pipelines to auto-generate changelogs and determine semantic versioning bumps.

• feat: A new feature (correlates with MINOR in semantic versioning).
• fix: A bug fix (correlates with PATCH).
• docs: Documentation only changes.
• refactor: A code change that neither fixes a bug nor adds a feature.

Example of a good commit:

feat(auth): implement Redis-backed session management

- Added Redis connection pool
- Implemented sliding window expiration
- Closes AUTH-456

3. Pull Request (PR) Protocols

Before opening a PR, ensure you have completed the following:

1. Rebase against target: git pull --rebase origin develop
2. Run tests locally: npm run test or cargo test
3. Self-Review: Look at your own diff in GitHub before requesting a reviewer.

The Code Review Cycle

sequenceDiagram
    participant Dev as Developer
    participant Git as GitHub
    participant CI as CI/CD Pipeline
    participant Rev as Reviewer

    Dev->>Git: Push feature branch
    Dev->>Git: Open Pull Request
    Git->>CI: Trigger tests & linting
    CI-->>Git: Status Check (Pass/Fail)
    
    alt Tests Failed
        Git-->>Dev: Block Merge
        Dev->>Git: Push Fixes
    else Tests Passed
        Git->>Rev: Request Review
        Rev-->>Git: Approve or Request Changes
        alt Approved
            Git->>Dev: Merge Allowed
        else Changes Requested
            Dev->>Git: Push Updates
        end
    end

Note on Approvals: Never override a blocked PR without explicit engineering manager approval. If the CI pipeline fails, the code is fundamentally broken.