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):

```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 |