# 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.