🌳 Git Workflow & Conventions¶

A guide to our Git workflow and commit conventions

📝 Commit Message Structure¶

Bash

<type>(<scope>): <subject>

🏷️ Commit Types¶

Type	Icon	Description
`feat`	✨	New feature
`fix`	🐛	Bug fix
`docs`	📚	Documentation changes
`style`	💅	Formatting changes
`refactor`	♻️	Code restructuring
`test`	🧪	Test updates
`chore`	🔧	Build tasks, configs
`ops`	🚀	Infrastructure, deployment

✍️ Writing Rules¶

🎯 Scope: (Optional) Component/module affected
📌 Subject: Use imperative mood ("Add" not "Added")

🌿 Branch Organization¶

📊 Core Branches¶

Branch	Icon	Purpose	Key Rules
`main`	🏭	Production	• No direct commits • Only `release`/`hotfix` merges • Version tagged
`develop`	🔨	Development	• Feature integration • Next release prep

🔄 Supporting Branches¶

Type	Pattern	Flow	Purpose
Feature	`feature/*`	`develop` → `develop`	✨ New features
Release	`release/*`	`develop` → `main+develop`	📦 Release prep
Hotfix	`hotfix/*`	`main` → `main+develop`	🚑 Quick fixes

⚡ Quick Commands¶

🌟 Feature Development¶

Bash

# 🏁 Start feature
git checkout -b feature/name develop

# ✅ Complete feature
git checkout develop
git merge --no-ff feature/name
git branch -d feature/name
git push origin develop

📦 Release Process¶

Bash

# 🏁 Start release
git checkout -b release/1.0.0 develop

# ✅ Complete release
git checkout main
git merge --no-ff release/1.0.0
git tag -a v1.0.0
git checkout develop
git merge --no-ff release/1.0.0
git branch -d release/1.0.0
git push --all && git push --tags

🚑 Hotfix Process¶

Bash

# 🏁 Start hotfix
git checkout -b hotfix/fix-name main

# ✅ Complete hotfix
git checkout main
git merge --no-ff hotfix/fix-name
git checkout develop
git merge --no-ff hotfix/fix-name
git branch -d hotfix/fix-name
git push --all

🚀 GitHub Actions CI/CD Workflow¶

Automated testing, code quality checks, docs deployment, and releases

📊 CI/CD Pipeline Structure¶

📊 CI/CD Pipeline File¶

YAML

---
name: CI/CD Pipeline

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]
  workflow_dispatch: true  # Allow manual triggering

