✨ enable upstream updates
This commit is contained in:
356
UPSTREAM.md
Normal file
356
UPSTREAM.md
Normal file
@@ -0,0 +1,356 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user