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

[David Hugh-Jones]

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.
>

	[[alternative HTML version deleted]]