fbd83c5896
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
83 lines
2.7 KiB
Markdown
Executable File
83 lines
2.7 KiB
Markdown
Executable File
# Upstream Changes Log
|
|
|
|
## Critical: Understanding the Purpose
|
|
|
|
**The `/rsx/` directory is the starter template that end users fork to create their applications.**
|
|
|
|
When we make changes to files in `/rsx/`, users who previously forked the template do NOT automatically receive those changes. They must manually update their own copies.
|
|
|
|
**Upstream changes documents tell users EXACTLY what to change in their forked `/rsx/` code to match the upstream template.**
|
|
|
|
## Audience
|
|
|
|
The audience is a developer who:
|
|
- Forked the `/rsx/` starter template weeks or months ago
|
|
- Has been building their own application on top of it
|
|
- Wants to incorporate improvements we've made to the starter template
|
|
- Needs to know the EXACT file paths and code changes to make
|
|
|
|
## When to Create a Document
|
|
|
|
Create an upstream changes document when:
|
|
- **ANY file in `/rsx/` is modified** that users would want to replicate
|
|
- New features are added to `/rsx/` files
|
|
- Bug fixes are made to `/rsx/` files
|
|
- Patterns or APIs change in `/rsx/` files
|
|
|
|
Do NOT create documents for:
|
|
- Changes to `/system/` (framework core) - users get these automatically via submodule
|
|
- Internal refactoring that doesn't change functionality users would want
|
|
|
|
## What the Document Must Contain
|
|
|
|
The document must provide everything needed to replicate the change:
|
|
|
|
1. **AFFECTED FILES** - Exact file paths in `/rsx/` that were changed
|
|
2. **WHAT CHANGED** - The specific code additions, modifications, or deletions
|
|
3. **HOW TO APPLY** - Step-by-step instructions or copy-paste code blocks
|
|
|
|
The goal is: a user can read the document and make the exact same changes to their fork without needing to diff files or guess what changed.
|
|
|
|
## File Naming Convention
|
|
|
|
```
|
|
{feature}_{month}_{day}.txt
|
|
```
|
|
|
|
Examples:
|
|
- `modal_events_01_28.txt` - Modal event changes on January 28
|
|
- `responsive_12_18.txt` - Responsive system changes on December 18
|
|
|
|
Use lowercase with underscores. Date is MM_DD format.
|
|
|
|
## Document Structure
|
|
|
|
```
|
|
FEATURE NAME
|
|
Date: YYYY-MM-DD
|
|
|
|
SUMMARY
|
|
Brief description of what changed and why users might want it.
|
|
|
|
AFFECTED FILES
|
|
/rsx/path/to/file.js
|
|
/rsx/path/to/other_file.php
|
|
|
|
CHANGES REQUIRED
|
|
|
|
File: /rsx/path/to/file.js
|
|
-------------------------------------------------------------------------
|
|
[Exact code to add/change, with enough context to locate where]
|
|
|
|
File: /rsx/path/to/other_file.php
|
|
-------------------------------------------------------------------------
|
|
[Exact code to add/change]
|
|
|
|
VERIFICATION
|
|
How to verify the change works after applying it.
|
|
```
|
|
|
|
## Key Principle
|
|
|
|
**Show the code.** Don't just describe what changed - show the exact lines to add or modify. Users should be able to copy-paste from the document into their files.
|