jobs:
  test:
    name: Run Tests
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        python-version: ["3.11", "3.12"]

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: "pip"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install uv tox tox-gh-actions
          uv pip install -e .[test]

      - name: Run tests with tox
        run: tox

  lint:
    name: Lint Code
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: "pip"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install uv
          uv pip install -e .[lint]

      - name: Run ruff
        run: ruff check .

      - name: Run black
        run: black --check .

      - name: Run mypy
        run: mypy .

  docs:
    name: Build and Deploy Docs
    runs-on: ubuntu-latest
    needs: [test, lint]
    # Only deploy docs when pushing to main/master, not on PRs
    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Get all history for proper versioning

      - name: Set up Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: "pip"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install uv
          uv pip install -e .[docs]
          uv pip install mike

      - name: Configure Git user
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"

      - name: Build documentation
        run: mkdocs build -v

      - name: Deploy documentation to GitHub Pages
        run: |
          # If using versioned docs with mike
          mike deploy --push --update-aliases $(git describe --tags --abbrev=0) latest

          # Alternatively, for non-versioned docs, use the mkdocs gh-deploy command
          # mkdocs gh-deploy --force

  # Add deployment job for production releases
  release:
    name: Create Release
    runs-on: ubuntu-latest
    needs: [test, lint, docs]
    if: startsWith(github.ref, 'refs/tags/v')

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: "pip"

      - name: Install build dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install build twine

      - name: Build package
        run: python -m build

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          files: dist/*
          generate_release_notes: true

      - name: Publish to PyPI
        env:
          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
        run: twine upload --skip-existing dist/*

# Configuration for tox to run in GitHub Actions
# Add this to tox.ini:
# [gh-actions]
# python =
#     3.11: py311
#     3.12: py312

Our workflow file .github/workflows/ci-cd.yml automates the following processes:

Job	Icon	Purpose	Trigger
`test`	🧪	Multi-platform testing	All pushes and PRs
`lint`	🔍	Code quality checks	All pushes and PRs
`docs`	📚	Documentation build & deploy	Pushes to main
`release`	📦	Package build & PyPI publish	Tagged releases

🏗️ Workflow Overview¶

graph TD
    A[Push/PR] --> B[Test]
    A --> C[Lint]
    B --> D{Main Branch?}
    C --> D
    D -->|Yes| E[Build & Deploy Docs]
    D -->|Tagged Release| F[Build & Publish Package]

🧪 Testing Job¶

YAML

test:
  runs-on: ${{ matrix.os }}
  strategy:
    matrix:
      os: [ubuntu-latest, windows-latest]
      python-version: ['3.11', '3.12']
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
    - run: python -m pip install uv tox tox-gh-actions
    - run: tox

🔍 Linting Job¶

YAML

lint:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
    - run: python -m pip install uv
    - run: uv pip install -e .[lint]
    - run: ruff check .
    - run: black --check .
    - run: mypy .

📚 Documentation Job¶

YAML

docs:
  runs-on: ubuntu-latest
  needs: [test, lint]
  if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - uses: actions/setup-python@v5
    - run: uv pip install -e .[docs] mike
    - run: git config --local user.email "github-actions[bot]@users.noreply.github.com"
    - run: git config --local user.name "github-actions[bot]"
    - run: mkdocs build -v
    - run: mike deploy --push --update-aliases $(git describe --tags --abbrev=0) latest

📦 Release Job¶

YAML

release:
  runs-on: ubuntu-latest
  needs: [test, lint, docs]
  if: startsWith(github.ref, 'refs/tags/v')
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
    - run: python -m pip install build twine
    - run: python -m build
    - uses: softprops/action-gh-release@v1
      with:
        files: dist/*
        generate_release_notes: true
    - run: twine upload --skip-existing dist/*
      env:
        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

🛠️ Configuration Tips¶

Tip	Icon	Description
Secrets	🔒	Add `PYPI_USERNAME` and `PYPI_PASSWORD` to repository secrets
Tox Integration	🔄	Add [gh-actions] section to tox.ini
Branch Protection	🛡️	Require status checks to pass before merging
Manual Triggers	🔄	Use workflow_dispatch for manual runs
Caching	⚡	Dependencies cached for faster runs

📋 Tox GitHub Actions Integration¶

Add this to your tox.ini file:

INI

[gh-actions]
python =
    3.11: py311
    3.12: py312

🧩 Workflow Events¶

Event	Icon	Trigger	Purpose
`push`	📤	Pushing to main/master	Run tests and deploy docs
`pull_request`	🔄	PRs to main/master	Run tests and linting
`workflow_dispatch`	🔘	Manual UI trigger	Run full pipeline on demand
`tags`	🏷️	Creating v* tags	Create releases and publish packages

💡 Best Practices¶

Practice	Description
📝 Commit Messages	Write clear, descriptive messages
👀 Code Review	Create PRs for all changes
✅ Testing	Ensure all tests pass before merge
📚 Documentation	Keep docs updated with changes
🔄 CI/CD	Use automated quality checks
🚀 Deployment	Automate from `main` branch

📚 Resources¶

📖 Conventional Commits¶

Resource	Icon	Purpose
Conventional Commits	📜	Official specification
Angular Guidelines	🅰️	Reference implementation
Commitlint	✨	Commit message linting
Commitizen	🛠️	Interactive commit tool

🌊 Git Flow Resources¶

Resource	Icon	Purpose
Git Flow Original	📘	Original workflow guide
Atlassian Guide	📗	Comprehensive tutorial
GitHub Flow	📓	Simplified workflow
GitLab Flow	📔	Enterprise approach

⚙️ GitHub Actions Resources¶

Resource	Icon	Purpose
GitHub Actions Docs	📄	Official documentation
Marketplace	🛒	Community actions
Workflow Syntax	📝	YAML format reference
Python CI Examples	🐍	Python-specific workflows

🛠️ Helpful Tools¶

Tool	Icon	Purpose
Husky	🐶	Git hooks automation
Semantic Release	📦	Version management
Conventional Changelog	📝	Auto-generate changelogs
Git Flow AVH	🔧	Extended Git Flow CLI
Pre-commit Hooks Guide	🔍	Code quality automation

🎨 Icon Resources¶

Resource	Icon	Purpose
Gitmoji	😄	Emoji guide for Git commits
GitHub Emoji	📋	Complete emoji cheatsheet
Emojipedia	📚	Emoji meanings and variants
Unicode Emoji	🌐	Official Unicode emoji list

💡 Tip: Bookmark this guide for quick reference during development