submit_cran(): explain relation to usethis::use_release_issue() (#2531)

* submit_cran(): explain relation to usethis::use_release_issue() *

See r-lib/usethis#1877.

* Tweak wording and modernize a few things

---------

Co-authored-by: Jenny Bryan <jenny.f.bryan@gmail.com>

Author: florisvdh

R/release.R

@@ -4,12 +4,10 @@
 #'
 #' The package release process will:
 #'
-#' \itemize{
-#'   \item Confirm that the package passes `R CMD check` on relevant platforms
-#'   \item Confirm that important files are up-to-date
-#'   \item Build the package
-#'   \item Submit the package to CRAN, using comments in "cran-comments.md"
-#' }
+#'   * Confirm that the package passes `R CMD check` on relevant platforms
+#'   * Confirm that important files are up-to-date
+#'   * Build the package
+#'   * Submit the package to CRAN, using comments in "cran-comments.md"
 #'
 #' You can add arbitrary extra questions by defining an (un-exported) function
 #' called `release_questions()` that returns a character vector
@@ -203,14 +201,26 @@ cran_comments <- function(pkg = ".", call = parent.frame()) {
 
 cran_submission_url <- "https://xmpalantir.wu.ac.at/cransubmit/index2.php"
 
-#' Submit a package to CRAN.
+#' Submit a package to CRAN
 #'
-#' This uses the new CRAN web-form submission process. After submission, you
-#' will receive an email asking you to confirm submission - this is used
-#' to check that the package is submitted by the maintainer.
+#' @description
+
+#' This submits your package to CRAN using the web-form submission process.
+#' After submission, you will receive an email asking you to confirm submission
+#' - this is used to check that the package is submitted by the maintainer.
+#'
+#' You may prefer to use `submit_cran()` indirectly, by calling [release()]
+#' instead. `release()` performs many checks verifying that your package is
+#' indeed ready for CRAN, before eventually asking for your confirmation that
+#' you'd like to submit it to CRAN (which it does by calling `submit_cran()`).
 #'
-#' It's recommended that you use [release()] rather than this
-#' function as it performs more checks prior to submission.
+#' Whether to use `release()` or `submit_cran()` depends on the rest of your
+#' development process. If you want to be super cautious, use `release()`, even
+#' though it may be redundant with other checks you have performed. On the other
+#' hand, if you have many other checks in place (such as automated checks via
+#' GitHub Actions and the task list generated by
+#' [usethis::use_release_issue()]), it makes sense to use `submit_cran()`
+#' directly.
 #'
 #' @template devtools
 #' @inheritParams release