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>
230 lines
6.4 KiB
Plaintext
Executable File
230 lines
6.4 KiB
Plaintext
Executable File
# 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
|