R Packages, 2nd Edition

Chapter 21. Lifecycle

This chapter is about managing the evolution of your package. The trickiest part of managing change is balancing the interests of various stakeholders:

• The maintainer(s), which includes you and possibly others, especially in the future.

• The existing users, which could be just you or a small group of colleagues or it could be tens or hundreds of thousands of people.

• The future users, which hopefully includes the existing users, but could potentially include many more people.

It’s impossible to optimize for all of these folks, all of the time, all at once. So we’ll describe how we think about various trade-offs. Even if your priorities differ from those of the tidyverse team, this chapter still should help you identify issues you want to consider.

Very few users complain when a package gains features or gets a bug fix. Instead, we’re mostly going to talk about so-called breaking changes, such as removing a function or narrowing the acceptable inputs for a function. In “Backward Compatibility and Breaking Change”, we explore how to determine whether something is a breaking change or, more realistically, to gauge where it lies on a spectrum of “breakingness.” Even though it can be painful, sometimes a breaking change is beneficial for the long-term health of a package (see “Pros and Cons of Breaking Change”).

Since change is inevitable, the kindest thing you can do for your users is to communicate clearly and help them adapt to change. Several practices ...