python_autoformat.yml

# ============================================================================
# Workflow: Auto-Format Python Code
# ============================================================================
# This is a MORE ADVANCED workflow. Instead of just checking formatting and
# failing the PR, this workflow actually RUNS Black and Ruff on your code
# and COMMITS the fixed files back to your branch automatically.
#
# How it works:
#   1. You push a commit to a feature branch (e.g. feature/alice)
#   2. This workflow runs Black and Ruff --fix on src/
#   3. If any files were changed, the workflow creates a new commit:
#      "auto: format code with Black and Ruff [skip ci]"
#   4. That commit is pushed back to YOUR branch (not to main)
#   5. You can then pull that commit locally: `git pull`
#
# IMPORTANT NOTES
# ---------------
# [skip ci] in the commit message: this prevents the auto-commit from
#   triggering the workflow AGAIN (which would cause an infinite loop).
#
# `permissions: contents: write`: By default, workflows can only READ the
#   repo. To push a commit back, we need write permission. This is safe
#   here because we're only pushing to the same branch that triggered the run.
#
# This workflow does NOT run on `main` - formatting fixes should go through
# a branch and PR like everything else. Direct auto-commits to main would
# bypass the review process.
#
# When to use this vs python_checks.yml
# --------------------------------------
# python_checks.yml   → REPORTS formatting issues (you fix them yourself)
# python_autoformat   → FIXES formatting issues automatically (bot fixes them)
#
# Both approaches are common in real projects. This repo uses BOTH so you can
# see how each one works. In production, you'd typically pick one.
# ============================================================================

name: Auto-Format Python Code

# TRIGGERS
on:
  push:
    branches-ignore:
      - main     # never auto-commit directly to main - use PRs for that

# PERMISSIONS
# Without this, the workflow can read the repo but cannot push commits back
permissions:
  contents: write

jobs:

  autoformat:
    name: Auto-format with Black and Ruff
    runs-on: ubuntu-latest

    steps:
      # -----------------------------------------------------------------------
      # Step 1: Check out the branch that was just pushed
      # -----------------------------------------------------------------------
      - name: Check out the code
        uses: actions/checkout@v4
        with:
          # GITHUB_TOKEN is a built-in secret that gives the workflow access
          # to the repo. It's automatically available - you don't need to
          # create it manually.
          token: ${{ secrets.GITHUB_TOKEN }}

      # -----------------------------------------------------------------------
      # Step 2: Set up Python
      # -----------------------------------------------------------------------
      - name: Set up Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      # -----------------------------------------------------------------------
      # Step 3: Install formatters
      # -----------------------------------------------------------------------
      - name: Install Black and Ruff
        run: pip install black ruff

      # -----------------------------------------------------------------------
      # Step 4: Run Black (auto-fix mode, no --check flag)
      # -----------------------------------------------------------------------
      - name: Format with Black
        run: black src/
        # Without --check, Black actually modifies files in place.
        # If everything is already formatted, it reports "All done!" and changes nothing.

      # -----------------------------------------------------------------------
      # Step 5: Run Ruff with auto-fix
      # -----------------------------------------------------------------------
      - name: Fix with Ruff
        run: ruff check --fix src/ || true
        # --fix: automatically fix issues that Ruff knows how to fix
        # || true: don't fail this step even if Ruff finds issues it CAN'T fix
        #   (those will be caught by python_checks.yml and reported to the PR)

      # -----------------------------------------------------------------------
      # Step 6: Commit and push any changes
      # -----------------------------------------------------------------------
      - name: Commit formatting changes (if any)
        run: |
          # Configure a bot identity for the commit
          # This is how the commit will appear in the git log
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          # Check if Black or Ruff changed anything
          # `git diff --quiet` exits with 0 (success) if there are NO changes,
          # and exits with 1 (failure) if there ARE changes
          if git diff --quiet; then
            echo "No formatting changes needed - code was already clean!"
          else
            # Stage all changes in src/
            git add src/

            # Commit with [skip ci] to prevent this commit from triggering
            # the workflow again (which would cause an infinite loop)
            git commit -m "auto: format code with Black and Ruff [skip ci]"

            # Push back to the same branch that triggered this workflow
            git push
            echo "Formatting changes committed and pushed."
            echo "Run 'git pull' locally to get the auto-formatted version."
          fi