docs: add upstream rebase policy (closes #13)

docs/REBASE.md

@@ -0,0 +1,165 @@
+# 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):
+
+```sh
+# 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 |