JonKazama-Hellion/HellionChat
1
0
Fork 0
Code Issues 1 Pull Requests Actions Releases 28 Activity

Revise upstream sync documentation for clarity

Browse Source 
Updated the documentation to clarify the upstream sync workflow, including changes to cherry-picking practices and conflict handling. Added sections on intent, contributing back, and handling upstream changes.
This commit is contained in:
Jon Kazama
2026-05-05 21:26:53 +02:00
committed by GitHub
parent eb8b7be2f5
commit 5b5bacfc41
1 changed files with 96 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/UPSTREAM_SYNC.md
+96 -52
View File
@@ -1,11 +1,34 @@
# Upstream sync workflow # Upstream Sync
HellionChat is a standalone EUPL-1.2 fork of [Chat 2](https://github.com/Infiziert90/ChatTwo). HellionChat is a standalone EUPL-1.2 plugin that originated from
We pull selected patches from upstream manually instead of running an [Chat 2](https://github.com/Infiziert90/ChatTwo). Since v1.0.0 it
automated mirror. This file documents how that works so anyone (including lives under its own namespace, IPC channels and source tree. I no
future-me) can do it cleanly. longer track upstream as a Git fork, but I do monitor Chat 2 commits
regularly and cherry-pick selectively where it makes sense.
## One-time setup This document covers how that works so anyone (including future-me)
can do it cleanly.
## A Word on Intent
HellionChat is not trying to replace Chat 2. I build it for myself,
and maybe for people who want the same things I do: a privacy-first
chat plugin with tighter defaults and no remote-access surface. If
that is not you, Chat 2 is the better choice and a well-maintained
project.
I am available to Infi if he ever has questions about HellionChat or
how I have diverged from the upstream code. What I will not do is
interfere with Chat 2's direction or push unsolicited opinions into
his project.
Long-term compatibility between Chat 2 and HellionChat is not
guaranteed and, frankly, not technically possible. I am building a
new UI from scratch and making deliberate architectural decisions that
pull in a different direction. Some upstream patches will simply stop
applying cleanly and that is expected.
## One-Time Setup
Add the upstream repo as a remote on a fresh clone: Add the upstream repo as a remote on a fresh clone:
@@ -24,36 +47,42 @@ git remote -v
# upstream https://github.com/Infiziert90/ChatTwo.git (push) # upstream https://github.com/Infiziert90/ChatTwo.git (push)
``` ```
You never push to `upstream`. It is read-only for us. `upstream` is read-only. Never push to it.
## Reviewing what is new upstream ## Reviewing What Is New Upstream
Before any feature cycle starts I run a quick check: Before any feature cycle I run a quick check:
```bash ```bash
git fetch upstream git fetch upstream
git log --oneline main..upstream/main | head -30 git log --oneline main..upstream/main | head -30
``` ```
That shows every commit Infi or contributors landed since the last sync. That shows every commit Infi or contributors landed since the last
Read the messages, decide which ones apply. sync. I read the messages and decide which ones apply to HellionChat.
## What we cherry-pick ## What I Cherry-Pick
**Always:** security fixes, API-version compatibility patches (Dalamud **Always:** security fixes, Dalamud API compatibility patches,
API 15 → 16 → ...), BetterTTV / emote-cache fixes, regression fixes for BetterTTV and emote-cache fixes, regression fixes for upstream
the upstream behaviour we still rely on. behaviour HellionChat still relies on.
**Sometimes:** small bug fixes in `MessageManager.cs`, `MessageStore.cs`, **Sometimes:** small bug fixes in `MessageManager.cs`,
`ChatLogWindow.cs`, the Tabs system. Pull them when they touch code we `MessageStore.cs`, `ChatLogWindow.cs`, the Tabs system. These come in
have not heavily modified. when they touch code I have not heavily modified.
**Never:** webinterface changes (the entire webinterface tree is gone in **Never:** webinterface changes (the entire webinterface tree is gone
HellionChat), changes that conflict with the privacy filter, changes that in HellionChat), changes that conflict with the privacy filter, changes
re-add upstream defaults we deliberately reversed (full-history logging, that re-add upstream defaults I deliberately reversed (full-history
Tell Exclusive defaults, etc.). logging, Tell Exclusive defaults, etc.).
## How we cherry-pick As HellionChat's UI moves further from the Chat 2 baseline, upstream
patches will increasingly require adaptation rather than a clean
apply. If a patch cannot be ported without breaking HellionChat
behaviour or the privacy model, I skip it rather than force a
compromised version in.
## How I Cherry-Pick
Always with `-x` so authorship and the original commit hash stay Always with `-x` so authorship and the original commit hash stay
visible: visible:
@@ -63,48 +92,63 @@ git checkout -b sync/upstream-<topic> main
git cherry-pick -x <upstream-commit-sha> git cherry-pick -x <upstream-commit-sha>
``` ```
`-x` adds a `(cherry picked from commit <sha>)` line to the commit `-x` appends a `(cherry picked from commit <sha>)` line to the commit
message. That preserves the upstream-author credit and lets anyone message. That preserves upstream-author credit and lets anyone reading
reading `git log` trace the change back to ChatTwo. Co-Author trail `git log` trace the change back to Chat 2. Commit messages stay
intact, no AI lines, no "Hellion" prefix on commits that were not identical to the upstream original; I do not rewrite them to match the
authored by us. HellionChat format.
## Conflict handling ## Conflict Handling
When a cherry-pick conflicts: When a cherry-pick conflicts:
1. Resolve the conflict by hand. Do not "fix" upstream code to match 1. Resolve by hand. Do not rewrite upstream code to match HellionChat
Hellion conventions; that is what the merge marker showed us. conventions; that is what the merge marker showed.
2. If the conflict is fundamental (touches code that no longer exists 2. If the conflict is fundamental (touches code that no longer exists
in our fork), abort the cherry-pick and document why in in HellionChat), abort the cherry-pick and note why in the
`Hellion Chat Backlog.md` instead. Some upstream patches are not relevant GitHub issue or backlog item. Some upstream patches are
portable; that is fine. simply not portable and that is fine.
3. After a successful resolve, the commit message stays identical to 3. After a clean resolve the commit message stays as-is, with the
the upstream message, with the `-x` cherry-pick footer Git appends `-x` footer Git appends automatically.
automatically. Do not rewrite the message to match our format.
## Pushing the sync ## Pushing the Sync
Cherry-picked commits go through the same review as our own work: the Cherry-picked commits go through the same review as any other change.
sync branch lands in `main` via a no-fast-forward merge, then a release The sync branch lands in `main` via a no-fast-forward merge, then gets
tag if the user-visible behaviour changes (otherwise just merged). a release tag if user-visible behaviour changed:
```bash ```bash
git checkout main git checkout main
git merge --no-ff sync/upstream-<topic> -m "merge: upstream sync — <topic>" git merge --no-ff sync/upstream-<topic> -m "merge: upstream sync — <topic>"
``` ```
## When upstream goes silent ## Contributing Back
If Chat 2 stops receiving updates entirely we keep this workflow alive HellionChat benefits from Chat 2's work, so I try to give something
anyway. The remote stays configured, the documentation stays here. The back where I can. If I fix a bug or improve something that would be
moment maintenance picks back up we are ready to pull again. useful to Chat 2 and is not HellionChat-specific, I submit a
good-will PR to [Infiziert90/ChatTwo](https://github.com/Infiziert90/ChatTwo).
## When upstream takes a direction we cannot follow A few things to note about that process:
If a future ChatTwo release breaks compatibility with our privacy - Good-will PRs are validated in a separate fork first to make sure
philosophy in a way we cannot resolve (e.g. mandatory cloud sync, the fix stands on its own without HellionChat context.
removal of the local message store, a license change that makes EUPL - They are written by hand. No AI-generated code goes to Infi's
incompatible), HellionChat continues on its own from the last project. He did not ask for Pair-level AI involvement and I will
compatible cherry-pick. The history we already inherited stays under not push that decision onto his codebase.
EUPL-1.2 and stays attributed. - This is not guaranteed for every change, only where it makes sense
and where I am confident the fix is clean and self-contained.
## When Upstream Goes Silent
If Chat 2 stops receiving updates the remote stays configured and this
workflow stays documented. The moment maintenance picks back up I am
ready to pull again.
## When Upstream Takes a Direction I Cannot Follow
If a future Chat 2 release breaks compatibility with the HellionChat
privacy philosophy in a way that cannot be resolved (mandatory cloud
sync, removal of the local message store, an incompatible license
change), HellionChat continues from the last compatible cherry-pick.
The inherited history stays under EUPL-1.2 and stays attributed.