docs: Clarify PromQL interval changes

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

docs/migration.md

@@ -60,33 +60,55 @@ 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. 
+### Regular expressions 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
+Lookback and range selectors are now left-open and right-closed (previously
-  evaluation aligns perfectly with a scrape, it would return 6 samples. In 
+left-closed and right-closed), which affects queries whose evaluation time
-  Prometheus v3 queries like this will always return 5 samples.  
+perfectly aligns with the sample timestamps.
-  This change has likely few effects for everyday use, except for some subquery
+
-  use cases.  
+For example, assume we are querying a timeseries with evenly spaced samples
-  Query front-ends that align queries usually align subqueries to multiples of
+exactly 1 minute apart. Before Prometheus v3, a range query with `5m` would
-  the step size. These subqueries will likely be affected.  
+usually return 5 samples. But if the query evaluation aligns perfectly with a
-  Tests are more likely to affected. To fix those either adjust the expected 
+scrape, it would return 6 samples. In Prometheus v3 queries like this will
-  number of samples or extend the range by less than one sample interval.
+always return 5 samples given even spacing.
-- The `holt_winters` function has been renamed to `double_exponential_smoothing` 
+
-  and is now guarded by the `promql-experimental-functions` feature flag.
+This change may affect subqueries that unintentionally relied on the old
-  If you want to keep using `holt_winters`, you have to do both of these things:
+behavior, because query frontends 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. In
+Prometheus V3, however, such a subquery will only return one point, which is
+insufficient for a rate or increase calculation.
+
+Such queries will need to be rewritten to extend the window to properly cover
+more than one point. In the example above, `foo[2m:1m]` should return two points
+no matter the query alignment. The exact form of the rewritten query may depend
+on the intended results and the nature of the underlying data and there is no
+universal drop-in replacement for queries whose behavior has changed.
+
+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.