Updated during WG sync

Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

Author: bwplotka

docs/tutorials/open_metrics_2_0_migration.md

@@ -1,27 +1,23 @@
 ---
-title: OpenMetrics 2.0 Migration Guide for Exposers
+title: OpenMetrics 2.0 Migration Guide for Client Libraries
 sort_rank: 6
 ---
 
-This guide covers the changes from OpenMetrics 1.0 to OpenMetrics 2.0 that affect exposer implementations. Sections are organized by implementation order so you can implement changes incrementally, starting with version negotiation and working through metric types, syntax, and metadata. This guide may contain errors, and in any case where this document disagrees with the spec document, the spec document is the authoritative source of truth.
+This guide covers the changes from OpenMetrics (OM) 1.0 to OpenMetrics 2.0 that affect client library (i.e. exposers) implementations. Sections are organized so you can implement changes incrementally, starting with version negotiation and working through metric types, syntax, and metadata. This guide may contain errors, and in any case where this document disagrees with the spec document, **the spec document is the authoritative source of truth**.
 
-> **Draft specification.** OpenMetrics 2.0 is currently version 2.0.0-rc0 and is not yet finalized. Details in this guide may change before the spec reaches 2.0.0. Track progress at the [OpenMetrics 2.0 work group issue](https://github.com/prometheus/OpenMetrics/issues/276).
+> WARNING: OpenMetrics 2.0 is currently experimental (release candidate versions), so some details might change. Track progress at the [OpenMetrics 2.0 work group issue](https://github.com/prometheus/OpenMetrics/issues/276).
 
-This guide covers the changes most relevant to exposer authors. For the complete specification including ABNF grammar, conformance requirements, and ingester rules, see the full [OpenMetrics 2.0 specification](../specs/om/open_metrics_spec_2_0.md). If you find errors or have questions, file an issue on the [OpenMetrics repository](https://github.com/prometheus/OpenMetrics).
+This guide covers the changes most relevant to client library / exposer authors. For the complete specification including ABNF grammar, conformance requirements, and ingester rules, see the full [OpenMetrics 2.0 specification](../specs/om/open_metrics_spec_2_0.md). If you find errors or have questions, file an issue on the [OpenMetrics repository](https://github.com/prometheus/OpenMetrics).
 
 ## How to use this guide
 
-Each section below guides implementers through the change:
+Each section below guides implementers through the changes. We use a **Breaking** or **Non-breaking** label. A change is **Breaking** if a line that was valid in OM 1.0 is now invalid in OM 2.0. A **Non-breaking** change adds new syntax or relaxes restrictions without invalidating any existing valid line.
 
-- A **Breaking** or **Non-breaking** label. A change is **Breaking** if a line that was valid in OM 1.0 is now invalid in OM 2.0. A **Non-breaking** change adds new syntax or relaxes restrictions without invalidating any existing valid line.
-- A brief refresher of the 1.0 behavior and the 2.0 change.
-- Before/after code blocks labeled "OM 1.0:" and "OM 2.0:" showing the difference.
-
-There is also a reference to the relevant section of the specification if more detail is required.
+There are also references to the relevant section of the specification if more detail is required.
 
 ## Quick Reference
 
-OpenMetrics 2.0 contains many changes. Some of those changes are a loosening of previously-strict requirements, like the way metric names are constructed or character limits. Most of these changes are in service of allowing OpenTelemetry metric data to be encoded in OpenMetrics without violating the specification. Other changes introduce new syntaxes, mostly focused on allowing metric data to be encoded into a single line rather than requiring multiple lines to describe one cohesive piece of information.  Lastly, some changes add new features and data types, like Native Histograms.
+OpenMetrics 2.0 contains many changes. Some of those changes are a loosening of previously-strict requirements, like the way metric names are constructed or character limits. Some of these changes are in service of allowing OpenTelemetry metric data to be encoded in OpenMetrics without violating the specification. Other changes improve scraper (e.g. Prometheus) efficiency and reliablity on various cases. Changes introduce new syntaxes, mostly focused on allowing metric data to be encoded into a single line rather than requiring multiple lines to describe one cohesive piece of information. Lastly, some changes add new features and data types, like Native Histograms.
 
 | Change                                                                           | 1.0                                      | 2.0                                                | Breaking? |
 | -------------------------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------------- | --------- |
@@ -67,29 +63,31 @@ application/openmetrics-text; version=2.0.0; charset=utf-8
 
 ### Negotiation defaults
 
-Exposers MUST default to the oldest version of the standard (1.0.0) when no specific version is requested. This applies to both pull and push models:
-
-- **Pull-based (HTTP):** Use standard HTTP content-type negotiation. If the scraper does not request version 2.0.0, respond with 1.0.0.
-- **Push-based:** Use version 1.0.0 unless the ingestor explicitly requests a newer version.
+Exposers MUST default to the oldest version of the standard (1.0.0) when no specific version is requested. Use standard HTTP content-type negotiation. If the scraper does not request version 2.0.0, respond with 1.0.0.
 
 This means your exposer should continue serving 1.0 format by default and only switch to 2.0 when the consumer asks for it.
 
 ### Protobuf format removed
 
-OM 2.0 no longer specifies an official protobuf format. You may continue to support the protobuf format for 1.0, but 2.0 does not contain a new or updated protobuf format. For the Prometheus protobuf wire format and other available formats, see the [exposition formats documentation](https://prometheus.io/docs/instrumenting/exposition_formats).
+OM 2.0 no longer specifies an official protobuf format. You may continue to support the protobuf format for 1.0 (we d, but 2.0 does not contain a new or updated protobuf format. 
+
+The Prometheus protobuf wire format is still important and maintain, see the [exposition formats documentation](https://prometheus.io/docs/instrumenting/exposition_formats).
 
 See: [Protocol Negotiation](../specs/om/open_metrics_spec_2_0.md#protocol-negotiation) in the OM 2.0 spec.
 
 ## Naming Changes
 
 OM 2.0 tightens the relationship between MetricFamily names and Metric Names, and changes the suffix rules for counters and info metrics. In OM 1.0, parsers implicitly stripped known suffixes to map sample names back to their MetricFamily. In OM 2.0, this implicit stripping is gone: the MetricFamily name must exactly match every Metric's Name.
 
+Generally, the mandatory unit and `_total` suffix is also now recommended, but not required.
+
 ### Specification Terminology Changes
 
-**Non-breaking**: Does not affect exposition format, only the terms used in the spec.
+**Non-breaking**: Does not affect exposition format, only the terms used in the spec. It's useful to understand this change for easier use of the OM 2.0 spec.
 
 OM 2.0 restructures the data model hierarchy. In OM 2.0, MetricPoint is removed and Sample becomes a first-class data model object:
 
+<!-- TODO: add diagram -->
 **OM 1.0:** MetricSet → MetricFamily → Metric → MetricPoint → Sample (text format)
 **OM 2.0:** MetricSet → MetricFamily → Metric → Sample (with Number or CompositeValue)
 
@@ -108,6 +106,7 @@ OM 2.0 restructures the data model hierarchy. In OM 2.0, MetricPoint is removed
 
 In OM 1.0, a counter's TYPE line used a base name (e.g. `http_requests`) while its samples carried the `_total` suffix (e.g. `http_requests_total`). The parser knew to strip `_total` when matching samples back to their MetricFamily, so the MetricFamily name and sample Metric Name could differ.
 
+<!--change to "must" unless we quote spec-->
 In OM 2.0, the MetricFamily name MUST exactly match every Metric's Name. There is no implicit suffix stripping. For counters, this means the TYPE line must include `_total` if the samples use it.
 
 OM 1.0:
@@ -316,7 +315,7 @@ See: [Counter](../specs/om/open_metrics_spec_2_0.md#counter) and [Histogram with
 
 ## CompositeValues
 
-**Breaking**: Traditional multiline complex types are no longer allowed.
+**Breaking**: Traditional multiline complex types are no longer allowed (except StateSet).
 
 In OM 1.0, complex metric types (histograms, summaries, gaugehistograms) were represented as multiple expanded sample lines — one line per bucket, one for count, one for sum. In OM 2.0, these become a single sample line whose value is a CompositeValue: a structured `{key:value,...}` block containing all the fields at once.