From 145119f762bb50d9309c752e864489d3710643d3 Mon Sep 17 00:00:00 2001
From: "Dr. Ryan McShane" <math.mcshane@gmail.com>
Date: Sat, 20 Sep 2025 10:38:01 -0500
Subject: [PATCH 1/2] Deprecate `use_pipe()`. Fixes #2124

---
 R/pipe.R                      | 23 +++++++++++++++++++++++
 tests/testthat/_snaps/pipe.md |  9 +++++++++
 tests/testthat/test-pipe.R    |  9 +++++++++
 3 files changed, 41 insertions(+)

diff --git a/R/pipe.R b/R/pipe.R
index dd36544cb..13a2b2d12 100644
--- a/R/pipe.R
+++ b/R/pipe.R
@@ -12,13 +12,36 @@
 #' the roxygen template to import and re-export `%>%`. If `FALSE`, the necessary
 #' roxygen directive is added, if possible, or otherwise instructions are given.
 #'
+#'#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' The base R pipe has been available since R 4.1.0, which handles most cases
+#' the `magrittr` pipe handles -- `%>%` can usually just be replaced with `|>`.
+#' However, other differences include:
+#' * instead of `x %>% f(1, y = .)`, use `x |> f(1, y = _)`,
+#' * instead of `x %>% .[[1]]`, use `x |> (\(x) x[[1]]))()`,
+#' * instead of `x %>% f(a = ., b = .)`, use `x |> (\(x) f(a = x, b = x))()`,
+#'     and
+#' * instead of `x %>% f`, use `x |> f()`.
+#' To read about these differences, read this `tidyverse`
+#' [blog post](https://www.tidyverse.org/blog/2023/04/base-vs-magrittr-pipe/).
+#'
 #' @export
 #'
+#' @keywords internal
+#'
 #' @examples
 #' \dontrun{
 #' use_pipe()
 #' }
 use_pipe <- function(export = TRUE) {
+  lifecycle::deprecate_warn(
+    when = "3.2.2",
+    what = "usethis::use_pipe()",
+    details = "It is recommended to use the base R pipe |> in your package
+      instead; it does not require an import."
+  )
+
   check_is_package("use_pipe()")
   check_uses_roxygen("use_pipe()")
 
diff --git a/tests/testthat/_snaps/pipe.md b/tests/testthat/_snaps/pipe.md
index fc4a96be0..7e53b5289 100644
--- a/tests/testthat/_snaps/pipe.md
+++ b/tests/testthat/_snaps/pipe.md
@@ -5,3 +5,12 @@
     Output
       [1] "#' @importFrom magrittr %>%"
 
+# use_pipe() should produce a lifecycle deprecated warning
+
+    Code
+      use_pipe(export = FALSE)
+    Condition
+      Warning:
+      `use_pipe()` was deprecated in usethis 3.2.2.
+      i It is recommended to use the base R pipe |> in your package instead; it does not require an import.
+
diff --git a/tests/testthat/test-pipe.R b/tests/testthat/test-pipe.R
index 399afa597..d1730263e 100644
--- a/tests/testthat/test-pipe.R
+++ b/tests/testthat/test-pipe.R
@@ -1,9 +1,11 @@
 test_that("use_pipe() requires a package", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   create_local_project()
   expect_usethis_error(use_pipe(), "not an R package")
 })
 
 test_that("use_pipe(export = TRUE) adds promised file, Imports magrittr", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   create_local_package()
   use_pipe(export = TRUE)
   expect_equal(desc::desc_get_field("Imports"), "magrittr")
@@ -11,6 +13,7 @@ test_that("use_pipe(export = TRUE) adds promised file, Imports magrittr", {
 })
 
 test_that("use_pipe(export = FALSE) adds roxygen to package doc", {
+  withr::local_options(lifecycle_verbosity = "quiet")
   create_local_package()
   use_package_doc()
   use_pipe(export = FALSE)
@@ -18,3 +21,9 @@ test_that("use_pipe(export = FALSE) adds roxygen to package doc", {
 
   expect_snapshot(roxygen_ns_show())
 })
+
+test_that("use_pipe() should produce a lifecycle deprecated warning", {
+  create_local_package()
+  use_package_doc()
+  expect_snapshot(use_pipe(export = FALSE))
+})

From 5f506b8a7869415bbfdae1d5690f4462a1ed9541 Mon Sep 17 00:00:00 2001
From: "Dr. Ryan McShane" <math.mcshane@gmail.com>
Date: Sat, 20 Sep 2025 10:38:51 -0500
Subject: [PATCH 2/2] Updating documentation

---
 man/use_pipe.Rd | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/man/use_pipe.Rd b/man/use_pipe.Rd
index eee140aa0..220a21cbb 100644
--- a/man/use_pipe.Rd
+++ b/man/use_pipe.Rd
@@ -9,7 +9,23 @@ use_pipe(export = TRUE)
 \arguments{
 \item{export}{If \code{TRUE}, the file \code{R/utils-pipe.R} is added, which provides
 the roxygen template to import and re-export \verb{\%>\%}. If \code{FALSE}, the necessary
-roxygen directive is added, if possible, or otherwise instructions are given.}
+roxygen directive is added, if possible, or otherwise instructions are given.
+
+#' @description
+\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
+
+The base R pipe has been available since R 4.1.0, which handles most cases
+the \code{magrittr} pipe handles -- \verb{\%>\%} can usually just be replaced with \verb{|>}.
+However, other differences include:
+\itemize{
+\item instead of \code{x \%>\% f(1, y = .)}, use \code{x |> f(1, y = _)},
+\item instead of \code{x \%>\% .[[1]]}, use \verb{x |> (\\(x) x[[1]]))()},
+\item instead of \code{x \%>\% f(a = ., b = .)}, use \verb{x |> (\\(x) f(a = x, b = x))()},
+and
+\item instead of \code{x \%>\% f}, use \code{x |> f()}.
+To read about these differences, read this \code{tidyverse}
+\href{https://www.tidyverse.org/blog/2023/04/base-vs-magrittr-pipe/}{blog post}.
+}}
 }
 \description{
 Does setup necessary to use magrittr's pipe operator, \verb{\%>\%} in your package.
@@ -27,3 +43,4 @@ use.
 use_pipe()
 }
 }
+\keyword{internal}