Note instability of nest_by() and group_nest/split() (#6657)

* Note instability of `group_nest()`

* Note instability of `nest_by()`

* Note instability of `group_split()`

* Life cycle -> Lifecycle

R/colwise-mutate.R

@@ -75,7 +75,7 @@
 #'
 #' Name collisions in the new columns are disambiguated using a unique suffix.
 #'
-#' @section Life cycle:
+#' @section Lifecycle:
 #'
 #' The functions are maturing, because the naming scheme and the
 #' disambiguation algorithm are subject to change in dplyr 0.9.0.
@@ -196,7 +196,7 @@ summarize_at <- summarise_at
 #'   `transmute_if()`.
 #'
 #' @inheritSection summarise_all Naming
-#' @inheritSection summarise_all Life cycle
+#' @inheritSection summarise_all Lifecycle
 #'
 #' @examples
 #' iris <- as_tibble(iris)

R/group-nest.R

@@ -10,6 +10,10 @@ group_nest_impl <- function(.tbl, .key, keep = FALSE){
 #'
 #' Nest a tibble using a grouping specification
 #'
+#' @section Lifecycle:
+#' `group_nest()` is not stable because [`tidyr::nest(.by =)`][tidyr::nest()]
+#' provides very similar behavior. It may be deprecated in the future.
+#'
 #' @section Grouped data frames:
 #'
 #' The primary use case for [group_nest()] is with already grouped data frames,

R/group-split.R

@@ -17,6 +17,13 @@
 #' is generally not very useful as you want have easy access to the group
 #' metadata.
 #'
+#' @section Lifecycle:
+#' `group_split()` is not stable because you can achieve very similar results by
+#' manipulating the nested column returned from
+#' [`tidyr::nest(.by =)`][tidyr::nest()]. That also retains the group keys all
+#' within a single data structure. `group_split()` may be deprecated in the
+#' future.
+#'
 #' @param .tbl A tbl.
 #' @param ... If `.tbl` is an ungrouped data frame, a grouping specification,
 #'   forwarded to [group_by()].
@@ -26,6 +33,7 @@
 #'   Note that this returns a [list_of][vctrs::list_of()] which is slightly
 #'   stricter than a simple list but is useful for representing lists where
 #'   every element has the same type.
+#' @keywords internal
 #' @family grouping functions
 #' @export
 #' @examples

R/nest-by.R

@@ -30,6 +30,10 @@
 #'   reframe(data)
 #' ```
 #'
+#' @section Lifecycle:
+#' `nest_by()` is not stable because [`tidyr::nest(.by =)`][tidyr::nest()]
+#' provides very similar behavior. It may be deprecated in the future.
+#'
 #' @return
 #' A [rowwise] data frame. The output has the following properties:
 #'

_pkgdown.yml

@@ -109,7 +109,6 @@ reference:
   - group_map
   - group_modify
   - group_trim
-  - group_split
 
 - title: Superseded
   desc: >