docs: Explained current state of the repo (#143)

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

Author: bwplotka

README.md

@@ -1,43 +1,20 @@
-_(If you are reading this because you are interested in Prometheus's native
-histograms, pay special attention to the last paragraph below.)_
-
 # Deprecation note
 
-This repository used to contain the [protocol
-buffer](https://developers.google.com/protocol-buffers) code that defined both
-the data model and the exposition format of Prometheus metrics.
-
-Starting with v2.0.0, the [Prometheus
-server](https://github.com/prometheus/prometheus) does not ingest the
-protobuf-based exposition format anymore. Currently, all but one of the
-[official instrumentation
-libraries](https://prometheus.io/docs/instrumenting/clientlibs/) do not expose
-the protobuf-based exposition format. The [Go instrumentation
-library](https://github.com/prometheus/client_golang), however, has been built
-around the protobuf-based data model. As a byproduct thereof, it is still able
-to expose the protobuf-based exposition format. The Go instrumentation library
-is the only remaining repository within the [Prometheus GitHub
-org](https://github.com/prometheus) directly using the prometheus/client_model
-repository.
-
-Therefore, formerly existing support for languages other than Go (namely C++,
-Java, Python, Ruby) has been removed from this repository. If you are a 3rd
-party user of those languages, you can go back to [commit
-14fe0d1](https://github.com/prometheus/client_model/commit/14fe0d1b01d4d5fc031dd4bec1823bd3ebbe8016)
-to keep using the old code, or you can consume
-[`metrics.proto`](https://github.com/prometheus/client_model/blob/master/metrics.proto)
-directly with your own protobuf tooling. Note, however, that changes of
-`metrics.proto` after [commit
-14fe0d1](https://github.com/prometheus/client_model/commit/14fe0d1b01d4d5fc031dd4bec1823bd3ebbe8016)
-are solely informed by requirements of the Go instrumentation library and will
-not take into account any requirements of other languages or stability concerns
-for the protobuf-based exposition format.
-
-Check out the [OpenMetrics project](https://openmetrics.io/) for the future of
-the data model and exposition format used by Prometheus and others.
-
-Note, though, that in an ironic twist of fate, the protobuf-based exposition
-format got revived to suppert native histograms in Prometheus. Therefore,
-starting with v2.40.0, the Prometheus server is again capable of ingesting the
-protobuf-based exposition format. Eventually, native histogram support will be
-added in some form to OpenMetrics, too.
+This repository used to contain the [protocol buffer](https://developers.google.com/protocol-buffers) code that defined both the data model and [the exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/#prometheus-protobuf-format) of Prometheus metrics. `client_model` was originally created because robust protobuf import tooling was non-existent at the time. Since then, tooling has improved (see [Buf](https://buf.build/)).
+
+The generated Go code is still used in the [public, stable API of `client_golang`](https://github.com/prometheus/client_golang/blob/74560058a7af7a695db8196c8e84a0754032c6af/prometheus/metric.go#L54) until v2.
+
+The source of truth for [the exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/#prometheus-protobuf-format) has moved to [prometheus/prometheus](https://github.com/prometheus/prometheus/tree/main/prompb/io/prometheus/client) and is also available in the [Buf registry](https://buf.build/prometheus/prometheus/docs/main%3Aio.prometheus.client).
+
+## History
+
+Starting with v2.0.0, the [Prometheus server](https://github.com/prometheus/prometheus) stopped ingesting the protobuf-based exposition format. However, in v3.0.0 this restriction was lifted, and new features like native histograms were first introduced in the protobuf format. As of now, [the PrometheusProto exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/#prometheus-protobuf-format) is an officially supported protocol that allows the community to experiment with new features.
+
+## Recommended Usage & Buf Tooling
+
+Formerly existing support for languages other than Go (namely C++, Java, Python, and Ruby) has been removed from this repository.
+
+For new consumers and SDKs in other languages (such as Rust, C++, Java, Python, and Ruby), **we do not recommend manually copying proto files or depending on `client_model`**. Instead, the modern preferred solution is to use [Buf tooling](https://buf.build/) to generate bindings directly on the SDK side with specific language options, maintaining a clean dependency chain.
+
+The centralized Prometheus protobuf definitions are available in the Buf registry, sourced directly from the main Prometheus repository:
+[buf.build/prometheus/prometheus (io.prometheus.client)](https://buf.build/prometheus/prometheus/docs/main:io.prometheus.client)