rspade_system/app/RSpade/upstream_changes/CLAUDE.md

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