docs: Clarify PromQL interval changes

Signed-off-by: Owen Williams <owen.williams@grafana.com>

docs/migration.md

@@ -60,33 +60,53 @@ This document offers guidance on migrating from Prometheus 2.x to Prometheus 3.0
 
 ## PromQL
 
-- The `.` pattern in regular expressions in PromQL matches newline characters. 
+### Regexes match newlines
-  With this change a regular expressions like `.*` matches strings that include 
+
-  `\n`. This applies to matchers in queries and relabel configs.
+The `.` pattern in regular expressions in PromQL matches newline characters.
-  - For example, the following regular expressions now match the accompanying
+With this change a regular expressions like `.*` matches strings that include
-  strings, whereas in Prometheus v2 these combinations didn't match.
+`\n`. This applies to matchers in queries and relabel configs.
+
+For example, the following regular expressions now match the accompanying
+strings, whereas in Prometheus v2 these combinations didn't match.
     - `.*` additionally matches `foo\n` and `Foo\nBar`
     - `foo.?bar` additionally matches `foo\nbar`
     - `foo.+bar` additionally matches `foo\nbar`
-  - If you want Prometheus v3 to behave like v2, you will have to change your
+
-  regular expressions by replacing all `.` patterns with `[^\n]`, e.g.
+If you want Prometheus v3 to behave like v2, you will have to change your
-  `foo[^\n]*`.
+regular expressions by replacing all `.` patterns with `[^\n]`, e.g.
-- Lookback and range selectors are left open and right closed (previously left 
+`foo[^\n]*`.
-  closed and right closed). This change affects queries when the evaluation time 
+
-  perfectly aligns with the sample timestamps. For example assume querying a 
+### Intervals return a predictable number of points
-  timeseries with evenly spaced samples exactly 1 minute apart. Before Prometheus
+
-  v3, a range query with `5m` would usually return 5 samples. But if the query
+Interval selectors are now more predictable than they were previously, always
-  evaluation aligns perfectly with a scrape, it would return 6 samples. In 
+returning the same number of points regardless of query alignment.
-  Prometheus v3 queries like this will always return 5 samples.  
+
-  This change has likely few effects for everyday use, except for some subquery
+Lookback and range selectors are now left-open and right-closed (previously
-  use cases.  
+left-closed and right-closed). This change affects queries when the evaluation
-  Query front-ends that align queries usually align subqueries to multiples of
+time perfectly aligns with the sample timestamps.
-  the step size. These subqueries will likely be affected.  
+
-  Tests are more likely to affected. To fix those either adjust the expected 
+For example, assume we are querying a timeseries with evenly spaced samples
-  number of samples or extend the range by less than one sample interval.
+exactly 1 minute apart. Before Prometheus v3, a range query with `5m` would
-- The `holt_winters` function has been renamed to `double_exponential_smoothing` 
+usually return 5 samples. But if the query evaluation aligns perfectly with a
-  and is now guarded by the `promql-experimental-functions` feature flag.
+scrape, it would return 6 samples. In Prometheus v3 queries like this will
-  If you want to keep using `holt_winters`, you have to do both of these things:
+always return 5 samples.
+
+This change may affect subqueries that unintentionally relied on the old
+behavior. Query front-ends often align subqueries to multiples of the step size.
+Before Prometheus V3 a subquery of `foo[1m:1m]` on such a system might have
+always returned two points, allowing for rate calculations. Such queries will
+need to be rewritten to extend the window to properly cover more than one point.
+In this case, `foo[2m:1m]` would always return two points no matter the query
+alignment.
+
+Tests are similarly more likely to affected. To fix those either adjust the
+expected number of samples or extend the range.
+
+### holt_winters function renamed
+
+The `holt_winters` function has been renamed to `double_exponential_smoothing`
+and is now guarded by the `promql-experimental-functions` feature flag.
+If you want to keep using `holt_winters`, you have to do both of these things:
   - Rename `holt_winters` to `double_exponential_smoothing` in your queries.
   - Pass `--enable-feature=promql-experimental-functions` in your Prometheus
     CLI invocation.