Overview

Our current Media over QUIC (MoQ) implementation has diverged from the upstream draft specification in several areas.
To support contributors and ensure long-term maintainability, we should introduce a clear documentation structure in the repository that records:

• what has changed from upstream,
• why those changes exist,
• and how far our implementation has diverged.

Motivation & Benefits

• The upstream MoQ spec is still evolving, and our implementation inevitably introduces differences, temporary workarounds, and project-specific behavior.
• Right now, these differences are not tracked in a central place, which makes it harder for:
  • contributors to understand expected behavior,
  • reviewers to validate PRs,
  • new developers to follow the protocol logic,
  • and maintainers to sync with future upstream changes.
• Having dedicated documentation for spec differences will:
  • provide transparency for all contributors,
  • make future rebase/merge with upstream specifications significantly easier,
  • reduce inconsistencies and misunderstandings across the codebase,
  • help external developers build interoperable clients.

Use Case

• Someone implementing a client or server needs to know exactly how our behavior differs from the upstream MoQ draft.
• New contributors can quickly identify which parts of the system follow upstream verbatim and which are modified or extended.
• When the upstream MoQ draft updates, maintainers can review the diff and easily update our documentation.

Proposed Solution (include Next Steps)

1. Add a new directory in the repo such as docs/spec-diff/ or spec/ that contains:
   • CHANGELOG.md — tracks protocol-level changes over time
   • DIFF_FROM_UPSTREAM.md — lists differences from the current upstream draft
   • RATIONALE.md — explains why certain differences exist (temporary workaround, permanent design choice, etc.)
2. Provide structured sections such as:
   • Behavior deviating from upstream
   • Additional extensions
   • Removed or simplified features
   • Open questions or pending upstream updates
3. During development, require contributors to update these files when modifying protocol behavior.
4. Optionally generate diff tables or auto-publish documentation via GitHub Pages.

Alternatives Considered

• Keeping differences in comments or PR discussions → easily lost and not maintainable.
• Writing a full forked specification → too heavy and unnecessary at this stage.
• Relying solely on inline code comments → not sufficient for protocol-level behavior.

Related issues

No related issues at this time.

Checklist

• I have searched existing issues
• I have read relevant documentation
• I can contribute to this feature