Skip to content

branching.md

Latest commit

 

History

History
387 lines (264 loc) · 7.3 KB

branching.md

File metadata and controls

387 lines (264 loc) · 7.3 KB
Raw

Branching Convention

Version: 2.0 Effective Date: 2025-12-27 Status: Active

Overview

A.R.C. CLI uses a PR-number-based branching convention to ensure clear traceability between branches, pull requests, and feature specifications.

Naming Convention

Format

{PR_NUMBER}-{feature-name}

Components:

  • {PR_NUMBER}: The GitHub Pull Request number (3 digits, zero-padded)
  • {feature-name}: Short, kebab-case description of the feature

Examples

007-state-management
008-config-system
009-provider-interface
010-kubernetes-provider

Workflow

1. Determine Next PR Number

Before creating a new feature branch, check what the next PR number will be:

# List all PRs to see the highest number
gh pr list --state all --limit 50

# Or check the last merged PR
git log --oneline | head -5

Example Output:

#6   001 initial setup
#5   001 initial setup
#4   001 initial setup  ← Last merged
#3   001 initial setup
#2   001 initial setup
#1   001 initial setup

Next PR will be: #7

2. Create Branch with PR Number

# Create and switch to new branch
git checkout -b 007-state-management

# Or from specific base
git checkout -b 007-state-management main

3. Create Spec Directory

Match the branch name to the spec directory:

mkdir -p specs/002-state-management

Note: Spec directory uses feature sequence (002), branch uses PR number (007)

4. Work and Commit

# Make changes
git add .
git commit -m "Implement state management foundation"

# Push branch
git push origin 007-state-management

5. Create Pull Request

# Using GitHub CLI
gh pr create \
  --title "002: State Management" \
  --body "Implements state management system. See specs/002-state-management/" \
  --base main

# Or via GitHub UI
# The PR will automatically get number #7

6. Update Branch Reference in Spec

Once PR is created, update the spec files:

**Feature ID**: 002-state-management
**Branch**: `007-state-management`
**PR**: #7

Mapping Convention

Feature Sequence vs PR Number

  • Feature Sequence: Sequential numbering of features (001, 002, 003...)
  • PR Number: Actual GitHub PR number (may include failed/closed PRs)

Example:

Feature 001 → Branch: 001-initial-setup      → PR #1-6 (multiple attempts)
Feature 002 → Branch: 007-state-management   → PR #7 (first attempt succeeded)
Feature 003 → Branch: 008-config-system      → PR #8
Feature 004 → Branch: 012-provider-interface → PR #9-11 (failed), #12 (succeeded)

Directory Structure:

specs/
├── 001-initial-setup/          # Feature sequence
├── 002-state-management/       # Feature sequence
├── 003-config-system/          # Feature sequence
└── 004-provider-interface/     # Feature sequence

git branches:
├── 001-initial-setup           # Merged via PR #4
├── 007-state-management        # Next PR will be #7
├── 008-config-system           # Hypothetical future PR #8
└── 012-provider-interface      # Hypothetical future PR #12

Benefits

✅ Traceability

  • Branch name directly references PR number
  • Easy to find PR from branch name: gh pr view 007
  • Clear history of which PRs were merged

✅ No Collisions

  • PR numbers are auto-assigned by GitHub (unique)
  • No need to coordinate branch names across developers

✅ Linear History

  • Chronological PR numbering shows development timeline
  • Easy to see which features came first

✅ GitHub Integration

  • Branch name matches GitHub's PR URL structure
  • Works well with automated workflows

Migration from Old Convention

Old Convention (v1.0)

{feature-sequence}-{feature-name}
001-initial-setup
002-state-management
003-config-system

New Convention (v2.0)

{pr-number}-{feature-name}
007-state-management
008-config-system
009-provider-interface

Transition Period

For existing branches:

  • Keep the old name (001-initial-setup is fine if already merged)
  • No need to rename merged branches

For new branches:

  • Use PR-number-based naming starting now
  • First new branch will be 007-{feature-name}

Special Cases

Multiple PRs for Same Feature

If a PR fails and needs to be reopened:

# First attempt (failed)
git checkout -b 007-state-management
gh pr create  # Creates PR #7
# PR closed without merge

# Second attempt
git checkout -b 008-state-management  # New PR number
gh pr create  # Creates PR #8
# PR merged successfully

Spec references both:

**Feature ID**: 002-state-management
**Branches**:

- `007-state-management` (PR #7 - closed)
- `008-state-management` (PR #8 - merged)

Hotfix Branches

For urgent fixes outside the feature process:

# Check next PR number (e.g., #15)
git checkout -b 015-hotfix-security-issue

# Still follows same convention

Experimental Branches

For experiments that may not result in PR:

# Use `exp/` prefix
git checkout -b exp/try-new-library

# When ready to PR, rename to PR-number format
git branch -m 016-new-library-integration

Automation

Pre-branch Hook (Optional)

Create a helper script to automate branch creation:

#!/bin/bash
# scripts/new-branch.sh

# Check if gh is installed
if ! command -v gh &> /dev/null
then
    echo "GitHub CLI (gh) could not be found. Please install it to use this script."
    exit
fi

# Get next PR number
NEXT_PR=$(gh pr list --state all --json number --jq 'max_by(.number).number + 1')

# Prompt for feature name
read -p "Feature name (kebab-case): " FEATURE_NAME

# Create branch
BRANCH_NAME="${NEXT_PR}-${FEATURE_NAME}"
git checkout -b "$BRANCH_NAME"

echo "✅ Created branch: $BRANCH_NAME"
echo "Next: Create specs directory and start implementation"

Usage:

./scripts/new-branch.sh
# Feature name (kebab-case): state-management
# ✅ Created branch: 007-state-management

Examples

Feature 002: State Management

# Step 1: Check next PR number
gh pr list --state all --limit 5
# Last PR was #6

# Step 2: Create branch
git checkout -b 007-state-management

# Step 3: Create spec directory
mkdir -p specs/002-state-management

# Step 4: Implement feature
# ... work ...

# Step 5: Create PR
gh pr create --title "002: State Management"
# PR #7 created

# Step 6: Update spec
# Edit specs/002-state-management/spec.md:
# **Branch**: `007-state-management`
# **PR**: #7

Feature 003: Config System

# Assuming PR #7 was merged

# Step 1: Check next PR number
gh pr list --state all --limit 5
# Last PR was #7

# Step 2: Create branch
git checkout -b 008-config-system

# Step 3: Create spec directory
mkdir -p specs/003-config-system

# ... continue workflow ...

Reference

Quick Commands

# Check next PR number
gh pr list --state all --json number --jq 'max_by(.number).number + 1'

# Create new branch (replace XXX and feature-name)
git checkout -b XXX-feature-name

# View PR by number
gh pr view 007

# List all branches with PR pattern
git branch -a | grep -E '^[0-9]{3}-'

Related Documentation

Convention Owner: @arc-framework/maintainers Last Updated: 2025-12-27 Next Review: 2025-03-20