# Forking the RSpade Framework

## NAME

framework_fork - Taking full ownership of the RSpade framework codebase

## SYNOPSIS

Breaking out of managed project mode to directly modify framework code:

    # Mark framework as forked
    touch .rspade-forked-framework

    # Switch to selfupdate branch (no demo rsx)
    git fetch rspade_upstream
    git checkout -B rspade_selfupdate rspade_upstream/rspade_selfupdate --force

    # Your ./rsx remains independent
    # Framework files are now yours to modify

## DESCRIPTION

RSpade offers two development approaches:

1. **Project Mode** (managed) - Framework is read-only, updated automatically
2. **Forked Framework** (full control) - Entire codebase is yours to modify

This document covers forked framework mode for developers who need to customize
framework internals or integrate deeply with Laravel.

## RSPADE'S RELATIONSHIP TO LARAVEL

RSpade is built within Laravel with minimal divergence:

- Laravel framework provides the foundation (Illuminate ORM, routing, etc.)
- RSpade-specific code isolated in `app/RSpade/`
- Application code lives in `./rsx` directory
- Surrounding Laravel structure meant to be pristine and replaceable

**The abstraction:**
- VB6 apps run in VB6 runtime, which runs in Windows
- RSX apps run in RSpade runtime, which runs in Laravel

**Developer experience:**
For most developers, Laravel's existence is transparent. You work in `./rsx`,
use Laravel helpers (Illuminate ORM, validation, etc.), and never touch files
outside `./rsx`. Framework updates replace everything except `./rsx`.

**But you CAN break the abstraction:**
You can write Laravel routes, controllers, commands, services directly in `./app`.
You can modify RSpade itself in `app/RSpade/`. You can customize anything.

The cost: automatic framework updates no longer work safely.

## WHEN TO FORK

**Stay in project mode if:**
- Building standard applications with RSX
- Want automatic framework updates
- Don't need to modify framework internals
- Comfortable with framework conventions

**Fork the framework if:**
- Need to modify RSpade core functionality
- Want to customize Laravel foundation
- Building deep framework integrations
- Willing to manually merge upstream changes
- Have team maintaining framework modifications

**Critical decision point:**
Once forked, you own all framework changes. Upstream updates require manual
review and merging. This is permanent divergence from managed updates.

## PROJECT MODE VS FORKED FRAMEWORK

Project Mode (managed):
    ./rsx                          - Independent git repo (your application)
    Everything else                - Managed by framework, auto-updated
    Framework modifications        - Blocked by pre-commit hooks
    Updates                        - php artisan rsx:framework:pull
    Merge conflicts                - Impossible (./rsx protected)

Forked Framework (full control):
    ./rsx                          - Independent git repo (your application)
    Everything else                - Your git repo, your modifications
    Framework modifications        - Allowed and expected
    Updates                        - Manual git merge from upstream
    Merge conflicts                - Your responsibility

**Key difference:**
Project mode: Framework is a black box, updated atomically
Forked mode: Framework is source code, you maintain modifications

## SETUP PROCEDURE

### 1. Ensure ./rsx is independent

Your ./rsx directory should already be an independent git repository:

    cd rsx
    git remote add origin <your-application-repo>
    git push -u origin master
    cd ..

Your application code must be independent before forking framework.

### 2. Create fork marker file

    touch .rspade-forked-framework

This marker:
- Disables automatic framework updates
- Signals intentional framework ownership
- Checked by update scripts

### 3. Switch to selfupdate branch

The `rspade_selfupdate` branch contains framework without demo `./rsx`:

    # Backup .env
    cp .env .env.backup

    # Fetch and switch
    git fetch rspade_upstream
    git checkout -B rspade_selfupdate rspade_upstream/rspade_selfupdate --force

    # Restore .env
    cp .env.backup .env

**Why selfupdate branch?**
- Master branch includes demo application in `./rsx`
- Selfupdate branch has no `./rsx` directory
- Prevents git conflicts with your independent `./rsx` repo
- Cleaner base for framework modifications

### 4. Verify configuration

    git branch -vv
    # Should show: * rspade_selfupdate [rspade_upstream/rspade_selfupdate]

    ls -la .rspade-forked-framework
    # File should exist

    ls -la rsx/.git
    # Directory should exist (independent repo)

### 5. Commit fork marker

    git add .rspade-forked-framework
    git commit -m "Mark framework as forked for custom modifications"

You now own the entire framework codebase.

## MAKING FRAMEWORK MODIFICATIONS

You can now modify any file outside `./rsx`:

**Common modifications:**
- `app/RSpade/` - Core RSpade functionality
- `app/Http/` - Laravel HTTP layer
- `config/` - Framework configuration
- `routes/` - Additional Laravel routes
- `app/Console/` - Laravel commands

**Example: Custom framework feature**

    # Create custom feature in RSpade core
    nano app/RSpade/Core/MyFeature/MyFeature.php

    # Commit to your fork
    git add app/RSpade/Core/MyFeature/
    git commit -m "Add custom MyFeature to RSpade core"

**The ./rsx boundary still exists:**
Your `./rsx` directory remains an independent git repository for application code.
Framework modifications go in the root repository.

## UPDATING FROM UPSTREAM

Upstream continues releasing framework improvements. You must manually merge them.

