Add 2.0 stability guarantees (#3484)

As discussed generally consider SDs as unstable, as realistically they
are never going to be. Drop the words "experimental/beta" from most
places in the docs, as users are getting the wrong impression from this.

docs/configuration/configuration.md

@@ -82,11 +82,11 @@ alerting:
   alertmanagers:
     [ - <alertmanager_config> ... ]
 
-# Settings related to the experimental remote write feature.
+# Settings related to the remote write feature.
 remote_write:
   [ - <remote_write> ... ]
 
-# Settings related to the experimental remote read feature.
+# Settings related to the remote read feature.
 remote_read:
   [ - <remote_read> ... ]
 ```
@@ -253,9 +253,6 @@ A `tls_config` allows configuring TLS connections.
 
 ### `<azure_sd_config>`
 
-CAUTION: Azure SD is in beta: breaking changes to configuration are still
-likely in future releases.
-
 Azure SD configurations allow retrieving scrape targets from Azure VMs.
 
 The following meta labels are available on targets during relabeling:
@@ -412,18 +409,8 @@ region: <string>
 
 ### `<openstack_sd_config>`
 
-CAUTION: OpenStack SD is in beta: breaking changes to configuration are still
+OpenStack SD configurations allow retrieving scrape targets from OpenStack Nova
-likely in future releases.
+instances.
-
-OpenStack SD configurations allow retrieving scrape targets from the OpenStack
-Nova API.
-
-One of the following `role` types can be configured to discover targets:
-
-#### `hypervisor`
-
-The `hypervisor` role discovers one target per Nova hypervisor node. The target
-address defaults to the `host_ip` attribute of the hypervisor.
 
 The following meta labels are available on targets during [relabeling](#relabel_config):
 
@@ -546,9 +533,6 @@ may contain a single `*` that matches any character sequence, e.g. `my/path/tg_*
 
 ### `<gce_sd_config>`
 
-CAUTION: GCE SD is in beta: breaking changes to configuration are still
-likely in future releases.
-
 [GCE](https://cloud.google.com/compute/) SD configurations allow retrieving scrape targets from GCP GCE instances.
 The private IP address is used by default, but may be changed to the public IP
 address with relabeling.
@@ -607,9 +591,6 @@ service account and place the credential file in one of the expected locations.
 
 ### `<kubernetes_sd_config>`
 
-CAUTION: Kubernetes SD is in beta: breaking changes to configuration are still
-likely in future releases.
-
 Kubernetes SD configurations allow retrieving scrape targets from
 [Kubernetes'](http://kubernetes.io/) REST API and always staying synchronized with
 the cluster state.
@@ -755,9 +736,6 @@ which automates the Prometheus setup on top of Kubernetes.
 
 ### `<marathon_sd_config>`
 
-CAUTION: Marathon SD is in beta: breaking changes to configuration are still
-likely in future releases.
-
 Marathon SD configurations allow retrieving scrape targets using the
 [Marathon](https://mesosphere.github.io/marathon/) REST API. Prometheus
 will periodically check the REST endpoint for currently running tasks and
@@ -854,9 +832,6 @@ Serverset data must be in the JSON format, the Thrift format is not currently su
 
 ### `<triton_sd_config>`
 
-CAUTION: Triton SD is in beta: breaking changes to configuration are still
-likely in future releases.
-
 [Triton](https://github.com/joyent/triton) SD configurations allow retrieving
 scrape targets from [Container Monitor](https://github.com/joyent/rfd/blob/master/rfd/0027/README.md)
 discovery endpoints.
@@ -1103,9 +1078,6 @@ relabel_configs:
 
 ### `<remote_write>`
 
-CAUTION: Remote write is experimental: breaking changes to configuration are
-likely in future releases.
-
 `write_relabel_configs` is relabeling applied to samples before sending them
 to the remote endpoint. Write relabeling is applied after external labels. This
 could be used to limit which samples are sent.
@@ -1152,9 +1124,6 @@ with this feature.
 
 ### `<remote_read>`
 
-CAUTION: Remote read is experimental: breaking changes to configuration are
-likely in future releases.
-
 ```yaml
 # The URL of the endpoint to query from.
 url: <string>

docs/stability.md

@@ -0,0 +1,38 @@
+---
+title: API Stability
+sort_rank: 8
+---
+
+# API Stability Guarantees
+
+Prometheus promises API stability within a major version, and strives to avoid
+breaking changes for key features. Some features, which are cosmetic, still
+under development, or depend on 3rd party services, are not covered by this.
+
+Things considered stable for 2.x:
+
+* The query language and data model
+* Alerting and recording rules
+* The ingestion exposition format
+* v1 HTTP API (used by dashboards and UIs)
+* Configuration file format (minus the service discovery remote read/write, see below)
+* Rule/alert file format
+* Console template syntax and semantics
+
+Things considered unstable for 2.x:
+
+* Any feature listed as experimental or subject to change, including:
+  * The [`holt_winters` PromQL function](https://github.com/prometheus/prometheus/issues/2458)
+  * Remote read, remote write and the remote read endpoint
+  * v2 HTTP and GRPC APIs
+* Service discovery integrations, with the exception of `static_configs` and `file_sd_configs`
+* Go APIs of packages that are part of the server
+* HTML generated by the web UI
+* The metrics in the /metrics endpoint of Prometheus itself
+* Exact on-disk format. Potential changes however, will be forward compatible and transparently handled by Prometheus
+
+As long as you are not using any features marked as experimental/unstable, an
+upgrade within a major version can usually be performed without any operational
+adjustments and very little risk that anything will break. Any breaking changes
+will be marked as `CHANGE` in release notes.
+

docs/storage.md

@@ -75,7 +75,7 @@ Prometheus integrates with remote storage systems in two ways:
 
 ![Remote read and write architecture](images/remote_integrations.png)
 
-The read and write protocols both use a snappy-compressed protocol buffer encoding over HTTP. The protocols are still marked experimental and may change to use gRPC over HTTP/2 in the future, when all hops between Prometheus and the long-term storage can safely be assumed to support HTTP/2.
+The read and write protocols both use a snappy-compressed protocol buffer encoding over HTTP. The protocols are not considered as stable APIs yet and may change to use gRPC over HTTP/2 in the future, when all hops between Prometheus and the long-term storage can safely be assumed to support HTTP/2.
 
 For details on configuring remote storage integrations in Prometheus, see the [remote write](configuration/configuration.md#remote_write) and [remote read](configuration/configuration.md#remote_read) sections of the Prometheus configuration documentation.