[R-pkg-devel] What counts as an API change?

[Jeff Newmiller]

"assume default values are provided."

Ah, no. Choosing to specify or not specify default values is a critical step. As is deciding where any ... argument will be placed (all specific arguments after that have to be named when called so positional compatibility cannot come back to bite you).

"I wonder if it always matters"

That would depend on the relationship you plan to maintain with users of your package. Still, sometimes breaking changes are necessary for a better future.

I think the definition of breaking is pretty clear if you are precise in your argument lists. (R CMD check is very helpful in pestering you to document your arguments, so you do have the opportunity to be precise in your API definition.) It is really bad to have silent changes in behavior, and precision in specification is crucial to avoid that if you distribute packages.

On September 25, 2019 7:27:25 AM PDT, David Hugh-Jones <davidhughjones using gmail.com> wrote:
>Hi Jeff,
>
>You're right. Indeed, assume default values are provided. I should have
>been more precise.
>
>I understand that the positional behaviour has changed. But I wonder if
>it
>always matters. OTOH I appreciate the force of the idea that an API
>change
>is an API change, and should be defined precisely.
>
>Best,
>David
>
>
>On Wed, 25 Sep 2019 at 15:01, Jeff Newmiller <jdnewmil using dcn.davis.ca.us>
>wrote:
>
>> Both of your examples are incompatible.
>>
>> foo <- function (a, b, c, d, e = NA )
>>
>> (add with default value) would be compatible.
>>
>> Your second example cannot be made compatible even with default
>values
>> because the positional behaviour has changed.
>>
>> On September 25, 2019 6:51:58 AM PDT, David Hugh-Jones <
>> davidhughjones using gmail.com> wrote:
>> >Hi all,
>> >
>> >Philosophical question. My package follows semantic versioning (
>> >https://semver.org). Incompatible API changes should trigger a major
>> >version upgrade. OK, but what counts as an incompatible change to an
>R
>> >API?
>> >Suppose my current function signature is
>> >
>> >foo <- function (a, b, c, d)
>> >
>> >and the new one is
>> >
>> >foo <- function (a, b, c, d, e)
>> >
>> >is that compatible? What if I add an argument, but not at the end:
>> >
>> >foo <- function (a, b, c, e, d)
>> >
>> >That would be incompatible if people have been calling the arguments
>by
>> >order rather than by name. But sometimes that is unlikely: I doubt
>if
>> >many
>> >people write
>> >
>> >lm(y ~ x, mydata, z==3, f, na.omit, "qr", FALSE, FALSE, TRUE, TRUE,
>> >FALSE)
>> >
>> >Should I be strict or relaxed about this?
>> >
>> >Cheers,
>> >David
>> >
>> >       [[alternative HTML version deleted]]
>> >
>> >______________________________________________
>> >R-package-devel using r-project.org mailing list
>> >https://stat.ethz.ch/mailman/listinfo/r-package-devel
>>
>> --
>> Sent from my phone. Please excuse my brevity.
>>

-- 
Sent from my phone. Please excuse my brevity.