Handeling Breaking Changes

Package development
#1

Our package has a moderate user base (~50k downloads) and we are currently contemplating large breaking changes to the core of the package. (changing from "stringy" arguments to R-expressions)
Our package is marked as stable but also has semver: 0.2.2 so big changes could be expected...

What would be the best way to handle this situation?

  • The infamous ggplot -> ggplot2 route
  • Visible warnings 1 - 2 versions prior to the change
  • Keep backwards compatibility for a few versions (which would mean quite a lot of additional work/code)
  • ?

Other than ggplot/2 I personally do not know of any examples for large breaking changes like that.
Thanks for your help in this quandry!

1 Like
#2

First, what do you perceive as the benefit to making this change?

Absent a very compelling reason it's generally very poor form to make breaking changes.

If the reason is sufficient to justify something so drastic, the proper way to handle things is to:

  1. Add code to enable the new functionality.
  2. Deprecate the functionality and document that.
  3. Maintain both for an appropriate amount of time, depending on your specifics that could be six months, a year, or longer.
  4. Remove the code enabling the previous behaviour.

All that said, while I don't know the details of your code or your package i don't think it sounds like much additional effort to accept strings in addition to expressions as it's very easy to turn the former into the latter.

2 Likes
#3

Thank you for the input. After looking at the code again, I think you are right, most strings used are easily converted to expressions as they more or less already are, the few that are not valid R Syntax are already parsed in some way so it should not be an issue to adapt that for backwards compatibility.

There are several advantages least of all is following a more R-like API. The main advantage would be easier code, better maintainability, and future-proofing of the backend.

On the users' side, it would be a more natural workflow (the package is simstudy, we use formulas for simulating data, inputting them as an expression is much cleaner imho) and allows for easier implementation of custom distributions and more flexibility.

1 Like
#4

In case it's useful to anyone reading this thread: I'll mention the chapter on changing stuff in the rOpenSci dev guide (disclaimer: that I maintain) with some general advice on the topic. :slightly_smiling_face:

1 Like
#5

A recommended read in any case!

1 Like
#6

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.

If you have a query related to it or one of the replies, start a new topic and refer back with a link.