HellionChat/docs/UPSTREAM_SYNC.md

Upstream sync workflow

HellionChat is a standalone EUPL-1.2 fork of Chat 2. We pull selected patches from upstream manually instead of running an automated mirror. This file documents how that works so anyone (including future-me) can do it cleanly.

One-time setup

Add the upstream repo as a remote on a fresh clone:

git remote add upstream https://github.com/Infiziert90/ChatTwo.git
git fetch upstream

Verify both remotes are wired up:

git remote -v
# origin    https://github.com/JonKazama-Hellion/HellionChat.git (fetch)
# origin    https://github.com/JonKazama-Hellion/HellionChat.git (push)
# upstream  https://github.com/Infiziert90/ChatTwo.git (fetch)
# upstream  https://github.com/Infiziert90/ChatTwo.git (push)

You never push to upstream. It is read-only for us.

Reviewing what is new upstream

Before any feature cycle starts I run a quick check:

git fetch upstream
git log --oneline main..upstream/main | head -30

That shows every commit Infi or contributors landed since the last sync. Read the messages, decide which ones apply.

What we cherry-pick

Always: security fixes, API-version compatibility patches (Dalamud API 15 → 16 → ...), BetterTTV / emote-cache fixes, regression fixes for the upstream behaviour we still rely on.

Sometimes: small bug fixes in MessageManager.cs, MessageStore.cs, ChatLogWindow.cs, the Tabs system. Pull them when they touch code we have not heavily modified.

Never: webinterface changes (the entire webinterface tree is gone in HellionChat), changes that conflict with the privacy filter, changes that re-add upstream defaults we deliberately reversed (full-history logging, Tell Exclusive defaults, etc.).

How we cherry-pick

Always with -x so authorship and the original commit hash stay visible:

git checkout -b sync/upstream-<topic> main
git cherry-pick -x <upstream-commit-sha>

-x adds a (cherry picked from commit <sha>) line to the commit message. That preserves the upstream-author credit and lets anyone reading git log trace the change back to ChatTwo. Co-Author trail intact, no AI lines, no "Hellion" prefix on commits that were not authored by us.

Conflict handling

When a cherry-pick conflicts:

1. Resolve the conflict by hand. Do not "fix" upstream code to match Hellion conventions; that is what the merge marker showed us.
2. If the conflict is fundamental (touches code that no longer exists in our fork), abort the cherry-pick and document why in Hellion Chat Backlog.md instead. Some upstream patches are not portable; that is fine.
3. After a successful resolve, the commit message stays identical to the upstream message, with the -x cherry-pick footer Git appends automatically. Do not rewrite the message to match our format.

Pushing the sync

Cherry-picked commits go through the same review as our own work: the sync branch lands in main via a no-fast-forward merge, then a release tag if the user-visible behaviour changes (otherwise just merged).

git checkout main
git merge --no-ff sync/upstream-<topic> -m "merge: upstream sync — <topic>"

When upstream goes silent

If Chat 2 stops receiving updates entirely we keep this workflow alive anyway. The remote stays configured, the documentation stays here. The moment maintenance picks back up we are ready to pull again.

When upstream takes a direction we cannot follow

If a future ChatTwo release breaks compatibility with our privacy philosophy in a way we cannot resolve (e.g. mandatory cloud sync, removal of the local message store, a license change that makes EUPL incompatible), HellionChat continues on its own from the last compatible cherry-pick. The history we already inherited stays under EUPL-1.2 and stays attributed.