mi/sunday

Files

2025-11-16 13:17:07 +10:00

8.5 KiB

Raw Blame History

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

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:

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

Verify your remotes:

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:

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

# 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

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:

# 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

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

If there are no conflicts:

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

The merge conflict will only be in comics_data.py.example (not your comics_data.py)

Accept upstream's version:

git checkout --theirs comics_data.py.example
git add comics_data.py.example

Review comics_data.py.example for new settings
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:

Open the conflicted file:
```
nano static/css/variables.css
```

Look for conflict markers:

<<<<<<< HEAD
--your-custom-variable: #ff0000;
=======
--new-upstream-variable: #00ff00;
>>>>>>> upstream/main

Keep both variables:

--your-custom-variable: #ff0000;
--new-upstream-variable: #00ff00;

Save and mark as resolved:

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:

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

## [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)

# Resolve conflicts manually, testing thoroughly
git mergetool
git commit

Option 2: Discard your changes (start fresh)

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

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

# 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
Ask questions: Open a discussion or issue on GitHub

Summary

Regular update workflow:

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

8.5 KiB Raw Blame History