165 lines
5.1 KiB
Markdown
165 lines
5.1 KiB
Markdown
# 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 |
|