Revise upstream sync documentation for clarity
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:
GitHub
+96
-52
@@ -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).
|
||||
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.
|
||||
HellionChat is a standalone EUPL-1.2 plugin that originated from
|
||||
[Chat 2](https://github.com/Infiziert90/ChatTwo). Since v1.0.0 it
|
||||
lives under its own namespace, IPC channels and source tree. I no
|
||||
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:
|
||||
|
||||
@@ -24,36 +47,42 @@ git remote -v
|
||||
# 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
|
||||
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.
|
||||
That shows every commit Infi or contributors landed since the last
|
||||
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
|
||||
API 15 → 16 → ...), BetterTTV / emote-cache fixes, regression fixes for
|
||||
the upstream behaviour we still rely on.
|
||||
**Always:** security fixes, Dalamud API compatibility patches,
|
||||
BetterTTV and emote-cache fixes, regression fixes for upstream
|
||||
behaviour HellionChat still relies 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.
|
||||
**Sometimes:** small bug fixes in `MessageManager.cs`,
|
||||
`MessageStore.cs`, `ChatLogWindow.cs`, the Tabs system. These come in
|
||||
when they touch code I 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.).
|
||||
**Never:** webinterface changes (the entire webinterface tree is gone
|
||||
in HellionChat), changes that conflict with the privacy filter, changes
|
||||
that re-add upstream defaults I deliberately reversed (full-history
|
||||
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
|
||||
visible:
|
||||
@@ -63,48 +92,63 @@ 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.
|
||||
`-x` appends a `(cherry picked from commit <sha>)` line to the commit
|
||||
message. That preserves upstream-author credit and lets anyone reading
|
||||
`git log` trace the change back to Chat 2. Commit messages stay
|
||||
identical to the upstream original; I do not rewrite them to match the
|
||||
HellionChat format.
|
||||
|
||||
## Conflict handling
|
||||
## 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.
|
||||
1. Resolve by hand. Do not rewrite upstream code to match HellionChat
|
||||
conventions; that is what the merge marker showed.
|
||||
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.
|
||||
in HellionChat), abort the cherry-pick and note why in the
|
||||
relevant GitHub issue or backlog item. Some upstream patches are
|
||||
simply not portable and that is fine.
|
||||
3. After a clean resolve the commit message stays as-is, with the
|
||||
`-x` footer Git appends automatically.
|
||||
|
||||
## Pushing the sync
|
||||
## 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).
|
||||
Cherry-picked commits go through the same review as any other change.
|
||||
The sync branch lands in `main` via a no-fast-forward merge, then gets
|
||||
a release tag if user-visible behaviour changed:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
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
|
||||
anyway. The remote stays configured, the documentation stays here. The
|
||||
moment maintenance picks back up we are ready to pull again.
|
||||
HellionChat benefits from Chat 2's work, so I try to give something
|
||||
back where I can. If I fix a bug or improve something that would be
|
||||
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
|
||||
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.
|
||||
- Good-will PRs are validated in a separate fork first to make sure
|
||||
the fix stands on its own without HellionChat context.
|
||||
- They are written by hand. No AI-generated code goes to Infi's
|
||||
project. He did not ask for Pair-level AI involvement and I will
|
||||
not push that decision onto his codebase.
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user