sunday/UPSTREAM.md

# Updating from Upstream

This guide explains how to keep your forked Sunday Comics site up-to-date with framework improvements while preserving your customizations.

## Fork-and-Customize Workflow

Sunday Comics is designed to be forked and customized for your own webcomic. The project separates:

- **Core framework files** (updated by upstream) - app logic, templates, scripts
- **User content files** (your comic data) - comics, images, markdown content
- **User configuration** (your settings) - config and design variables

When you pull updates from upstream, you'll get new features and bug fixes without losing your content or customizations.

---

## Initial Setup

### 1. Fork the Repository

On GitHub, click "Fork" to create your own copy of Sunday Comics.

### 2. Clone Your Fork

```bash
git clone https://github.com/YOUR-USERNAME/sunday-comics.git
cd sunday-comics
```

### 3. Add Upstream Remote

Add the original repository as an "upstream" remote:

```bash
git remote add upstream https://github.com/ORIGINAL-AUTHOR/sunday-comics.git
```

Verify your remotes:

```bash
git remote -v
# origin    https://github.com/YOUR-USERNAME/sunday-comics.git (fetch)
# origin    https://github.com/YOUR-USERNAME/sunday-comics.git (push)
# upstream  https://github.com/ORIGINAL-AUTHOR/sunday-comics.git (fetch)
# upstream  https://github.com/ORIGINAL-AUTHOR/sunday-comics.git (push)
```

### 4. Set Up Your Configuration

**Option A: Track your config in git (recommended)**

Your `comics_data.py` and `static/css/variables.css` files are already set up. Customize them and commit:

```bash
# Edit your configuration
nano comics_data.py
nano static/css/variables.css

# Commit your changes
git add comics_data.py static/css/variables.css
git commit -m "Configure site settings and design"
git push origin main
```

**Option B: Keep config out of git**

If you prefer to keep your config private:

```bash
# Uncomment the gitignore lines for config files
nano .gitignore
# Uncomment:
# comics_data.py
# static/css/variables.css

# Copy the example files
cp comics_data.py comics_data.py.backup
# Now comics_data.py won't be tracked
```

---

## Getting Updates from Upstream

### 1. Fetch Upstream Changes

```bash
git fetch upstream
```

This downloads new commits from the original repository without modifying your files.

### 2. Review What Changed

See what's new in upstream:

```bash
# View commit log
git log HEAD..upstream/main --oneline

# See which files changed
git diff HEAD..upstream/main --stat

# Review the CHANGELOG
git show upstream/main:CHANGELOG.md
```

### 3. Merge Upstream Changes

```bash
# Merge upstream into your current branch
git merge upstream/main
```

**If there are no conflicts:**
```bash
# Push the updates to your fork
git push origin main
```

**If there are conflicts** (see next section).

---

## Handling Merge Conflicts

Conflicts may occur if both you and upstream modified the same file. Common scenarios:

### Scenario 1: Framework Added New Config Options

**Example:** Upstream added a new setting to `comics_data.py.example`

**What to do:**
1. The merge conflict will only be in `comics_data.py.example` (not your `comics_data.py`)
2. Accept upstream's version:
   ```bash
   git checkout --theirs comics_data.py.example
   git add comics_data.py.example
   ```
3. Review `comics_data.py.example` for new settings
4. Manually add any new settings you want to your `comics_data.py`

### Scenario 2: CSS Variables Conflict

**Example:** Both you and upstream added/changed CSS variables

**What to do:**
1. Open the conflicted file:
   ```bash
   nano static/css/variables.css
   ```
2. Look for conflict markers:
   ```
   <<<<<<< HEAD
   --your-custom-variable: #ff0000;
   =======
   --new-upstream-variable: #00ff00;
   >>>>>>> upstream/main
   ```
3. Keep both variables:
   ```css
   --your-custom-variable: #ff0000;
   --new-upstream-variable: #00ff00;
   ```
4. Save and mark as resolved:
   ```bash
   git add static/css/variables.css
   git commit -m "Merge upstream CSS variables"
   ```

### Scenario 3: Rare - Core File Conflicts

If you modified a core framework file (app.py, templates, etc.), you may have conflicts.

**Best practice:** Avoid modifying core files. If you need custom behavior:
- Add new routes/functions instead of modifying existing ones
- Use template blocks for customization
- Open an issue/PR to suggest the feature for upstream

