chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,334 @@
|
||||
---
|
||||
summary: "Fork setup: remote configuration and multi-upstream workflow."
|
||||
read_when:
|
||||
- Setting up fork remotes
|
||||
- Syncing with upstreams
|
||||
---
|
||||
|
||||
# Fork Setup & Initial Configuration
|
||||
|
||||
**One-time setup for managing your CodexBar fork with multiple upstreams**
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Setup
|
||||
|
||||
### Step 1: Configure Git Remotes
|
||||
|
||||
```bash
|
||||
# Verify your fork is origin
|
||||
git remote -v
|
||||
# Should show: origin git@github.com: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 git@github.com:topoffunnel/CodexBar.git (fetch/push)
|
||||
# upstream https://github.com/steipete/CodexBar.git (fetch/push)
|
||||
# quotio https://github.com/nguyenphutrong/quotio.git (fetch/push)
|
||||
```
|
||||
|
||||
### Step 2: Test Automation Scripts
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
### Step 3: Initial Upstream Review
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
### Step 4: Initial Quotio Analysis
|
||||
|
||||
```bash
|
||||
# Analyze quotio repository
|
||||
./Scripts/analyze_quotio.sh
|
||||
|
||||
# Creates: quotio-analysis-YYYYMMDD.md
|
||||
# Review the file for interesting patterns
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Critical Discovery: Upstream Removed Augment
|
||||
|
||||
**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:**
|
||||
- ✅ Your fork preserves Augment support
|
||||
- ✅ You can continue developing Augment features
|
||||
- ✅ Upstream changes won't break your Augment work
|
||||
- ✅ You maintain features important to your users
|
||||
|
||||
**Action Required:**
|
||||
When syncing with upstream, you'll need to:
|
||||
1. Cherry-pick valuable changes (Vertex AI improvements, bug fixes)
|
||||
2. **Avoid** merging commits that remove Augment
|
||||
3. Keep your Augment implementation separate
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Regular Workflow
|
||||
|
||||
### Weekly Upstream Check (Recommended: Monday)
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
```
|
||||
|
||||
### Weekly Quotio Review (Recommended: Thursday)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Selective Sync Strategy
|
||||
|
||||
### What to Sync from Upstream
|
||||
|
||||
✅ **DO sync:**
|
||||
- Bug fixes (non-Augment)
|
||||
- Performance improvements
|
||||
- New provider support (Vertex AI, etc.)
|
||||
- Documentation improvements
|
||||
- Test improvements
|
||||
- Dependency updates
|
||||
|
||||
❌ **DON'T sync:**
|
||||
- Augment provider removal
|
||||
- Changes that conflict with fork features
|
||||
- Breaking changes without careful review
|
||||
|
||||
### How to Cherry-Pick Selectively
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Quotio Pattern Learning
|
||||
|
||||
### Ethical Guidelines
|
||||
|
||||
**DO:**
|
||||
- ✅ Analyze their architecture and patterns
|
||||
- ✅ Learn from their UX decisions
|
||||
- ✅ Understand their approach to problems
|
||||
- ✅ Implement similar concepts independently
|
||||
- ✅ Credit inspiration in commits
|
||||
|
||||
**DON'T:**
|
||||
- ❌ Copy code verbatim
|
||||
- ❌ Use their assets or branding
|
||||
- ❌ Violate their license
|
||||
- ❌ Claim their work as yours
|
||||
|
||||
### Analysis Workflow
|
||||
|
||||
```bash
|
||||
# 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."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Contributing to Upstream
|
||||
|
||||
### When to Contribute
|
||||
|
||||
**Good candidates:**
|
||||
- Universal bug fixes
|
||||
- Performance improvements
|
||||
- Documentation improvements
|
||||
- Test coverage
|
||||
- Provider enhancements (non-fork-specific)
|
||||
|
||||
**Keep in fork:**
|
||||
- Augment provider (they removed it)
|
||||
- Multi-account management (major change)
|
||||
- Fork branding
|
||||
- Experimental features
|
||||
|
||||
### Contribution Workflow
|
||||
|
||||
```bash
|
||||
# 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
|
||||
make 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Automated Monitoring
|
||||
|
||||
### GitHub Actions Setup
|
||||
|
||||
The workflow `.github/workflows/upstream-monitor.yml` will:
|
||||
- Run Monday and Thursday at 9 AM UTC
|
||||
- Check for new commits in both upstreams
|
||||
- Create/update GitHub issue with summary
|
||||
- Provide links to review changes
|
||||
|
||||
**To enable:**
|
||||
1. Push the workflow file to your fork
|
||||
2. Enable GitHub Actions in repository settings
|
||||
3. Issues will be created automatically
|
||||
|
||||
**Manual trigger:**
|
||||
```bash
|
||||
# Via GitHub UI: Actions → Monitor Upstream Changes → Run workflow
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Verification Checklist
|
||||
|
||||
After setup, verify:
|
||||
|
||||
- [ ] All three remotes configured (origin, upstream, quotio)
|
||||
- [ ] Scripts are executable
|
||||
- [ ] `./Scripts/check_upstreams.sh` runs successfully
|
||||
- [ ] Can create review branch with `./Scripts/review_upstream.sh`
|
||||
- [ ] Can analyze quotio with `./Scripts/analyze_quotio.sh`
|
||||
- [ ] GitHub Actions workflow is present
|
||||
- [ ] Understand Augment removal in upstream
|
||||
- [ ] Know how to cherry-pick selectively
|
||||
- [ ] Know when to contribute upstream vs keep in fork
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Next Steps
|
||||
|
||||
1. **Review Current Upstream Changes**
|
||||
```bash
|
||||
./Scripts/review_upstream.sh upstream
|
||||
```
|
||||
|
||||
2. **Decide on Sync Strategy**
|
||||
- Which commits to cherry-pick?
|
||||
- How to handle Augment removal?
|
||||
- See `docs/UPSTREAM_STRATEGY.md`
|
||||
|
||||
3. **Start Quotio Analysis**
|
||||
```bash
|
||||
./Scripts/analyze_quotio.sh
|
||||
# Then edit docs/QUOTIO_ANALYSIS.md
|
||||
```
|
||||
|
||||
4. **Update Fork Roadmap**
|
||||
- Review `docs/FORK_ROADMAP.md`
|
||||
- Adjust based on upstream changes
|
||||
- Plan fork-specific features
|
||||
|
||||
---
|
||||
|
||||
**Setup Complete!** You now have a robust system for managing your fork while learning from multiple sources.
|
||||
Reference in New Issue
Block a user