wehub/steipete--codexbar
1
0
Fork 0
Code Issues Pull Requests Actions 1 Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
steipete--codexbar/docs/UPSTREAM_STRATEGY.md
T
wehub-resource-sync fc4fcbab58 chore: import upstream snapshot with attribution
2026-07-13 12:22:33 +08:00

16 KiB
Raw Permalink Blame History

summary, read_when
summary read_when
Upstream strategy for forks: remotes, cherry-picks, and contribution policy.
Managing fork/upstream workflow
Planning contributions or syncs

Multi-Upstream Fork Management Strategy

Fork: topoffunnel/CodexBar
Upstream 1: steipete/CodexBar (original)
Upstream 2: nguyenphutrong/quotio (inspiration source)

🎯 Core Principles

Fork Independence

  • Your fork is the primary development target
  • Upstream contributions are optional and selective
  • You retain full credit for your innovations
  • Fork-specific features stay in the fork

Selective Contribution

  • Only contribute universally beneficial changes upstream
  • Keep attribution-sensitive improvements in fork
  • Submit small, focused PRs to increase merge likelihood
  • Don't contribute fork branding or identity

Best-of-Both-Worlds

  • Monitor both upstreams for valuable changes
  • Cherry-pick features that enhance your fork
  • Adapt patterns without copying code
  • Credit sources appropriately

🌳 Git Repository Structure

Remote Configuration

# Your fork (origin)
git remote add origin git@github.com:topoffunnel/CodexBar.git

# Original upstream (steipete)
git remote add upstream git@github.com:steipete/CodexBar.git

# Quotio inspiration source
git remote add quotio git@github.com:nguyenphutrong/quotio.git

# Verify remotes
git remote -v

Branch Strategy

