# RSpade Framework Updates

## NAME

rsx_upstream - Managing RSpade framework updates from upstream

## SYNOPSIS

Updating the RSpade framework while preserving your application code:

    php artisan rsx:framework:pull

## DESCRIPTION

The RSpade framework is distributed as a git repository that receives regular
updates with bug fixes, new features, and improvements. The framework update
system allows you to pull these updates while preserving your application code
in the ./rsx directory.

## COMMAND

### php artisan rsx:framework:pull

Pulls RSpade framework updates from upstream repository.

**What it does:**
- Fetches latest changes from `rspade_upstream` remote
- Merges framework updates into your local repository
- Preserves `./rsx` directory completely unchanged
- Cleans and rebuilds the manifest
- Recompiles all bundles

**Safety features:**
- Shows what files will be updated before proceeding
- Requires confirmation before applying updates
- Fails loud on merge conflicts
- Never modifies ./rsx directory

**No git cleanliness checks:**
- ./rsx is never tracked by framework repository
- Framework files are read-only in application development mode
- You may WANT to update broken framework files
- Update will fail loud on real conflicts

**Usage:**

    php artisan rsx:framework:pull

**Time required:**
Framework updates take 2-5 minutes to complete, including:
- Pulling latest framework code from upstream
- Cleaning and rebuilding the manifest
- Recompiling all bundles
- Updating dependencies

## GIT MERGE PROTECTION

The framework is configured to always preserve your ./rsx directory during
updates, even if upstream has historical commits containing ./rsx files.

**How it works:**

1. **`.gitignore` excludes ./rsx** - Framework doesn't track ./rsx changes
2. **`.gitattributes` merge strategy** - `/rsx/** merge=ours` ensures your
   version is always kept during merges
3. **Defense-in-depth** - `rsx:framework:pull` explicitly preserves ./rsx

**Why this matters:**

The upstream framework repository may have historical commits with ./rsx files
(demo applications, examples, etc.). Without merge protection, git merge could
attempt to merge those changes into your application code. The multi-layer
protection ensures your ./rsx directory is never touched by framework updates.

## REMOTE CONFIGURATION

Framework updates require a git remote named `rspade_upstream` pointing to the
RSpade framework repository.

**Check current remotes:**

    git remote -v

**Expected output:**

    rspade_upstream  <upstream-url> (fetch)
    rspade_upstream  <upstream-url> (push)

**Add upstream remote if missing:**

    git remote add rspade_upstream <upstream-url>

## TYPICAL WORKFLOW

### Regular Framework Updates

    # Check for updates
    git fetch rspade_upstream
    git log HEAD..rspade_upstream/master

    # Pull framework updates
    php artisan rsx:framework:pull

    # Test your application
    php artisan rsx:check
    # Run your tests

    # Commit if framework changes were applied
    git add -A
    git commit -m "Update RSpade framework to latest version"

### Handling Merge Conflicts

If framework updates conflict with local changes:

    # During rsx:framework:pull
    ERROR: Merge conflict detected

    # View conflicted files
    git status

    # Resolve conflicts manually
    nano path/to/conflicted/file.php

    # Mark as resolved
    git add path/to/conflicted/file.php

    # Complete the merge
    git commit -m "Merge framework updates, resolved conflicts"

    # Rebuild framework
    php artisan rsx:clean
    php artisan rsx:manifest:build

## FORKING THE FRAMEWORK

The framework update system assumes the RSpade framework code remains managed
by upstream and updated automatically. This is recommended for most developers.

If you need to modify framework internals or customize the Laravel foundation,
you can take full ownership of the entire codebase:

    php artisan rsx:man framework_fork

This documents:
- When and why to fork the framework
- How to maintain a forked framework
- Procedures for manually merging upstream updates
- Trade-offs between managed updates and full control

**Consider forking only if:**
- You need to modify RSpade core functionality
- You want to customize Laravel foundation
- You're building deep framework integrations
- You're willing to manually maintain framework modifications

## TROUBLESHOOTING

### "Remote rspade_upstream not configured"

Add the upstream remote:

    git remote add rspade_upstream <upstream-url>

### "Framework is in forked mode"

You have created a `.rspade-forked-framework` marker file indicating you've
taken full ownership of the framework codebase. Automatic updates are disabled
to prevent overwriting your modifications.

To manually update from upstream:

    git fetch rspade_upstream
    git diff rspade_upstream/master
    # Manually merge desired changes
    # Test thoroughly

For detailed procedures:

    php artisan rsx:man framework_fork

### Merge conflicts every update

Your local changes to framework files conflict with upstream changes frequently.

**Solutions:**

1. **Minimize framework modifications** - Keep changes to ./rsx only
2. **Fork the framework** - Take full control (see framework_fork)
3. **Reset local changes** - Discard modifications and re-apply after update

### Updates take too long / timeout

Framework updates include rebuilding manifest and recompiling bundles, which
can take 2-5 minutes. Ensure sufficient timeout when running the command.

For LLM agents: Use 5-minute timeout when executing framework updates.

## FOR FRAMEWORK DEVELOPERS

When distributing RSpade:

1. Ensure `.gitignore` excludes ./rsx directory
2. Configure `.gitattributes` with `/rsx/** merge=ours`
3. Set up `merge.ours.driver` git config
4. Document the framework update workflow
5. Provide upstream repository URL to users

## FOR APPLICATION DEVELOPERS

When using RSpade:

1. Clone or receive RSpade framework
2. Configure `rspade_upstream` remote
3. Work entirely in ./rsx directory
4. Update framework regularly with `php artisan rsx:framework:pull`
5. Never modify files outside ./rsx (unless forking)

Your ./rsx directory is independent and can be:
- Pushed to your own git repository
- Deployed independently
- Shared with your team
- Managed with standard git workflows

## SEE ALSO

framework_fork(7) - Forking the framework for custom modifications
rsx_architecture(7) - RSX application structure
coding_standards(7) - RSpade development conventions