Revise chapter on lifecycle (#923)

* Write an introduction * Add a section establishing what sort of evolution we care about * Lots of work on versions * Work on backward compatibility * First batch of work on lifecycle * Install pkgsearch * Come back to work on the intro * Just some changes * Connecting "release" to "changing package version number" * More work * Work on breaking changes * More work * Tweaks * More details on deprecation * Polishing in various places * Talk about superseded and legacy behaviour * Mostly finalizing introduction * A bit more about version number here
hadley · Jan 17, 2023 · 5fa8217 · 5fa8217
1 parent 6e22d76
commit 5fa8217
Show file tree

Hide file tree

Showing 7 changed files with 691 additions and 147 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -14,6 +14,7 @@ Imports:
     lubridate,
     nycflights13,
     pak,
+    pkgsearch,
     rlang,
     roxygen2,
     stringi,

diff --git a/R-CMD-check.Rmd b/R-CMD-check.Rmd
@@ -28,7 +28,7 @@ I'm running R 3.1.1 on OS X with a UTF-8 charset:
 -   **Using session charset**: UTF-8
 
 Next the description is parsed and the package version is printed.
-Here I'm checking httr version 0.5.0.9000 (you'll learn more about that weird version number in @sec-release-version).
+Here I'm checking httr version 0.5.0.9000 (you'll learn more about that weird version number in @sec-lifecycle-version-number).
 
 <!-- https://github.com/wch/r-source/blob/trunk/src/library/tools/R/check.R#L3459 -->
 

diff --git a/description.Rmd b/description.Rmd
@@ -291,7 +291,7 @@ usethis::use_package("ggplot2", "Suggests")
 usethis::proj_set(op)
 ```
 
-### Minimum versions
+### Minimum versions {#sec-description-imports-suggests-minium-version}
 
 If you need a specific version of a package, specify it in parentheses after the package name:
 

diff --git a/diagrams/lifecycle.svg b/diagrams/lifecycle.svg
diff --git a/lifecycle.Rmd b/lifecycle.Rmd
diff --git a/notes/scrutinize-section-labels-in-one-chapter.R b/notes/scrutinize-section-labels-in-one-chapter.R
@@ -1,7 +1,7 @@
 library(tidyverse)
 library(parsermd)
 
-file <- "website.Rmd"
+file <- "lifecycle.Rmd"
 (rmd <- parse_rmd(file) |> 
     rmd_select(has_type("rmd_heading")))
 

diff --git a/release.Rmd b/release.Rmd
@@ -7,6 +7,11 @@ status("restructuring")
 
 ## Introduction
 
+(TODO: Some intro text written when this was combined with the lifecycle chapter. Incorporate when I revise this introduction.) ... we delve into the specifics of releasing a package on CRAN and the ongoing work required to keep it safely on CRAN.
+We've been calling out CRAN-specific concerns throughout the book.
+So ??
+is where we underscore some of the most crucial points and, most importantly, can take a holistic look at blah blah CRAN.
+
 If you want your package to have significant traction in the R community, you need to submit it to CRAN.
 Submitting to CRAN is a lot more work than just providing a version on github, but the vast majority of R users do not install packages from github, because CRAN provides discoverability, ease of installation and a stamp of authenticity.
 The CRAN submission process can be frustrating, but it's worthwhile, and this chapter will make it as painless as possible.
@@ -126,7 +131,7 @@ Compared to running `R CMD check` locally, there are a few important differences
     This reminds CRAN that this is a new submission and that they'll need to do some extra checks.
     You can't eliminate this, so just mention in `cran-comments.md` that this is your first submission.
 
-### Reverse dependencies {#release-deps}
+### Reverse dependencies {#sec-release-revdepcheck}
 
 Finally, if you're releasing a new version of an existing package, it's your responsibility to check that downstream dependencies (i.e. all packages that list your package in the `Depends`, `Imports`, `Suggests` or `LinkingTo` fields) continue to work.
 To help you do this, ~~devtools provides `devtools::revdep_check()`~~.