# Upstream Changes Log

## Purpose

This directory contains migration guides for significant framework changes that affect existing RSX applications. When framework updates introduce breaking changes or new patterns that downstream projects should adopt, a detailed migration document is created here.

These documents serve as technical references for updating existing applications to match the current framework patterns.

## When to Create a Document

Create a migration guide when:
- Breaking changes affect existing application code
- New patterns replace old patterns (and old code should be updated)
- Configuration or directory structure changes
- New required dependencies or bundle includes

Do NOT create documents for:
- Internal framework refactoring that doesn't affect applications
- New features that don't require changes to existing code
- Bug fixes

## File Naming Convention

```
{feature}_{month}_{day}.txt
```

Examples:
- `responsive_12_18.txt` - Responsive system changes on December 18
- `bundle_api_03_15.txt` - Bundle API changes on March 15
- `auth_session_07_22.txt` - Authentication/session changes on July 22

Use lowercase with underscores. Date is MM_DD format (no year - files are naturally ordered by creation).

## Document Structure

Each migration guide should include:

```
FEATURE NAME - MIGRATION GUIDE
Date: YYYY-MM-DD

SUMMARY
    One paragraph describing what changed and why.

AFFECTED FILES
    List of file paths that need modification in downstream projects.

CHANGES REQUIRED

    1. First Change Category
       - What to do
       - Code examples (before/after)

    2. Second Change Category
       - What to do
       - Code examples

CONFIGURATION
    Any new configuration values, bundle includes, or settings.

VERIFICATION
    How to verify the migration was successful.

REFERENCE
    Links to man pages or other documentation.
```

## Level of Detail

Migration guides should be:
- **Complete**: Every change needed to migrate, no assumptions
- **Actionable**: Clear steps, not just descriptions
- **Example-driven**: Show before/after code for each change type
- **Self-contained**: Reader shouldn't need to reference other docs to complete migration

Assume the reader:
- Has an existing RSX application
- Understands the framework basics
- Does NOT know what changed or why