From 222928ffd2551b328b6b1ceb68b692a53666c822 Mon Sep 17 00:00:00 2001
From: Leonidas Zhak <70497898+LeonidasZhak@users.noreply.github.com>
Date: Fri, 5 Jun 2026 18:52:00 +0800
Subject: [PATCH 1/2] Document progress completion messages

---
 NEWS.md                 | 4 ++++
 R/progress-client.R     | 8 ++++++++
 man/cli_progress_bar.Rd | 8 ++++++++
 3 files changed, 20 insertions(+)

diff --git a/NEWS.md b/NEWS.md
index bb4f7376..e7785cba 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,9 @@
 # cli (development version)
 
+* The `cli_progress_bar()` documentation now shows how to leave completion and
+  failure messages on screen with `format_done`, `format_failed`, and
+  `clear = FALSE` (#610).
+
 * `keypress()` improvements:
   - `timeout` argument to wait at most a given number of seconds for a
     key press.
diff --git a/R/progress-client.R b/R/progress-client.R
index 93612451..edae4463 100644
--- a/R/progress-client.R
+++ b/R/progress-client.R
@@ -216,6 +216,11 @@
 #' like the elapsed time, of the ETA manually. You can also use your own
 #' variables in the calling function:
 #'
+#' To leave a completion or failure message on screen after the progress bar
+#' finishes, set `clear = FALSE` and customize `format_done` and
+#' `format_failed`. The `pb_elapsed` variable is often useful for reporting the
+#' total runtime.
+#'
 #' ```{asciicast progress-format}
 #' #| asciicast_at = "all",
 #' #| asciicast_knitr_output = "svg",
@@ -230,6 +235,9 @@
 #'       "{col_green(symbol$tick)} Downloaded {pb_total} files ",
 #'       "in {pb_elapsed}."
 #'     ),
+#'     format_failed = paste0(
+#'       "{col_red(symbol$cross)} Download failed after {pb_elapsed}."
+#'     ),
 #'     clear = FALSE,
 #'     total = length(urls)
 #'   )
diff --git a/man/cli_progress_bar.Rd b/man/cli_progress_bar.Rd
index fcdd96ae..b28bfb92 100644
--- a/man/cli_progress_bar.Rd
+++ b/man/cli_progress_bar.Rd
@@ -337,6 +337,11 @@ are probably useful to avoid calculating some progress bar quantities
 like the elapsed time, of the ETA manually. You can also use your own
 variables in the calling function:
 
+To leave a completion or failure message on screen after the progress bar
+finishes, set \code{clear = FALSE} and customize \code{format_done} and
+\code{format_failed}. The \code{pb_elapsed} variable is often useful for reporting the
+total runtime.
+
 \if{html}{\out{<div class="sourceCode r">}}\preformatted{fun <- function(urls) \{
   cli_progress_bar(
     format = paste0(
@@ -347,6 +352,9 @@ variables in the calling function:
       "\{col_green(symbol$tick)\} Downloaded \{pb_total\} files ",
       "in \{pb_elapsed\}."
     ),
+    format_failed = paste0(
+      "\{col_red(symbol$cross)\} Download failed after \{pb_elapsed\}."
+    ),
     clear = FALSE,
     total = length(urls)
   )

From faf85aced56f23a66607fba988b01fa796936fc8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A1bor=20Cs=C3=A1rdi?= <csardi.gabor@gmail.com>
Date: Fri, 5 Jun 2026 13:21:22 +0200
Subject: [PATCH 2/2] No NEWS entry for documentation change

---
 NEWS.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index e7785cba..bb4f7376 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,9 +1,5 @@
 # cli (development version)
 
-* The `cli_progress_bar()` documentation now shows how to leave completion and
-  failure messages on screen with `format_done`, `format_failed`, and
-  `clear = FALSE` (#610).
-
 * `keypress()` improvements:
   - `timeout` argument to wait at most a given number of seconds for a
     key press.