Skip to content

CRAN releases

Jump to bottom Edit New page
Dan Kelley edited this page Jul 6, 2022 · 20 revisions

Parent: Developer

This page outlines procedures for a CRAN release.

Releases are made from the main branch.

As a matter of policy, CRAN releases cannot be made in rapid succession. Two or three releases a year seems to be an upper limit, but oce has traditionally tried for a slower pace, except when the timetable is dictated by changes in other packages or in R itself. Since about the year 2020, it seems that most releases have been in response to changes in R that break the building process.

But the CRAN policies are not the only reason that oce takes a conservative approach to releases. Another benefit is that it lets users focus on their own work, without spending time rewriting their code to keep up with changes to the package. After all, users who want to try out new features can always install from github.

It is important to wait a reasonable time after making any changes to oce. Keeping in mind that the next release is likely 4 to 6 months away, surely it is reasonable to wait a day to let even the most minor improvements to documentation "cool off". A week may be appropriate for small additions to functionality, or a month for significant additions. This is partly a matter of waiting to see if problems arise, but another factor is that changes that "feel right" at first might prove to be inelegant or even counterproductive on second thought.

After the developers (and bug-reporters who are involved in the development) are happy with a change, there are several more technical steps that need attention, in the run-up to a release. These include the following, but the best plan is to look at the source for devtools::release() and to see what questions it will ask, taking any steps that will be required to answer in such a way as to continue. For example, release() demands a spell check, so do that as a first step. It then requires a URL check, so do that, too. You can save a lot of time this way, because any of those steps might change things enough that you'll want to do a full build-check (local and remote) afterwards.

  1. All releases should be discussed in a github issue, so users and co-developers can see the reasons for the release, and track the progress of the tests that are done pre-release.

  2. Don't even consider a release unless the code has "cooled off" for a few days, or a week. Also, be sure that local build-test and build-check actions work. And be sure that remote checks (done with R-CMD-check) work, unless, as is often the case, some fail because of non-oce problems (e.g. that the test machine cannot load some required package, like sf).

  3. Ensure that a local build/check works cleanly. Frankly, you ought to do that after every code change anyway, but be sure to do it again. Be sure to update all your other packages before doing it.

  4. Look at the source of devtools::release() and take the recommended steps so that e.g. when it asks if you've done a spell-check, you can answer in the affirmative. Note that for the question about updating docs, you can use pkgdown::build_site(); I think devtools::release() provides good hints about the other actions you'll need to take. The file check_release.R goes through some of the steps, but note that portions of it might be disabled if things are known to be broken ... un-disable them, please!

  5. Use release() to submit the package. This almost always turns up new problems, and so it can take a few hours even if things go well. And, if there are major problems, then it's back to the start, with a waiting period, and then steps 1 through 5.

  6. Once it's on CRAN, tag the release by doing e.g. as follows (with the proper version number, of course).

git tag -a v1.7-8cran -m "v1.7-8 CRAN"
git push --tags

  1. Merge main into develop.

  2. In develop, bump the version number in NEWS.md and DESCRIPTION, and work in develop for a few weeks or months, until the next CRAN release. It makes sense to carry out many of the actions listed above from time to time. Don't wait for a release to catch spelling errors, broken URLs, or a failing test suite; think of these things as preventative measures, like flossing your teeth.

  3. In the week or so after the submission, check the oce CRAN page multiple times, to track the process of building the package on a variety of machines. It helps to make a checklist, as you can see at https://github.com/dankelley/oce/issues/1970#issuecomment-1175952759 and https://github.com/dankelley/oce/issues/1970#issuecomment-1176055464.

Quick links

Clone this wiki locally