Semantic Versioning Policy and R

[tel]

Hi Jeff,

I'm not sure how it plays out with R/Bioconductor/CRAN but I've found that the Semantic Versioning Policy is extremely useful.

The primary difference between SemVer and what you've prescribed here is the notion of a "public API" upon which those who build atop your package depend. This dovetails neatly with the need for documentation as once you've established version 1.0.0 and solidified your public API, you really commit to using the version number to indicate to your users whether the changes you're making are likely to break their code.

The reason I bring this up is not that it's significantly different than what you wrote, but instead just to stress the notion of a public API. Clearly stating this helps to think about how your packages are structured and also allows you develop a "private API" which can change more quickly without affecting major version numbers. This is useful for continued personal experimentation or slowly adding new functionality to the public API in a backwards compatible fashion.

This is somewhat covered by the documentation sections (and specifically the @export annotations), but I think the concept itself is worth stressing. In a package that really gets used a lot and built upon, careful choice of the public API and maintaining it responsibly is a very definite design task. Spending a little time before v1 working it out can pay out exponentially down the road.

[jtleek]

Great idea and a really interesting connection. Do you think that you could add a couple of sentences with a link as a pull request and add yourself as a contributor on the list at the bottom?