docs: Clarify PromQL interval changes

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

docs/migration.md

@@ -60,36 +60,58 @@ 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. 
-  With this change a regular expressions like `.*` matches strings that include 
-  `\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.
-  `foo[^\n]*`.
-- Lookback and range selectors are left open and right closed (previously left 
-  closed and right closed). This change affects queries when the evaluation time 
-  perfectly aligns with the sample timestamps. For example assume querying a 
-  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
-  evaluation aligns perfectly with a scrape, it would return 6 samples. In 
-  Prometheus v3 queries like this will always return 5 samples.  
-  This change has likely few effects for everyday use, except for some subquery
-  use cases.  
-  Query front-ends that align queries usually align subqueries to multiples of
-  the step size. These subqueries will likely be affected.  
-  Tests are more likely to affected. To fix those either adjust the expected 
-  number of samples or extend the range by less than one sample interval.
-- 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.
+### Regular expressions match newlines
+
+The `.` pattern in regular expressions in PromQL matches newline characters.
+With this change a regular expressions like `.*` matches strings that include
+`\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.
+`foo[^\n]*`.
+
+### Intervals return a predictable number of points
+
+Lookback and range selectors are now left-open and right-closed (previously
+left-closed and right-closed), which affects queries whose evaluation time
+perfectly aligns with the sample timestamps.
+
+For example, assume we are querying a 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 evaluation aligns perfectly with a
+scrape, it would return 6 samples. In Prometheus v3 queries like this will
+always return 5 samples given even spacing.
+
+This change may affect subqueries that unintentionally relied on the old
+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.
 
 ## Scrape protocols
 Prometheus v3 is more strict concerning the Content-Type header received when