### Update procedure

    # 1. Fetch upstream changes
    git fetch rspade_upstream

    # 2. Review what changed upstream
    git log HEAD..rspade_upstream/rspade_selfupdate
    git diff HEAD..rspade_upstream/rspade_selfupdate

    # 3. Check for conflicts with your modifications
    git diff HEAD..rspade_upstream/rspade_selfupdate app/RSpade/

    # 4. Merge upstream changes
    git merge rspade_upstream/rspade_selfupdate

    # 5. Resolve any conflicts
    # Edit conflicted files, keeping your modifications where needed

    # 6. Test thoroughly
    php artisan rsx:check
    php artisan rsx:clean
    php artisan rsx:manifest:build
    php artisan rsx:bundle:compile

    # Run your application tests

    # 7. Commit merge
    git add -A
    git commit -m "Merge upstream framework updates"

### Handling merge conflicts

When upstream modifies files you've changed:

    # During merge, git will mark conflicts
    git status
    # Shows: both modified: app/RSpade/Core/Something.php

    # Edit file, resolve conflicts
    nano app/RSpade/Core/Something.php

    # Look for conflict markers:
    <<<<<<< HEAD
    Your modifications
    =======
    Upstream changes
    >>>>>>> rspade_upstream/rspade_selfupdate

    # Decide what to keep:
    # - Your changes only
    # - Upstream changes only
    # - Combination of both (most common)

    # Mark as resolved
    git add app/RSpade/Core/Something.php

### Selective merging

Don't want all upstream changes?

    # Cherry-pick specific commits
    git log rspade_upstream/rspade_selfupdate
    git cherry-pick <commit-hash>

    # Or manually copy specific files
    git checkout rspade_upstream/rspade_selfupdate -- path/to/specific/file.php

## BLOCKED OPERATIONS

Once `.rspade-forked-framework` exists:

**Blocked: php artisan rsx:framework:pull**

    ERROR: Framework is in forked mode.

    You have taken full ownership of the RSpade framework codebase.
    Automatic updates are disabled to prevent overwriting your changes.

    To manually update from upstream:
      1. git fetch rspade_upstream
      2. git diff rspade_upstream/rspade_selfupdate
      3. Manually merge desired changes
      4. Test thoroughly

    For detailed procedures: php artisan rsx:man framework_fork

Forked frameworks are permanent unless you explicitly revert to managed mode
(see "REVERTING TO PROJECT MODE" section below).

## REVERTING TO PROJECT MODE

If you want to return to managed project mode:

**⚠️ WARNING: This deletes all framework modifications**

    # 1. Stash or commit any ./rsx changes
    cd rsx
    git add -A
    git commit -m "Save application changes"
    cd ..

    # 2. Remove fork marker
    rm .rspade-forked-framework

    # 3. Hard reset to upstream
    git fetch rspade_upstream
    git reset --hard rspade_upstream/rspade_selfupdate

    # 4. Verify
    php artisan rsx:framework:pull
    # Should work again

Your framework modifications are lost. Only do this if you're certain.

## DEPLOYMENT

Forked framework requires different deployment strategy:

**Project mode deployment:**
    rsync ./rsx/ production:/var/www/html/rsx/
    ssh production 'php artisan rsx:framework:pull'

**Forked framework deployment:**
    # Deploy entire repository
    git push production master
    ssh production 'git pull origin master'
    ssh production 'php artisan rsx:clean'
    ssh production 'php artisan rsx:manifest:build'
    ssh production 'php artisan rsx:bundle:compile'

You're deploying framework changes, not just application code.

## TEAM WORKFLOW

Managing a forked framework with a team:

    # 1. Designate framework maintainer(s)
    # Only certain developers modify app/RSpade/

    # 2. Use feature branches for framework changes
    git checkout -b feature/custom-bundle-processor
    # Modify framework code
    git commit -m "Add custom bundle processor"
    git push origin feature/custom-bundle-processor

    # 3. Code review framework changes carefully
    # Framework bugs affect all team members

    # 4. Document framework modifications
    # Keep FRAMEWORK_CHANGES.md listing all divergences

    # 5. Periodically merge upstream
    # Scheduled maintenance window to merge framework updates

## TROUBLESHOOTING

### "Framework is in forked mode" error

You marked framework as forked but want automatic updates:

    rm .rspade-forked-framework
    php artisan rsx:framework:pull

### Merge conflicts every update

Your modifications conflict with upstream changes frequently:

**Option 1:** Reconsider forking
Can you achieve goals without modifying framework?

**Option 2:** Contribute upstream
Submit your modifications to RSpade project, eliminate divergence.

**Option 3:** Freeze framework version
Stop merging upstream updates, maintain fixed framework version.

### Lost track of modifications

Can't remember what you changed:

    # Show all commits since initial fork
    git log rspade_upstream/rspade_selfupdate..HEAD

    # Show diff of all modifications
    git diff rspade_upstream/rspade_selfupdate HEAD

### Want to undo specific modification

    # Revert specific commit
    git revert <commit-hash>

    # Or reset specific file to upstream
    git checkout rspade_upstream/rspade_selfupdate -- path/to/file.php

## BEST PRACTICES

1. **Document everything**
   Keep FRAMEWORK_CHANGES.md listing every modification and why.

2. **Minimize divergence**
   Only fork if absolutely necessary. Minimize number of modified files.

3. **Contribute upstream**
   Submit useful modifications to RSpade project.

4. **Test rigorously**
   Framework bugs affect entire application. Test after every change.

5. **Version lock dependencies**
   Check composer.lock and package-lock.json into git.

6. **Regular upstream merges**
   Don't let fork drift too far. Merge upstream monthly.

7. **Separate concerns**
   Application code in ./rsx, framework modifications outside.

## SEE ALSO

rsx_upstream(7) - Project mode and automatic updates
rsx_architecture(7) - RSX application structure
coding_standards(7) - RSpade development conventions