From 33f272819360eabe8a59865625bd1fc0d2982d97 Mon Sep 17 00:00:00 2001
From: math-mcshane <math.mcshane@gmail.com>
Date: Fri, 19 Sep 2025 14:57:18 -0500
Subject: [PATCH 1/2] Deprecating the use_pipe() function. Fixes #2124

---
 R/pipe.R                      | 18 ++++++++++++++++++
 R/utils-pipe.R                | 14 ++++++++++++++
 man/pipe.Rd                   | 20 ++++++++++++++++++++
 man/use_pipe.Rd               | 19 ++++++++++++++++++-
 tests/testthat/_snaps/pipe.md |  8 ++++++++
 tests/testthat/test-pipe.R    |  9 +++++++++
 6 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 R/utils-pipe.R
 create mode 100644 man/pipe.Rd

diff --git a/R/pipe.R b/R/pipe.R
index dd36544cb..78232b0fd 100644
--- a/R/pipe.R
+++ b/R/pipe.R
@@ -12,13 +12,31 @@
 #' 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 `|>`.
+#' To read about the differences, read this `tidyverse`
+#' [blog post](https://www.tidyverse.org/blog/2023/04/base-vs-magrittr-pipe/)
+#' describing some special cases where using the base R pipe requires handling
+#' different from the `magrittr` pipe, including using
+#' * `x |> f(1, y = _)` instead of `x %>% f(1, y = .)`,
+#' * `x |> (\(x) x[[1]]))()` instead of `x %>% .[[1]]`,
+#' * `x |> (\(x) f(a = x, b = x))()` instead of `x %>% f(a = ., b = .)`, and
+#' * `x |> f()` instead of `x %>% f`.
+#'
 #' @export
 #'
+#' @keywords internal
+#'
 #' @examples
 #' \dontrun{
 #' use_pipe()
 #' }
 use_pipe <- function(export = TRUE) {
+  lifecycle::deprecate_warn(when = "3.2.2", what = "use_pipe()")
+
   check_is_package("use_pipe()")
   check_uses_roxygen("use_pipe()")
 
diff --git a/R/utils-pipe.R b/R/utils-pipe.R
new file mode 100644
index 000000000..fd0b1d13d
--- /dev/null
+++ b/R/utils-pipe.R
@@ -0,0 +1,14 @@
+#' Pipe operator
+#'
+#' See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details.
+#'
+#' @name %>%
+#' @rdname pipe
+#' @keywords internal
+#' @export
+#' @importFrom magrittr %>%
+#' @usage lhs \%>\% rhs
+#' @param lhs A value or the magrittr placeholder.
+#' @param rhs A function call using the magrittr semantics.
+#' @return The result of calling `rhs(lhs)`.
+NULL
diff --git a/man/pipe.Rd b/man/pipe.Rd
new file mode 100644
index 000000000..a648c2969
--- /dev/null
+++ b/man/pipe.Rd
@@ -0,0 +1,20 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utils-pipe.R
+\name{\%>\%}
+\alias{\%>\%}
+\title{Pipe operator}
+\usage{
+lhs \%>\% rhs
+}
+\arguments{
+\item{lhs}{A value or the magrittr placeholder.}
+
+\item{rhs}{A function call using the magrittr semantics.}
+}
+\value{
+The result of calling \code{rhs(lhs)}.
+}
+\description{
+See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details.
+}
+\keyword{internal}
diff --git a/man/use_pipe.Rd b/man/use_pipe.Rd
index eee140aa0..5ab4b5d3d 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{|>}.
+To read about the differences, read this \code{tidyverse}
+\href{https://www.tidyverse.org/blog/2023/04/base-vs-magrittr-pipe/}{blog post}
+describing some special cases where using the base R pipe requires handling
+different from the \code{magrittr} pipe, including using
+\itemize{
+\item \code{x |> f(1, y = _)} instead of \code{x \%>\% f(1, y = .)},
+\item \verb{x |> (\\(x) x[[1]]))()} instead of \code{x \%>\% .[[1]]},
+\item \verb{x |> (\\(x) f(a = x, b = x))()} instead of \code{x \%>\% f(a = ., b = .)}, and
+\item \code{x |> f()} instead of \code{x \%>\% f}.
+}}
 }
 \description{
 Does setup necessary to use magrittr's pipe operator, \verb{\%>\%} in your package.
@@ -27,3 +43,4 @@ use.
 use_pipe()
 }
 }
+\keyword{internal}
diff --git a/tests/testthat/_snaps/pipe.md b/tests/testthat/_snaps/pipe.md
index fc4a96be0..8da3982dd 100644
--- a/tests/testthat/_snaps/pipe.md
+++ b/tests/testthat/_snaps/pipe.md
@@ -5,3 +5,11 @@
     Output
       [1] "#' @importFrom magrittr %>%"
 
+# use_pipe() should produce a lifecycle deprecated warning
+
+    Code
+      use_pipe()
+    Condition
+      Warning:
+      `use_pipe()` was deprecated in usethis 3.2.2.
+
diff --git a/tests/testthat/test-pipe.R b/tests/testthat/test-pipe.R
index 399afa597..88c3602f9 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", {
+  expect_snapshot(use_pipe())
+})
+
+

From e8be9f6e27bc2e42f28b777b697da8c865845994 Mon Sep 17 00:00:00 2001
From: math-mcshane <math.mcshane@gmail.com>
Date: Fri, 19 Sep 2025 15:02:01 -0500
Subject: [PATCH 2/2] Updating test for #2124

---
 tests/testthat/_snaps/pipe.md | 4 +++-
 tests/testthat/test-pipe.R    | 6 +++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/tests/testthat/_snaps/pipe.md b/tests/testthat/_snaps/pipe.md
index 8da3982dd..c05e8b1e0 100644
--- a/tests/testthat/_snaps/pipe.md
+++ b/tests/testthat/_snaps/pipe.md
@@ -8,7 +8,9 @@
 # use_pipe() should produce a lifecycle deprecated warning
 
     Code
-      use_pipe()
+      create_local_package()
+      use_package_doc()
+      use_pipe(export = FALSE)
     Condition
       Warning:
       `use_pipe()` was deprecated in usethis 3.2.2.
diff --git a/tests/testthat/test-pipe.R b/tests/testthat/test-pipe.R
index 88c3602f9..5920391c9 100644
--- a/tests/testthat/test-pipe.R
+++ b/tests/testthat/test-pipe.R
@@ -23,7 +23,11 @@ test_that("use_pipe(export = FALSE) adds roxygen to package doc", {
 })
 
 test_that("use_pipe() should produce a lifecycle deprecated warning", {
-  expect_snapshot(use_pipe())
+  expect_snapshot({
+    create_local_package()
+    use_package_doc()
+    use_pipe(export = FALSE)
+  })
 })