Rework NEWS.md about .ref_time_value and almost-pronouns available

brookslogan · brookslogan · commit e7c4b8d74bd7 · 2023-06-16T13:28:35.000-07:00
diff --git a/NEWS.md b/NEWS.md
@@ -6,16 +6,31 @@ inter-release development versions will include an additional ".9999" suffix.
 
 ## Breaking changes:
 
-* Changes to `epix_slide`:
-  * The `f` computation is now required to take at least three arguments. `f`
-    must take an `epi_df` with the same column names as the archive's `DT`,
+* Changes to `epi_slide` and `epix_slide`:
+  * If `f` is a function, it is now required to take at least three arguments.
+    `f` must take an `epi_df` with the same column names as the archive's `DT`,
     minus the `version` column; followed by a one-row tibble containing the
-    values of the grouping variables for the associated group; followed by a
-    Date containing the reference time value that was used; followed by any
-    number of named arguments.
+    values of the grouping variables for the associated group; followed by *a
+    time value (usually a `Date`) containing the reference time value that was
+    used. Optionally, it can take any number of additional arguments, which will
+    be forwarded through `epi[x]_slide`'s `...` args.
+    * To make your existing slide computations work, add a third argument to
+      your `f` function to accept this new input: e.g., change `f = function(x,
+      g, <any other arguments>) { <body> }` to `f = function(x, g, rt, <any
+      other arguments>) { <body> }`.
 
 ## New features:
 
+* `epi_slide` and `epix_slide` also make the window data, group key and reference
+  time value available to slide computations specified as formulas or tidy
+  evaluation expressions, in additional or completely new ways.
+  * If `f` is a formula, it can now access the reference time value via `.z` or
+    `.ref_time_value`.
+  * If `f` is missing, the tidy evaluation expression in `...` can now refer to
+    the window data as an `epi_df` or `tibble` with `.x`, the group key with
+    `.group_key`, and the reference time value with `.ref_time_value`. The usual
+    `.data` and `.env` pronouns also work, but`pick()` and `cur_data()` are not;
+    work off of `.x` instead.
 * `epix_slide` has been made more like `dplyr::group_modify`. It will no longer
   perform element/row recycling for size stability, accepts slide computation
   outputs containing any number of rows, and no longer supports `all_rows`.
@@ -29,11 +44,6 @@ inter-release development versions will include an additional ".9999" suffix.
   more closely whether/when/how to output an `epi_df`.
   * To keep the old behavior, convert the output of `epix_slide()` to `epi_df`
     when desired and set the metadata appropriately.
-* `epix_slide` `f` computations passed as functions or formulas now have
-  access to the reference time value. If `f` is a function, it is passed a
-  Date containing the reference time value as the third argument. If a
-  formula, `f` can access the reference time value via `.z` or
-  `.ref_time_value`.
 
 ## Improvements:
 
