Instructions for B-Square-Bulletin fork to align with upstream for smoother syncs

fork-sync-instructions.md

Smoother upstream syncs for B-Square-Bulletin/community-calendar

Five commits just landed upstream that reduce merge friction for forks. Here's what to do and why.

What changed upstream

1. report.json and xmlui/version.txt are no longer tracked. These auto-generated files always diverge across forks, causing pointless merge conflicts.

2. xmlui/config.local.js is no longer tracked. It was already gitignored but still in the repo from an earlier commit. A config.local.js.example template is now shipped instead.

3. .gitattributes now declares keepours merge drivers for xmlui/config.json, cities.json, and cities/*/feeds.txt. When activated, these auto-resolve to your fork's version during upstream merges.

4. scripts/align-fork.sh automates the one-time setup: restores deleted city directories, configures the merge driver, and creates config.local.js.

5. The CI workflow no longer force-adds gitignored files back into tracking on every build.

What to do

Step 1: Merge upstream

# Make sure you're on your main branch with a clean working tree
git stash  # if needed

# Add upstream if you haven't already
git remote add upstream https://github.com/judell/community-calendar.git

# Fetch and merge upstream (this pulls in all 5 commits)
git fetch upstream
git merge upstream/main

You'll likely get conflicts on the deleted city directories. That's expected — this is the last time. Resolve by accepting the upstream versions:

git checkout upstream/main -- cities/
git add cities/
git commit -m "Restore upstream city directories for cleaner merges"

Step 2: Run the alignment script

bash scripts/align-fork.sh

This sets up the keepours merge driver and creates config.local.js from the template if needed.

Step 3: Verify your config.local.js

Check that xmlui/config.local.js has your Supabase credentials:

window.SUPABASE_URL = 'https://qatykxdvbpojxnvpicyi.supabase.co';
window.SUPABASE_KEY = 'your-anon-or-publishable-key';

If it was overwritten during the merge, restore it from your Supabase dashboard (Settings > API > Project API keys).

Note on the XMLUI shell

Upstream now keeps the XMLUI bootstrap logic in xmlui/shell.js (with a small companion xmlui/shell.css) rather than inline in xmlui/index.html. This does not change local fork setup: you should still keep your own untracked xmlui/config.local.js for development and fork-specific credentials. The deployed GitHub Pages shell can fall back to xmlui/config.json if config.local.js is absent, but local forks should continue to treat config.local.js as the place for their Supabase settings.

Step 4: Set ENABLED_CITIES (if you haven't already)

In your GitHub repo, go to Settings > Secrets and variables > Actions > Variables and add:

Name:  ENABLED_CITIES
Value: bloomington

This scopes builds to Bloomington without deleting other city directories. The directories exist in the repo but the workflow ignores them.

Step 5: Push

git push origin main

What's different going forward

Future upstream syncs are just:

git fetch upstream
git merge upstream/main

• City directories won't conflict because they're no longer deleted from your fork
• config.json, cities.json, and feeds.txt won't conflict because the keepours driver auto-resolves them to your version
• report.json, version.txt, and config.local.js won't conflict because they're no longer tracked
• When upstream adds new resources/icons to config.json, you'll want to manually check git diff upstream/main -- xmlui/config.json and cherry-pick any new entries into yours