Update comments and feature flag description

Signed-off-by: Carrie Edwards <edwrdscarrie@gmail.com>

CHANGELOG.md

@@ -27,7 +27,6 @@ User migrating from bind mounts might need to ajust permissions too, depending o
 - [FEATURE] Web: Add OpenAPI 3.2 specification for the HTTP API at `/api/v1/openapi.yaml`. #17825
 - [FEATURE] Dockerfile: Add distroless image variant using UID/GID 65532 and no VOLUME declaration. Busybox image remains default. #17876
 - [FEATURE] Web: Add on-demand wall time profiling under `<URL>/debug/pprof/fgprof`. #18027
-- [FEATURE] Add xor2-encoding feature flag. #18276
 - [ENHANCEMENT] PromQL: Add more detail to histogram quantile monotonicity info annotations. #15578
 - [ENHANCEMENT] Alerting: Independent alertmanager sendloops. #16355
 - [ENHANCEMENT] TSDB: Experimental support for early compaction of stale series in the memory with configurable threshold `stale_series_compaction_threshold` in the config file. #16929

docs/feature_flags.md

@@ -310,18 +310,12 @@ For more details, see the [proposal](https://github.com/prometheus/proposals/pul
 
 `--enable-feature=xor2-encoding`
 
-Enables the XOR2 chunk encoding for float samples, which provides better
-disk compression than the default XOR encoding for typical Prometheus workloads. XOR2 reduces chunk storage size by
-5-20% in typical Prometheus deployments through:
+> WARNING: This is highly experimental and risky setting:
+> * Chunks encoded with XOR2 **cannot be read by older Prometheus versions** that do not support the encoding. Once enabled and data is written, you need to **manually delete blocks from the disk**, otherwise Prometheus will return error on all queries.
+> * We are still experimenting on the final encoding. As of now this encoding can change in any Prometheus version. All your persistent block data will be lost between versions.
+> * This is encoding is new, meaning downstream tools and LTS systems might now support it yet (e.g. Thanos sidecar uploaded blocks).
 
-1. **Staleness marker optimization**: When a scrape target disappears, Prometheus writes a special "staleness marker" to indicate the series has ended. Standard XOR encoding uses ~110 bits per marker; XOR2 uses only 13 bits—a **90% reduction**. For deployments with dynamic infrastructure (Kubernetes pods, auto-scaling, short-lived jobs), staleness markers can represent 10-40% of all samples.
-2. **Adaptive timestamp encoding**: XOR2 automatically optimizes for both regular and irregular scrape intervals. Regular data gets the same compression as standard XOR (zero overhead), while irregular data benefits from improved encoding that handles larger timestamp variations more efficiently.
-
-This feature also introduces the fields needed for encoding start timestamps. `xor2-encoding` is automatically enabled when `st-storage` is enabled.
-
-Chunks encoded with XOR2 **cannot be read by older Prometheus versions** that do not support
-the encoding. Once enabled and data is written, downgrading requires waiting for
-all XOR2 chunks to be compacted out of retention.
+This setting enables the new XOR2 chunk encoding for float samples, which provides better disk compression than the default XOR encoding for typical Prometheus workloads. This format also allow storing Start Timestamp (ST).
 
 ## Extended Range Selectors
 

tsdb/head.go

@@ -167,8 +167,7 @@ type HeadOptions struct {
 	EnableSTStorage atomic.Bool
 
 	// EnableXOR2Encoding enables XOR2 chunk encoding for float samples.
-	// Represents 'xor2-encoding' feature flag. Automatically true when
-	// EnableSTStorage is true.
+	// Represents 'xor2-encoding' feature flag.
 	EnableXOR2Encoding atomic.Bool
 
 	ChunkRange int64