Draft lifecycle 0.1.0 post

content/articles/2019-08-lifecycle-0-1-0.Rmarkdown

@@ -0,0 +1,253 @@
+---
+title: 'lifecycle 0.1.0'
+author: Lionel Henry
+date: '2019-08-02'
+slug: lifecycle-0-1-0
+description: >
+  lifecycle 0.1.0 is now on CRAN!
+categories:
+  - package
+photo:
+  url: https://unsplash.com/photos/hnUUZMxQwYk
+  author: Nathana blt
+---
+
+```{r setup, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE, comment = "#>"
+)
+```
+
+```{r crayon, include = FALSE}
+colourise_chunk <- function(x, options) {
+  x <- pkgdown:::escape_html(x)
+  sprintf(
+    '<div class = "output"><pre class="knitr %s">%s</pre></div>\n',
+    tolower(options$engine),
+    fansi::sgr_to_html(x)
+  )
+}
+knitr::knit_hooks$set(
+  output = colourise_chunk,
+  message = colourise_chunk,
+  warning = colourise_chunk,
+  error = colourise_chunk
+)
+
+options(crayon.enabled = TRUE)
+```
+
+
+It is with unmeasured exhilaration that we announce the release of [lifecycle 0.1.0](https://lifecycle.r-lib.org) on CRAN. lifecycle is a toolkit for managing the lifecycle of your exported functions with shared conventions, documentation badges, and non-invasive deprecation warnings.
+
+The main goal of lifecycle is to streamline how the evolution of your exported API is communicated to your users. It achieves this by:
+
+* Defining a set of stages that a function or argument can be in.
+
+* Providing badges for each lifecycle stage that you can insert in your documentation.
+
+* Providing a set of functions to signal deprecation warnings with increasing levels of non-invasive verbosity.
+
+We have started using these tools and conventions in r-lib and tidyverse packages a few months ago. We now make them available for all package developers. Install the package from CRAN with:
+
+```{r, eval = FALSE}
+install.packages("lifecycle")
+```
+
+In this post, we'll briefly present the lifecycle workflow. Read the [Get started](http://lifecycle.r-lib.org/articles/lifecycle.html) vignette for a more complete description. Normally you'd call lifecycle functions with the namespace prefix, but for the purposes of illustrating the package we're attaching the package with `library()`:
+
+```{r, message = FALSE}
+library(lifecycle)
+```
+
+
+## Lifecycle stages
+
+The stages for functions and arguments are modelled after the [lifecycle stages for packages](https://www.tidyverse.org/lifecycle/).  There are 4 __development__ stages. Then, if the decision of discontinuing a feature has been made, it goes through 3 __deprecation__ stages.
+
+### Development stages
+
+```{r echo = FALSE}
+knitr::include_graphics("/images/lifecycle/lifecycle-experimental.svg")
+```
+
+This is a new feature that is in the very early stage of development. It is exported so users can start to use it and report feedback, but its interface and/or behaviour is likely to change in the future. It is generally best to avoid depending on experimental features.
+
+```{r echo = FALSE}
+knitr::include_graphics("/images/lifecycle/lifecycle-maturing.svg")
+```
+
+The interface and behaviour of a maturing feature has been roughed out, but finer details are likely to change. It still needs more feedback to find the optimal API.
+
+```{r echo = FALSE}
+knitr::include_graphics("/images/lifecycle/lifecycle-stable.svg")
+```
+
+A feature is considered stable when the author is happy with its interface and behaviour. Major changes are unlikely, and breaking changes will occur gradually, through a deprecation process.
+
+```{r echo = FALSE}
+knitr::include_graphics("/images/lifecycle/lifecycle-questioning.svg")
+```
+
+The author is no longer convinced that the feature is the optimal approach. However, there are no recommended alternatives yet.
+
+
+### Deprecation stages
+
+```{r echo = FALSE}
+knitr::include_graphics("/images/lifecycle/lifecycle-soft-deprecated.svg")
+```
+
+The author is no longer happy with a feature because they consider it sub-optimal compared to some other approach, or simply because they no longer have the time to maintain it. A soft-deprecated feature can still be used without hassle, but users should consider switching to an alternative approach.
+
+```{r echo = FALSE}
+knitr::include_graphics("/images/lifecycle/lifecycle-deprecated.svg")
+```
+
+The feature is likely to be discontinued in the next major release. Users should switch to an alternative approach as soon as possible.
+
+```{r echo = FALSE}
+knitr::include_graphics("/images/lifecycle/lifecycle-defunct.svg")
+```
+
+The feature can no longer be used. A defunct function is still exported, and a defunct argument is still part of the signature. This way an informative error can be thrown.
+
+
+### Adding lifecycle badges in documentation
+
+You can insert the lifecycle badges anywhere in your documentation. First import the badges in your package:
+
+```{r, eval = FALSE}
+# At the time of writing, you need the development version of usethis
+remotes::install_github("r-lib/usethis")
+usethis::use_lifecycle()
+```
+
+Then use the Rd macro `\lifecycle{stage}`:
+
+```{r, eval = FALSE}
+#' \lifecycle{experimental}
+#' \lifecycle{soft-deprecated}
+```
+
+You typically don't need to advertise the status of a function if it is the same as the package as a whole. For instance, if your package is [maturing](https://www.tidyverse.org/lifecycle/#maturing), only signal functions in the experimental, stable, questioning stages, or deprecated stages. A good place to include the lifecycle badge of a function is at the top of the `@description` block. If the function is deprecated, we recommend marking it as internal so it no longer appear in the help index:
+
+```{r, eval = FALSE}
+#' Recoup some local heads outside the sent staged changes
+#'
+#' @description
+#'
+#' \lifecycle{soft-deprecated}
+#'
+#' `git_recoup_head()` recoups any non-indexed downstream heads before a
+#' few relinked local archives.
+#'
+#' @keywords internal
+```
+
+The lifecycle stage of your function is now clearly indicated in its documentation topic:
+
+```{r echo = FALSE}
+knitr::include_graphics("/images/lifecycle/recoup-deprecated.png")
+```
+
+To document the lifecycle stage of an argument, insert the badge in the argument description:
+
+```{r, eval = FALSE}
+#' @param indict_branch \lifecycle{deprecated}
+#'
+#'   If `FALSE`, `git_blend_tag()` parses references from
+#'   the filter-branched upstream.
+```
+
+```{r, echo = FALSE}
+knitr::include_graphics("/images/lifecycle/indict-deprecated.png")
+```
+
+
+### Verbosity of deprecation
+
+As is convention in R, usage of deprecated functions is signalled with warnings. However, lifecycle tries to warn in a non-invasive way. When a deprecated function is called multiple times, only the first time causes a warning. The function then works silently for the rest of the session.
+
+There are two levels of verbosity for deprecated functions, depending on the lifecycle stage. For soft-deprecated features, the verbosity level is minimal. No warning is issued unless the function is called directly from the global environment or from unit tests. This is a way of starting to raise awareness about the deprecation of this function without affecting indirect users.
+
+*   To signal (soft-)deprecation warnings, use `deprecate_soft()` and `deprecate_warn()`:
+
+    ```{r, include = FALSE}
+    # Soft-deprecation warnings are suppressed in the knitr eval env
+    options(lifecycle_verbosity = "warning")
+    ```
+    ```{r}
+    deprecate_soft("0.5.0", "mypkg::foo()")
+    ```
+    ```{r, include = FALSE}
+    options(lifecycle_verbosity = "default")
+    ```
+
+    ```{r}
+    deprecate_warn("0.4.0", "mypkg::bar()")
+    ```
+
+    You can optionally provide a replacement which will be mentioned in the warning message:
+
+    ```{r}
+    deprecate_warn("0.4.0", "mypkg::bar()", "otherpkg::quux()")
+    ```
+
+*   When a function is ready to be effectively discontinued, use `defunct_stop()`:
+
+    ```{r, error = TRUE}
+    deprecate_stop("0.4.0", "mypkg::bar()")
+    ```
+
+*   To control the verbosity of deprecation, use the global option `lifecycle_verbosity`. It can be set to `"quiet"`, `"default"`, `"warning"`, or `"error"`:
+
+    ```{r, error = TRUE}
+    options(lifecycle_verbosity = "error")
+
+    deprecate_soft("0.5.0", "mypkg::foo()")
+    ```
+
+    ```{r, include = FALSE}
+    options(lifecycle_verbosity = "default")
+    ```
+
+    Setting the verbosity to `"warn"` forces warnings to occur each time the function is called, it is no longer shown once per session.
+
+*   Provide additional details about the deprecation with the `details` argument:
+
+    ```{r}
+    details <- "Why this is discontinued"
+    deprecate_warn("0.4.0", "mypkg::bar()", details = details)
+    ```
+
+*   Finally, signal deprecated arguments with the following syntax:
+
+    ```{r}
+    deprecate_warn("0.4.0", "mypkg::bar(old = )", "mypkg::bar(new = )")
+    ```
+
+
+### Deprecation of arguments
+
+Deprecating arguments requires a little more work than deprecating functions because you need to make sure the function still interprets the argument correctly when it is supplied by the user. To help with this, lifecycle provides the `deprecated()` sentinel. All it does is return the missing argument, so you can test whether the argument was supplied explicitly with `rlang::is_missing()` (note that `base::missing()` doesn't work here because it doesn't support complex expressions). If you find the argument non-missing, signal the deprecation warning and handle the user input for compatibility:
+
+```{r}
+git_recoup_head <- function(unwind_head = TRUE, indict_branch = deprecated()) {
+  if (!rlang::is_missing(indict_branch)) {
+    # Signal deprecation
+    lifecycle::deprecate_warn(
+      when = "1.0.0",
+      what = "git_recoup_head(indict_branch = )",
+      with = "git_recoup_head(unwind_head = )"
+    )
+
+    # Compatibility
+    unwind_head <- indict_branch
+  }
+
+  ...
+
+  message("Recouped head of git repo")
+}
+```