From f80fafac14b6dfd29b4dc470c94e520ac131e935 Mon Sep 17 00:00:00 2001 From: Chris Marchbanks Date: Thu, 23 May 2024 19:13:31 -0600 Subject: [PATCH] Add section explaining backwards compatability and versioning plan Signed-off-by: Chris Marchbanks --- proposals/2024-01-29_native_histograms_text_format.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/proposals/2024-01-29_native_histograms_text_format.md b/proposals/2024-01-29_native_histograms_text_format.md index 6f3a689..2231a2d 100644 --- a/proposals/2024-01-29_native_histograms_text_format.md +++ b/proposals/2024-01-29_native_histograms_text_format.md @@ -41,7 +41,7 @@ Client library maintainers, OpenMetrics, and Prometheus scrape maintainers. ## Non-Goals -* Requiring backwards compatability (OpenMetrics 2.0 would be ok) +* Requiring backwards compatability (OpenMetrics 2.0 would be ok), and especially forwards compatability (not required in the OpenMetrics spec). ## How @@ -67,6 +67,10 @@ Positive infinity, negative infinity, and non number values will be represented Note that in this initial implementation float histograms are not supported. +### Backwards compatability and semantic versioning + +After discussions with a few people it is believed that these changes can be made in a 1.x release of OpenMetrics. OpenMetrics 1.x parsers that support native histograms will still be able to read OpenMetrics 1.0 responses, therefore this change is backwards compatible. However, this change is not forwards compatible, i.e. an OpenMetrics 1.0 parser will not be able to read an OpenMetrics >= 1.1 response. Any producers implementing native histograms MUST also implement content negotiation and fall back to OpenMetrics 1.0.0, and therefore not expose native histograms, if a supported version cannot be negotiated. Note that the behavior to fall back to 1.0.0 is already part of the [OpenMetrics spec](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#protocol-negotiation). + ## Alternatives ### Do nothing