datarhei-dragonfork-core/docs/REBASE.md

Dragon Fork — Upstream Rebase Policy

Tracks the relationship between forge.wilddragon.net/zgaetano/datarhei-dragonfork-core (this fork) and upstream github.com/datarhei/core.

---

Baseline

Point	Value
Fork date	2026-04-17
Fork commit	0de97f4 ("Add linux/arm/v8 build")
Upstream module path	github.com/datarhei/core/v16 (kept — see NOTES.md)
First rebase target	upstream main (post-v16.16.0)

---

Cadence

Rebase against upstream main monthly, timed to follow an upstream minor release (v16.X.0) appearing on the upstream default branch.

Emergency rebases (CVE in a transitive dependency, critical upstream fix) are performed ad-hoc following the same procedure, just sooner.

---

Strategy: Rebase, Not Merge

Use git rebase upstream/main rather than git merge upstream/main.

• Keeps a linear history; git log --oneline stays readable.
• Dragon Fork commits remain visually distinct from upstream commits.
• Conflicts surface one commit at a time rather than in a single merge blob.

Merge commits are only used for feature branches merging into main via PR.

---

Divergence Boundaries

Files exclusively owned by Dragon Fork (expect zero conflicts)

These paths did not exist upstream at fork time and are not being upstreamed:

Path	Description
app/webrtc/	WebRTC app subsystem
core/webrtc/	Pion peer factory, Source, ICE helpers
deploy/truenas/	TrueNAS deployment bundle
docs/design/	Dragon Fork design documents
docs/REBASE.md	This file
.forgejo/	Forgejo CI workflows
test/load/	WHEP load-test harness

Files modified from upstream (higher conflict risk)

Path	Our change	Conflict strategy
go.mod / go.sum	Added Pion + Prometheus deps	Accept upstream base; re-add our require blocks; run go mod tidy
http/server.go	WebRTC handler registration	Search for WebRTC in diff; reapply our three-line wiring
restream/	ProcessHooks interface + SetHooks	Check if upstream changed hook shape; adapt our callbacks
config/	DataWebRTC config block	Keep our field additions; adopt upstream structural changes
README.md	Dragon Fork branding	Keep our content; cherry-pick upstream security notices
CHANGELOG.md	Dragon Fork version entries	Keep our entries at top; adopt upstream format changes

---

Pre-Rebase Checklist

[ ] git fetch upstream                      # confirm new upstream commits exist
[ ] CI is green on current main
[ ] go mod vendor is clean:
      go mod vendor && git diff --quiet vendor/   # commit if dirty
[ ] Tag current tip:
      git tag pre-rebase-v<upstream-ver>    # e.g. pre-rebase-v16.17.0

---

First Rebase Procedure

Run these commands locally (or on any machine with the repo checked out):

# 1. Add upstream remote (idempotent)
git remote add upstream https://github.com/datarhei/core.git 2>/dev/null || true

# 2. Fetch
git fetch upstream

# 3. Tag current tip
UPSTREAM_VER=$(git describe --tags upstream/main --abbrev=0 2>/dev/null || echo manual)
git tag pre-rebase-${UPSTREAM_VER}

# 4. Rebase
git rebase upstream/main
# On conflict:
#   git diff               — see what conflicted
#   <edit the file>
#   git add <file>
#   git rebase --continue

# 5. Update vendored dependencies
go mod tidy
go mod vendor
git add vendor/ go.mod go.sum
git commit -m "chore: update vendor after upstream rebase to ${UPSTREAM_VER}"

# 6. Run verification gate (see below)

# 7. Push
git push origin main

---

Post-Rebase Verification Gate

All of the following must pass before pushing the rebased main:

Check	Command
Build	go build ./...
Vet	go vet ./...
Unit + race	go test -race -short -count=1 ./...
WebRTC smoke	go test -race -count=1 -v -run 'TestIntegration_|TestSubsystem_|TestHandler_' ./app/webrtc/... ./core/webrtc/...
Latency gate	go test -tags latency -timeout 90s -race -count=1 -run TestLatencyServerHop ./app/webrtc/... -v
TrueNAS smoke	Deploy to staging, subscribe one WHEP peer, verify video renders

Forgejo CI covers the first four automatically on push. The latency gate and TrueNAS smoke are manual.

---

go.mod / Vendored Dependencies

After rebasing and running go mod tidy:

1. Confirm Pion packages (github.com/pion/*) remain in vendor/ at our required versions.
2. If upstream bumped a shared dep (e.g. labstack/echo), review that dep's changelog before accepting the version bump.
3. Commit vendor/, go.mod, and go.sum together: chore: update vendor after upstream rebase to v<X>

---

CI Automation (Future)

Automated monthly rebase via a Forgejo-Actions scheduled workflow is a v0.3 consideration. Blocked on: runner having a git identity for push, and a strategy for surfacing conflict PRs when automation fails.

---

Record-Keeping

After each successful rebase, append a row to this table:

Date	Upstream version	Pre-rebase tag	Conflicts	Notes
(first rebase pending)	v16.X.0	pre-rebase-v16.X.0	—	run locally per procedure above