docs(scope): document deferred Go parity areas

Author: quinnj

CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Changed
+- Documented the intentionally deferred Go-parity areas for the 2.x release
+  line, including HTTP/2 server push, `Pusher`, `ResponseController` /
+  hijack-style control APIs, full `httptrace` parity, and full `net/url` /
+  `ServeMux` parity.
 
 ## [v2.0.0] - 2026-03-18
 ### Changed

README.md

@@ -27,6 +27,22 @@ cookies, multipart forms, retries, and proxy-aware transports for Julia.
 
 Current package compat targets Julia `1.10` and later.
 
+## Scope and Deferred Go Parity
+
+`HTTP.jl` 2.x borrows heavily from Go's `net/http` design, but it is not a
+drop-in clone of every Go API or feature.
+
+The current release intentionally defers:
+
+- HTTP/2 server push and a `Pusher`-style surface
+- Go `ResponseController` / hijack-style server-control APIs
+- full `httptrace` parity beyond the documented `HTTP.ClientTrace` hooks
+- full `net/url` and `ServeMux` feature parity
+
+These are explicit scope decisions for the 2.x release line rather than known
+bugs in the documented client, server, streaming, proxy, HTTP/2, SSE, and
+WebSocket APIs.
+
 ## Contributing and Questions
 
 Contributions are very welcome, as are feature requests and suggestions. Please open an

docs/src/guides/protocols.md

@@ -71,3 +71,19 @@ Use these higher-level APIs for ordinary HTTP/2 traffic:
 
 HPACK tables, HTTP/2 frame structs, and direct connection/session types are
 internal implementation details rather than part of the documented public API.
+
+## Intentional Go Parity Gaps
+
+`HTTP.jl` 2.x borrows ideas from Go's `net/http`, but it does not aim to
+surface every Go API or compatibility point.
+
+The current release intentionally defers:
+
+- HTTP/2 server push and any `Pusher`-style server API
+- Go `ResponseController` / hijack-style response-control APIs
+- full `httptrace` parity beyond the documented `HTTP.ClientTrace` hooks
+- full `net/url` and `ServeMux` feature parity
+
+Treat these as explicit scope decisions for the current release, not accidental
+regressions in the supported client, server, HTTP/2, or WebSocket features
+documented here.

docs/src/index.md

@@ -77,3 +77,4 @@ String(resp.body)
 - Request and response bodies are explicit types instead of loosely typed byte blobs.
 - Client/server internals follow a more explicit state-machine design, which makes retries, proxying, streaming, and HTTP/2 behavior easier to reason about.
 - Most wire-level HTTP/2 and HPACK details are implementation details rather than part of the documented public API.
+- `HTTP.jl` is not a drop-in clone of Go's `net/http`; see the Protocols guide for the intentionally deferred Go-parity areas in the current release.