docs/FORK_SETUP.md
One-time setup for managing your CodexBar fork with multiple upstreams
# Verify your fork is origin
git remote -v
# Should show: origin [email protected]:topoffunnel/CodexBar.git
# Add upstream (steipete's original)
git remote add upstream https://github.com/steipete/CodexBar.git
# Add quotio (inspiration source)
git remote add quotio https://github.com/nguyenphutrong/quotio.git
# Fetch all remotes
git fetch --all
# Verify setup
git remote -v
# Should show:
# origin [email protected]:topoffunnel/CodexBar.git (fetch/push)
# upstream https://github.com/steipete/CodexBar.git (fetch/push)
# quotio https://github.com/nguyenphutrong/quotio.git (fetch/push)
# Make scripts executable (if not already)
chmod +x Scripts/*.sh
# Test upstream monitoring
./Scripts/check_upstreams.sh
# Should show:
# - Number of new commits in upstream
# - Number of new commits in quotio
# - File change summary
# Check what's new in upstream
./Scripts/check_upstreams.sh upstream
# Review changes in detail
./Scripts/review_upstream.sh upstream
# This creates a review branch: upstream-sync/upstream-YYYYMMDD
# Analyze quotio repository
./Scripts/analyze_quotio.sh
# Creates: quotio-analysis-YYYYMMDD.md
# Review the file for interesting patterns
IMPORTANT: Upstream (steipete) has removed the Augment provider in recent commits!
Files changed:
.../Providers/Augment/AugmentStatusProbe.swift | 627 deletions
Tests/CodexBarTests/AugmentStatusProbeTests.swift | 88 deletions
This validates our fork strategy:
Action Required: When syncing with upstream, you'll need to:
# Check for new changes
./Scripts/check_upstreams.sh
# If changes found, review them
./Scripts/review_upstream.sh upstream
# Cherry-pick valuable commits (skip Augment removal)
git cherry-pick <commit-hash>
# Test
./Scripts/compile_and_run.sh
# Merge to main
git checkout main
git merge upstream-sync/upstream-$(date +%Y%m%d)
# Analyze recent quotio changes
./Scripts/analyze_quotio.sh
# Review specific files of interest
git show quotio/main:path/to/interesting/file.swift
# Document patterns in docs/QUOTIO_ANALYSIS.md
ā DO sync:
ā DON'T sync:
# Review upstream commits
git log --oneline main..upstream/main
# Example output:
# 001019c style: fix swiftformat violations ā
SYNC
# e4f1e4c feat(vertex): add token cost tracking ā
SYNC
# 202efde fix(vertex): disable double-counting ā
SYNC
# 0c2f888 docs: add Vertex AI documentation ā
SYNC
# 3c4ca30 feat(vertexai): token cost tracking ā
SYNC
# abc123d refactor: remove Augment provider ā SKIP
# Cherry-pick the good ones
git cherry-pick 001019c
git cherry-pick e4f1e4c
git cherry-pick 202efde
git cherry-pick 0c2f888
git cherry-pick 3c4ca30
# Skip abc123d (Augment removal)
DO:
DON'T:
# 1. Fetch latest quotio
git fetch quotio
# 2. Analyze structure
./Scripts/analyze_quotio.sh
# 3. Review specific areas
git show quotio/main:path/to/AccountManager.swift
# 4. Document patterns (not code!)
# Edit docs/QUOTIO_ANALYSIS.md
# 5. Implement independently
# Create feature branch
git checkout -b quotio-inspired/multi-account
# 6. Commit with attribution
git commit -m "feat: multi-account management
Inspired by quotio's account switching pattern:
https://github.com/nguyenphutrong/quotio/...
Implemented independently using CodexBar architecture."
Good candidates:
Keep in fork:
# 1. Prepare clean branch from upstream
./Scripts/prepare_upstream_pr.sh fix-cursor-bonus
# 2. Cherry-pick your fix (without fork branding)
git cherry-pick <your-commit-hash>
# 3. Review - ensure no fork-specific code
git diff upstream/main
# 4. Test
swift test
# 5. Push to your fork
git push origin upstream-pr/fix-cursor-bonus
# 6. Create PR on GitHub
# Go to: https://github.com/steipete/CodexBar
# Click "New Pull Request"
# Select: base: steipete:main <- compare: topoffunnel:upstream-pr/fix-cursor-bonus
The workflow .github/workflows/upstream-monitor.yml will:
To enable:
Manual trigger:
# Via GitHub UI: Actions ā Monitor Upstream Changes ā Run workflow
After setup, verify:
./Scripts/check_upstreams.sh runs successfully./Scripts/review_upstream.sh./Scripts/analyze_quotio.shReview Current Upstream Changes
./Scripts/review_upstream.sh upstream
Decide on Sync Strategy
docs/UPSTREAM_STRATEGY.mdStart Quotio Analysis
./Scripts/analyze_quotio.sh
# Then edit docs/QUOTIO_ANALYSIS.md
Update Fork Roadmap
docs/FORK_ROADMAP.mdSetup Complete! You now have a robust system for managing your fork while learning from multiple sources.