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

[Jeff Newmiller]

No "maybe" about it.

On September 25, 2019 2:28:27 PM PDT, David Hugh-Jones <davidhughjones using gmail.com> wrote:
>Thanks Jeff. My function is currently:
>
>insert_column <- function (ht, ..., after = 0, copy_cell_props = TRUE)
>
>and I want to add a `fill` argument:
>
>insert_column <- function (ht, ..., after = 0, fill = NULL,
>copy_cell_props
>= TRUE)
>
>This is definitely the best place for the fill argument - I wouldn't
>like
>to put it after copy_cell_props.
>
>Actually, thinking about it, both after and copy_cell_props have to be
>named arguments, given the position of ... . So maybe this is my get
>out of
>jail free card. If I add "fill", existing function calls won't break,
>and I
>can call this "adding functionality in a backwards-compatible manner".
>
>David
>
>
>On Wed, 25 Sep 2019 at 17:26, Jeff Newmiller <jdnewmil using dcn.davis.ca.us>
>wrote:
>
>> "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.
>>

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