[Dev-Setup/Docs] Question: What is the purpose of maintaining both main and master branches?

[lenucksi]

Context

I noticed that this repository maintains both main and master branches, with a GitHub Actions workflow (.github/workflows/main-to-master-sync.yml) that automatically syncs main to master on every push.

Current Setup

Workflow:

# .github/workflows/main-to-master-sync.yml
name: Sync Main to Master

on:
  push:
    branches:
      - main

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v6
      with:
        ref: main
        fetch-depth: 0

    - name: Sync main to master
      run: |
        git checkout master
        git merge --ff-only main
        git push origin master

Observations:

1. Default branch: main (as shown in GitHub UI)
2. Sync direction: main → master (one-way)
3. Multiple workflows reference master:
   • Some workflows still check for master branch (causing bugs)
   • Example: update-readme.yml has branches: [master] but should be [main]

Questions

1. What is the purpose of the master branch?

• Is it for backward compatibility with external tools/integrations?
• Is it for users who bookmarked the old branch name?
• Is there a specific reason it's maintained?

2. Is the sync necessary?

The sync workflow:

• ✅ Ensures master stays in sync with main
• ❌ Uses GitHub Actions minutes
• ❌ Creates duplicate commits/refs
• ❌ May confuse contributors about which branch to use - it certainly confused me...

3. Should workflows reference main or master?

Currently there's inconsistency:

• Some workflows: branches: [main] ✅
• Some workflows: branches: [master] ❌ (don't trigger)
• Docker workflow: github.ref == 'refs/heads/master' ❌ (broken)

Confusion Examples

Example 1: Docker Workflow

# Checks for master, but branch is main
push: ${{ github.ref == 'refs/heads/master' }}

Result: Docker images never pushed (critical bug)

Example 2: Update README Workflow

# Triggers on master, but pushes happen to main
on:
  push:
    branches: [master]

Result: Workflow never runs

Questions for Maintainers

1. Is there a documented reason for keeping master?

   • If yes, where is it documented?
   • What would break if we removed it?

2. Are there external integrations that depend on master?

   • CI/CD systems?
   • Documentation links?
   • Package registries?

Related Issues/PRs - filed earlier

• See also: ci: add automated weekly test matrix updates #1316 fix(devcontainer): install uv and add venv cleanup #1317 fix(ci): fix broken Docker workflow and modernize #1318 security(ci): enable GitHub Actions digest pinning in Renovate #1319 fix(ci): add branch filter to TOC generator workflow #1320 fix(ci): correct branch name and path in update-readme workflow #1321

• Multiple workflow bugs caused by main/master confusion

• Docker workflow broken due to checking wrong branch

• Update-readme workflow not triggering due to wrong branch