f6fac6c4bc
Fix bin/publish: use correct .env path for rspade_system Fix bin/publish script: prevent grep exit code 1 from terminating script 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
404 lines
12 KiB
Plaintext
Executable File
404 lines
12 KiB
Plaintext
Executable File
# 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
|