**If you must resolve:**
```bash
# Open the conflicted file
nano path/to/conflicted_file.py

# Resolve conflicts manually
# Then:
git add path/to/conflicted_file.py
git commit -m "Merge upstream changes with custom modifications"
```

---

## File Categories Reference

### Core Framework (Upstream Updates)

**DO NOT modify these files** - you'll get conflicts when merging:

- `app.py` - Flask application
- `data_loader.py` - YAML loading logic
- `scripts/*.py` - Utility scripts
- `templates/*.html` - Jinja templates (unless extending)
- `static/css/style.css` - Core CSS framework
- `static/js/*.js` - JavaScript functionality
- `version.py`, `VERSION` - Version info
- `Dockerfile`, `docker-compose.yml` - Deployment config
- Documentation files (README, CLAUDE, etc.)

### User Configuration (You Customize)

**Safe to modify** - tracked in git:

- `comics_data.py` - Your site settings
- `static/css/variables.css` - Your design variables
- `data/comics/*.yaml` - Your comic metadata
- `content/*.md` - Your markdown content (about page, author notes)
- `static/images/*` - Your images and graphics

### Template Files (Reference)

**Use as reference** - copy to create your versions:

- `comics_data.py.example` - Default configuration template
- `data/comics/TEMPLATE.yaml` - Comic file template

### Generated Files (Ignored by Git)

**Automatically regenerated:**

- `static/feed.rss` - RSS feed
- `static/sitemap.xml` - Sitemap
- `data/comics/.comics_cache.pkl` - Comic cache
- `__pycache__/` - Python bytecode

---

## Migration Notes

When upstream releases breaking changes, check `CHANGELOG.md` for migration instructions.

**Example migration scenario:**

```markdown
## [2025.03.15] - Breaking Changes
### Changed
- Renamed `SHOW_HEADER_IMAGE` to `HEADER_IMAGE` in comics_data.py

**Migration:** Update your `comics_data.py`:
- Old: `SHOW_HEADER_IMAGE = True`
- New: `HEADER_IMAGE = 'title.jpg'`
```

After merging, check the CHANGELOG and update your config accordingly.

---

## Best Practices

### ✅ DO:

- Keep your fork's main branch in sync with upstream
- Customize via `comics_data.py` and `variables.css`
- Add your comics to `data/comics/`
- Read the CHANGELOG before/after merging
- Test your site after merging updates
- Commit your changes regularly

### ❌ DON'T:

- Modify core framework files (app.py, templates, etc.)
- Delete or rename upstream files (you'll break updates)
- Force push over merged commits
- Ignore merge conflicts (resolve them properly)

---

## Troubleshooting

### "I modified a core file and now I have conflicts"

**Option 1: Keep your changes** (advanced)
```bash
# Resolve conflicts manually, testing thoroughly
git mergetool
git commit
```

**Option 2: Discard your changes** (start fresh)
```bash
# Reset to upstream version
git checkout upstream/main -- path/to/file.py
git add path/to/file.py
git commit -m "Reset to upstream version"
```

### "I want to see what changed before merging"

```bash
# Create a test branch
git checkout -b test-upstream-merge

# Merge in the test branch
git merge upstream/main

# If you like it, merge to main
git checkout main
git merge test-upstream-merge

# If not, delete the test branch
git checkout main
git branch -D test-upstream-merge
```

### "My site broke after merging"

```bash
# Check what changed
git log --oneline -10

# Test the previous version
git checkout HEAD~1
python app.py

# If it works, the issue is in the latest commit
git checkout main
git diff HEAD~1 HEAD

# Read CHANGELOG for migration notes
cat CHANGELOG.md
```

---

## Getting Help

- **Check the docs:** `README.md`, `CLAUDE.md`, `CHANGELOG.md`
- **Report issues:** [GitHub Issues](https://github.com/ORIGINAL-AUTHOR/sunday-comics/issues)
- **Ask questions:** Open a discussion or issue on GitHub

---

## Summary

**Regular update workflow:**

```bash
# Every few weeks/months:
git fetch upstream                    # Get new commits
git log HEAD..upstream/main --oneline # Review changes
git merge upstream/main               # Merge updates
# Resolve any conflicts
git push origin main                  # Push to your fork
python scripts/publish_comic.py       # Rebuild site
```

Your comics, images, and config stay safe - only the framework code updates!