main (your fork's stable branch)
├── feature/* (fork-specific features)
├── upstream-sync/* (tracking upstream changes)
├── quotio-inspired/* (features inspired by quotio)
└── upstream-pr/* (branches for upstream PRs)

Branch Types:

  • main - Your fork's stable release branch
  • feature/* - Fork-specific development
  • upstream-sync/* - Temporary branches for reviewing upstream changes
  • quotio-inspired/* - Features adapted from quotio patterns
  • upstream-pr/* - Clean branches for upstream contributions

🔄 Workflow 1: Monitoring Upstream Changes

Daily/Weekly Sync Check

#!/bin/bash
# Scripts/check_upstreams.sh

echo "==> Fetching upstream changes..."
git fetch upstream
git fetch quotio

echo ""
echo "==> Upstream (steipete) changes:"
git log --oneline main..upstream/main --no-merges | head -20

echo ""
echo "==> Quotio changes:"
git log --oneline --all --remotes=quotio/main --since="1 week ago" | head -20

echo ""
echo "==> Files changed in upstream:"
git diff --stat main..upstream/main

echo ""
echo "==> Files changed in quotio (recent):"
git diff --stat quotio/main~10..quotio/main

Automated Monitoring (GitHub Actions)

Create .github/workflows/upstream-monitor.yml:

name: Monitor Upstreams

on:
  schedule:
    - cron: '0 9 * * 1,4'  # Monday and Thursday at 9 AM
  workflow_dispatch:

jobs:
  check-upstream:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Add upstream remotes
        run: |
          git remote add upstream https://github.com/steipete/CodexBar.git
          git remote add quotio https://github.com/nguyenphutrong/quotio.git
          git fetch upstream
          git fetch quotio
      
      - name: Check for new commits
        id: check
        run: |
          UPSTREAM_NEW=$(git log --oneline main..upstream/main --no-merges | wc -l)
          QUOTIO_NEW=$(git log --oneline --all --remotes=quotio/main --since="1 week ago" | wc -l)
          
          echo "upstream_commits=$UPSTREAM_NEW" >> $GITHUB_OUTPUT
          echo "quotio_commits=$QUOTIO_NEW" >> $GITHUB_OUTPUT
      
      - name: Create issue if changes detected
        if: steps.check.outputs.upstream_commits > 0 || steps.check.outputs.quotio_commits > 0
        uses: actions/github-script@v7
        with:
          script: |
            const upstreamCommits = '${{ steps.check.outputs.upstream_commits }}';
            const quotioCommits = '${{ steps.check.outputs.quotio_commits }}';
            
            const body = `## Upstream Changes Detected
            
            **steipete/CodexBar:** ${upstreamCommits} new commits
            **quotio:** ${quotioCommits} new commits (last week)
            
            Review changes:
            - [steipete commits](https://github.com/steipete/CodexBar/compare/main...upstream/main)
            - [quotio commits](https://github.com/nguyenphutrong/quotio/commits/main)
            
            Run \`./Scripts/review_upstream.sh\` to analyze changes.`;
            
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: 'Upstream Changes Available',
              body: body,
              labels: ['upstream-sync']
            });

🔍 Workflow 2: Reviewing & Incorporating Changes

Step 1: Review Upstream Changes

#!/bin/bash
# Scripts/review_upstream.sh

UPSTREAM=${1:-upstream}  # 'upstream' or 'quotio'

echo "==> Creating review branch for $UPSTREAM..."
git checkout main
git checkout -b upstream-sync/$UPSTREAM-$(date +%Y%m%d)

echo "==> Fetching latest..."
git fetch $UPSTREAM

echo "==> Showing commits to review:"
git log --oneline --graph main..$UPSTREAM/main | head -30

echo ""
echo "==> Detailed diff:"
git diff main..$UPSTREAM/main --stat

echo ""
echo "Next steps:"
echo "1. Review commits: git log -p main..$UPSTREAM/main"
echo "2. Cherry-pick specific commits: git cherry-pick <commit-hash>"
echo "3. Or merge all: git merge $UPSTREAM/main"
echo "4. Test thoroughly"
echo "5. Merge to main: git checkout main && git merge upstream-sync/$UPSTREAM-$(date +%Y%m%d)"

Step 2: Selective Cherry-Picking

# Review individual commits
git log -p main..upstream/main

# Cherry-pick specific valuable commits
git cherry-pick <commit-hash>

# If conflicts, resolve and continue
git cherry-pick --continue

# Or abort if not suitable
git cherry-pick --abort

Step 3: Quotio Pattern Adaptation

# Create inspiration branch
git checkout -b quotio-inspired/feature-name

# View quotio implementation (read-only)
git show quotio/main:path/to/file.swift

# Implement similar pattern in your codebase
# (write your own code, don't copy)

# Commit with attribution
git commit -m "feat: implement feature inspired by quotio

Inspired by quotio's approach to [feature]:
https://github.com/nguyenphutrong/quotio/commit/abc123

Implemented independently with CodexBar-specific patterns."

📤 Workflow 3: Contributing to Upstream

Identifying Upstream-Suitable Changes

✅ Good for Upstream:

  • Bug fixes that affect all users
  • Performance improvements
  • Provider enhancements (non-fork-specific)
  • Documentation improvements
  • Test coverage additions
  • Dependency updates

❌ Keep in Fork:

  • Fork branding/attribution
  • Multi-account management (major architectural change)
  • Fork-specific UI customizations
  • Experimental features
  • topoffunnel.com-specific integrations

Creating Upstream PR Branch

#!/bin/bash
# Scripts/prepare_upstream_pr.sh

FEATURE_NAME=$1

if [ -z "$FEATURE_NAME" ]; then
  echo "Usage: ./Scripts/prepare_upstream_pr.sh <feature-name>"
  exit 1
fi

echo "==> Creating upstream PR branch..."
git checkout upstream/main
git checkout -b upstream-pr/$FEATURE_NAME

echo "==> Branch created: upstream-pr/$FEATURE_NAME"
echo ""
echo "Next steps:"
echo "1. Cherry-pick your commits (without fork branding)"
echo "2. Remove any fork-specific code"
echo "3. Ensure tests pass"
echo "4. Push: git push origin upstream-pr/$FEATURE_NAME"
echo "5. Create PR to steipete/CodexBar from GitHub UI"

Cleaning Commits for Upstream

# Start from upstream's main
git checkout upstream/main
git checkout -b upstream-pr/fix-cursor-bonus

# Cherry-pick your fix (without fork branding)
git cherry-pick <your-commit-hash>

# If commit includes fork branding, amend it
git commit --amend

# Remove fork-specific changes
git reset HEAD~1
# Manually stage only upstream-suitable changes
git add <files>
git commit -m "fix: correct Cursor bonus credits calculation

Fixes issue where bonus credits were incorrectly calculated.

Tested with multiple account types."

# Push to your fork
git push origin upstream-pr/fix-cursor-bonus

# Create PR to steipete/CodexBar via GitHub UI

🏷️ Commit Message Strategy

Fork Commits (Keep Everything)

feat: add multi-account management for Augment

Implements account switching UI and storage.
Fork-specific feature for topoffunnel.com users.

Co-authored-by: Brandon Charleson <brandon@topoffunnel.com>

Upstream-Bound Commits (Generic)

fix: correct Cursor bonus credits calculation

The bonus credits were being added instead of subtracted
from the total usage calculation.

Tested with Pro and Team accounts.

Quotio-Inspired Commits (Attribution)

feat: implement session persistence inspired by quotio

Adds automatic session restoration on app restart.

Inspired by quotio's approach:
https://github.com/nguyenphutrong/quotio/blob/main/...

Implemented independently using CodexBar patterns.

📋 Decision Matrix: What Goes Where?

Change Type Fork Upstream Notes
Bug fix (universal) ✅ ✅ Submit to upstream
Bug fix (fork-specific) ✅ ❌ Keep in fork
Performance improvement ✅ ✅ Submit to upstream
New provider support ✅ ✅ Submit to upstream
Provider enhancement ✅ Maybe Depends on scope
UI improvement (generic) ✅ ✅ Submit to upstream
UI improvement (fork brand) ✅ ❌ Keep in fork
Multi-account feature ✅ ❌ Too large for upstream
Documentation ✅ ✅ Submit to upstream
Tests ✅ ✅ Submit to upstream
Fork branding ✅ ❌ Never upstream
Experimental feature ✅ ❌ Prove it first

🔐 Protecting Your Attribution

Separate Commits Strategy

# Make changes in feature branch
git checkout -b feature/my-improvement

# Commit 1: Core improvement (upstream-suitable)
git add Sources/CodexBarCore/...
git commit -m "feat: improve cookie handling"

# Commit 2: Fork-specific enhancements
git add Sources/CodexBar/About.swift
git commit -m "feat: add fork attribution for improvement"

# Merge to main (both commits)
git checkout main
git merge feature/my-improvement

# For upstream PR: cherry-pick only commit 1
git checkout upstream/main
git checkout -b upstream-pr/cookie-handling
git cherry-pick <commit-1-hash>  # Only the core improvement

Maintaining Fork Identity

Keep these files fork-specific (never upstream):

  • Sources/CodexBar/About.swift (your attribution)
  • Sources/CodexBar/PreferencesAboutPane.swift (fork sections)
  • README.md (fork notice)
  • docs/FORK_*.md (fork documentation)
  • FORK_STATUS.md

🤖 Automation Scripts

All automation scripts are located in Scripts/:

  • check_upstreams.sh - Check for new commits in both upstreams
  • review_upstream.sh - Create review branch for upstream changes
  • prepare_upstream_pr.sh - Prepare clean branch for upstream PR
  • analyze_quotio.sh - Analyze quotio for patterns and features

GitHub Actions workflow: .github/workflows/upstream-monitor.yml

📖 Practical Examples

Example 1: Weekly Upstream Check

# Monday morning routine
./Scripts/check_upstreams.sh

# If changes found, review them
./Scripts/review_upstream.sh upstream

# Cherry-pick valuable commits
git cherry-pick abc123
git cherry-pick def456

# Test
./Scripts/compile_and_run.sh

# Merge to main
git checkout main
git merge upstream-sync/upstream-20260104

Example 2: Contributing Bug Fix Upstream

# You fixed a bug in your fork
git log --oneline -5
# abc123 fix: correct Cursor bonus credits
# def456 feat: add fork attribution

# Prepare upstream PR (only the fix, not attribution)
./Scripts/prepare_upstream_pr.sh fix-cursor-bonus

# Cherry-pick only the fix
git cherry-pick abc123

# Review - ensure no fork branding
git diff upstream/main

# Push and create PR
git push origin upstream-pr/fix-cursor-bonus
# Then create PR on GitHub to steipete/CodexBar

Example 3: Learning from Quotio

# Analyze quotio
./Scripts/analyze_quotio.sh

# Review their multi-account implementation
git show quotio/main:path/to/AccountManager.swift

# Document patterns in docs/QUOTIO_ANALYSIS.md
# Then implement independently in your fork

# Commit with attribution
git commit -m "feat: implement multi-account management

Inspired by quotio's account switching pattern:
https://github.com/nguyenphutrong/quotio/...

Implemented independently using CodexBar's architecture."

🎓 Best Practices

For Fork Development

  1. Commit often - Small, focused commits
  2. Separate concerns - Fork branding in separate commits
  3. Test thoroughly - Every change
  4. Document decisions - Why you chose this approach
  5. Credit sources - When inspired by others

For Upstream Contributions

  1. Start small - Bug fixes before features
  2. One thing per PR - Focused changes
  3. Follow their style - Match upstream conventions
  4. Include tests - Prove it works
  5. Be patient - Maintainers are busy

For Multi-Upstream Sync

  1. Check weekly - Stay current
  2. Review carefully - Understand before merging
  3. Test everything - Upstream changes may break your fork
  4. Document conflicts - How you resolved them
  5. Keep attribution - Credit all sources

🔧 Troubleshooting

Merge Conflicts

# During upstream merge
git merge upstream/main
# CONFLICT in Sources/CodexBar/About.swift

# Keep your fork version for branding files
git checkout --ours Sources/CodexBar/About.swift
git add Sources/CodexBar/About.swift

# Merge other files manually
# Then continue
git commit

Accidentally Pushed Fork Branding to Upstream PR

# Oops! Pushed fork branding to upstream PR branch
git checkout upstream-pr/my-feature

# Reset to before the bad commit
git reset --hard HEAD~1

# Re-apply changes without branding
# ... make changes ...
git commit -m "fix: proper commit"

# Force push (only safe on PR branches)
git push origin upstream-pr/my-feature --force

Lost Track of Upstream Changes

# See what you've merged from upstream
git log --oneline --graph --all --grep="upstream"

# See what's still pending
git log --oneline main..upstream/main

# Create a tracking branch
git checkout -b upstream-tracking upstream/main
git log --oneline upstream-tracking..main

📊 Success Metrics

Fork Health

  • ✅ Builds without errors
  • ✅ All tests passing
  • ✅ No regressions from upstream merges
  • ✅ Fork-specific features working
  • ✅ Documentation up to date

Upstream Relationship

  • ✅ PRs are small and focused
  • ✅ PRs get merged (or constructive feedback)
  • ✅ Maintain good relationship with maintainer
  • ✅ Credit given appropriately
  • ✅ No fork branding in upstream PRs

Multi-Source Learning

  • ✅ Regular upstream monitoring
  • ✅ Quotio patterns documented
  • ✅ Independent implementations
  • ✅ Proper attribution
  • ✅ Best-of-both-worlds achieved

🗓️ Recommended Schedule

Weekly

  • Monday: Check upstreams (./Scripts/check_upstreams.sh)
  • Thursday: Review quotio (./Scripts/analyze_quotio.sh)

Monthly

  • Review upstream PRs you submitted
  • Update QUOTIO_ANALYSIS.md with new findings
  • Sync with upstream main
  • Update fork documentation

Quarterly

  • Major feature planning
  • Upstream contribution strategy review
  • Fork roadmap update
  • Community engagement

📞 Getting Help

Upstream Issues

  • Check their issue tracker first
  • Ask in discussions if available
  • Be respectful and patient
  • Provide minimal reproduction

Fork Issues

  • Document in your fork's issues
  • Reference upstream if relevant
  • Track in FORK_STATUS.md
  • Update roadmap as needed

Quotio Questions

  • Review their documentation
  • Check their issue tracker
  • Don't ask them to help with your fork
  • Credit them when you adapt patterns

Remember: Your fork is independent. Upstream contributions are optional. Learn from others, but implement independently. Credit sources appropriately.

Reference in New Issue View Git Blame Copy Permalink