rspade_system/docs/framework_upstream.md

Framework Upstream Synchronization

This document explains how to keep your RSpade project synchronized with framework updates.

Overview

When you create a new project from the RSpade framework template, you get your own Git repository for your project-specific code. However, you'll also want to pull in framework updates and improvements over time. This is managed through Git's upstream remote functionality.

Initial Setup

When starting a new project from this template:

1. Clone/fork this template to create your project repository
2. Change the origin to your project's repository:

   git remote set-url origin git@your-server:your-project.git
   

3. Setup framework upstream:

   bin/framework-upstream setup
   

This configures ssh://git@192.168.0.3:3322/brianhansonxyz/rspade-publish.git as the framework-upstream remote.

Workflow

Check for Updates

Check if framework updates are available:

bin/framework-upstream status

This shows:

• Whether you're up to date with the framework
• How many commits ahead/behind you are
• If your project has diverged from the framework

Pull Framework Updates

To merge framework updates into your project:

bin/framework-upstream pull

This will:

1. Fetch the latest framework changes
2. Attempt to merge them into your current branch
3. Report any conflicts that need manual resolution

View Framework Changes

See recent framework commits:

bin/framework-upstream logs

View differences between your project and the framework:

bin/framework-upstream diff

Handling Conflicts

When pulling framework updates, you may encounter merge conflicts if you've modified framework files. This is normal and expected.

Common Conflict Areas

• CLAUDE.md - If you've customized AI directives
• config/ files - If you've modified framework configuration
• .gitignore - If you've added project-specific ignores

Resolution Strategy

1. Review the conflicts carefully
2. Keep your project-specific changes where appropriate
3. Accept framework improvements where they don't conflict with your customizations
4. Test thoroughly after resolving conflicts

Conflict Commands

During a merge conflict:

# See which files have conflicts
git status

# After resolving conflicts in a file
git add <resolved-file>

# Complete the merge
git commit

# Or abort if needed
git merge --abort

Best Practices

1. Minimize Framework Modifications

• Work primarily in /rsx/ for your application code
• Avoid modifying /app/RSpade/ framework files
• Use configuration files for customization when possible

2. Regular Updates

• Check for updates weekly: bin/framework-upstream status
• Pull updates regularly to avoid large divergences
• Test thoroughly after each update

3. Document Customizations

If you must modify framework files:

• Document the changes in your project README
• Consider if the change should be contributed back to the framework
• Keep modifications minimal and well-commented

4. Commit Before Updating

Always commit your changes before pulling framework updates:

git add -A
git commit -m "Save work before framework update"
bin/framework-upstream pull

Framework Update Types

Patch Updates

• Bug fixes
• Security patches
• Documentation improvements
• Usually safe to pull immediately

Feature Updates

• New framework capabilities
• New helper functions
• Enhanced commands
• Review changes before pulling

Breaking Changes

• Rare but possible
• Will be documented in framework commits
• May require code changes in your project

Troubleshooting

"Not in a git repository"

Ensure you're in your project root directory

"Upstream not configured"

Run: bin/framework-upstream setup

"You have uncommitted changes"

Commit or stash your changes before pulling:

git add -A && git commit -m "WIP"
# or
git stash

Merge conflicts persist

Consider:

1. Understanding what changed in the framework
2. Reviewing your local modifications
3. Potentially refactoring to reduce conflicts

Manual Git Commands

The bin/framework-upstream script automates these Git commands:

# Add upstream remote manually
git remote add framework-upstream ssh://git@192.168.0.3:3322/brianhansonxyz/rspade-publish.git

# Fetch updates
git fetch framework-upstream

# Merge updates
git merge framework-upstream/master

# Check status
git log HEAD..framework-upstream/master --oneline

Contributing Back

If you make improvements that would benefit all RSpade projects:

1. Consider contributing them back to the framework
2. Create a clean branch with just the framework improvements
3. Submit a pull request to the framework repository

Support

For framework update issues:

• Check the framework repository for announcements
• Review recent commits for breaking changes
• Test in a development environment first