rspade_system/app/RSpade/upstream_changes/CLAUDE.md

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.