Documenting how otelhttp.Handler allows propagating WriteHeader calls

We explicitly capture initial statusCode written while propagating all
consecutive calls to the wrapped ResponseWriter without altering state.

CHANGELOG.md

@@ -12,9 +12,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Add the new `go.opentelemetry.io/contrib/instrgen` package to provide auto-generated source code instrumentation. (#3068)
 
-### Changed
+### Fixed
 
-- Remove early return in `respWriterWrapper` in `go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp` to avoid blocking multiple calls to underlying ResponseWriter.WriteHeader. (#3580)
+- Enable `otelhttp.Handler` to propagate multiple WriteHeader calls while persisting initial statusCode in `go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp`. (#3580)
 
 ## [1.16.0-rc.1/0.41.0-rc.1/0.9.0-rc.1] - 2023-03-02
 

instrumentation/net/http/otelhttp/wrap.go

@@ -50,7 +50,7 @@ func (w *bodyWrapper) Close() error {
 var _ http.ResponseWriter = &respWriterWrapper{}
 
 // respWriterWrapper wraps a http.ResponseWriter in order to track the number of
-// bytes written, the last error, and to catch the returned statusCode
+// bytes written, the last error, and to catch the first written statusCode.
 // TODO: The wrapped http.ResponseWriter doesn't implement any of the optional
 // types (http.Hijacker, http.Pusher, http.CloseNotifier, http.Flusher, etc)
 // that may be useful when using it in real life situations.
@@ -85,6 +85,11 @@ func (w *respWriterWrapper) Write(p []byte) (int, error) {
 	return n, err
 }
 
+// WriteHeader persists initial statusCode for span attribution.
+// All calls to WriteHeader will be propagated to the underlying ResponseWriter
+// but will not overwrite persisted statusCode.
+// Blocking consecutive calls to WriteHeader alters expected behavior and will
+// remove warning logs from net/http where developers will notice incorrect handler implementations.
 func (w *respWriterWrapper) WriteHeader(statusCode int) {
 	if !w.wroteHeader {
 		w.wroteHeader = true