Re: [R-pkg-devel] What counts as an API change?
On 26/09/2019 4:22 a.m., neonira Arinoem wrote: Very interesting thread. Indeed just got one question in relationship with SEMVER and API. For a given package, does CRAN adapt the control and acceptance processes according to SEMVER, when submitting a new package version ? Any reference material about CRAN control and acceptance processes are welcome. Haven't found any yet online. CRAN requires that your new version is greater than the existing one; it also flags high version numbers, e.g. those that follow Hadley's recommendation of using 9000 to signal "in-development". I imagine it would also flag non-standard version numbers, i.e. ones that the package_version(strict = TRUE) function doesn't accept. Other than that, it more or less ignores the version number. I'm not sure what you mean by "control and acceptance processes". Do you mean internal processes, or the rules submitters need to follow? The latter are documented in the CRAN policies document. Duncan Murdoch Neonira Le jeu. 26 sept. 2019 à 01:24, Hugh Parsonage a écrit : The approach I take is a major version increment is required if it requires an existing unit test to be changed or if it requires a reverse dependency to change a unit test. (With the exception of tests marked explicitly as unstable.) In my view the test suite is a good way to advertise exactly what developers can rely on in minor version upgrades. On Wed, 25 Sep 2019 at 11:52 pm, David Hugh-Jones < davidhughjo...@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@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] What counts as an API change?
> The approach I take is a major version increment is required if it > requires an existing unit test to be changed or if it requires a reverse > dependency to change a unit test. > > (With the exception of tests marked explicitly as unstable.) > > In my view the test suite is a good way to advertise exactly what > developers can rely on in minor version upgrades. > > On Wed, 25 Sep 2019 at 11:52 pm, David Hugh-Jones < > davidhughjo...@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@r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/r-package-devel >> > [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] What counts as an API change?
No "maybe" about it. On September 25, 2019 2:28:27 PM PDT, David Hugh-Jones 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 >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 < >> davidhughjo...@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 > >> >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 < >> >> davidhughjo...@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@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. __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] What counts as an API change?
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 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 < > davidhughjo...@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 > >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 < > >> davidhughjo...@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@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]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] What counts as an API change?
"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 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 >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 < >> davidhughjo...@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@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. __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] What counts as an API change?
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 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@r-project.org mailing list >https://stat.ethz.ch/mailman/listinfo/r-package-devel -- Sent from my phone. Please excuse my brevity. __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
[R-pkg-devel] What counts as an API change?
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@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
