Recently, I've been developing my R package - mcradds, which will be my first package released to CRAN. To be honest, finishing coding is just the first step for R package development, whereas I feel like the submission to CRAN is the most challenging for me. This blog is to keep track of something I came across during the submission process to help giving me a reminder when I would develop other packages in next steps. If you are a beginner like me, this blog will be beneficial to you as well.
The main reference is the Chapter 22 Releasing to CRAN in https://r-pkgs.org/release.html. Follow these steps below.
Previous Preparation
Use usethis::use_release_issue() to generate a listing on the github issue page to advise on a series of recommendations you should finish.
If you don't have a README document already, you should create and render devtools::build_readme() it before releasing. Don't forget to add the install instructions in the README. Keep updating the NEW document as well.
A vignette is necessary that is a long-term guide to your package. Use usethis::use_vignette("my-vignette") to create a default template first, and then you can just follow other mature packages's vignettes, through following the similar structure from them is okay (that's what I'm doing).
In addition, a website like pkgdown is also help for users to know more about your package. These functions from usethis package can help your build it. The usethis::use_pkgdown() function to initial setup, and pkgdown::build_site() to render your site, then usethis::use_pkgdown_github_pages() to deployment your site to github and githun action.
Check the DESCRIPTION clearly
- Proofread the title, follow the naming rule, like it should be plain text (no markup), capitalized like a title, and NOT end in a period.
- Provide a good description, which is very important.
- Check version number, updating manually or using
usethis::use_version(). - Don't forget to add (copyright holder) role to
Authors@R. If you are the only developer, you should add three roles and put "aut", "cre" and "cph" together. - Make sure the license is reasonable and correct.
- Add the correct urls following to the CRAN's URL checks, and check with
urlchecker::url_check().
Check and list all spell words in inst/WORDLIST automatically with usethis::use_spell_check(). That's a fantastic way—just a one-line command.
At last, run devtools::check() once again to ensure everything is ready.
Releasing Preparation
As usual, I use devtools::check() to double-check all is still well before I want to merge or commit update. But before releasing, you'd better add remote = TRUE and manual = TRUE to run the R CMD check again, like devtools::check(remote = TRUE, manual = TRUE), which will build and check the manual, and perform a number of CRAN incoming checks.
Maybe you will encounter the same problem I had, like a confused warning pdflatex not found! Not building PDF manual. I didn't understand the meaning of this warning at first. I checked all options in R and Rstudio, but that didn’t work. Finally, I found that it occurred because I didn’t have the pdflatex executive program on this computer!
It's easy to solve the problem if you find it. I chose to install the pdflatex using the solution provided by Yihui Xie, referring to the article https://yihui.org/tinytex/.
install.packages('tinytex')
tinytex::install_tinytex()Another option is to add some more packages for building PDF vignettes of many CRAN packages.
tinytex:::install_yihui_pkgs()At last, if it still doesn't work, ensure the path of pdflatex has been added to your PATH environment on the computer.
After R CMD check, you'd better use devtools::check_win_devel() as this checking with r-devel is required by CRAN policy. And make sure your package can be passed through CRAN's win-builder service, which is only for Windows. Another good option is to use rhub::check_for_cran() that is also a service supported by the R Consortium, to check your package.
If this package is the new submission to CRAN, there are currently no downstream dependencies for it. If not, you should do the reverse dependency checks.
usethis::use_revdep()
revdepcheck::revdep_check(num_workers = 4)or
revdepcheck::cloud_check()After all the above, record comments about the submission to cran-comments.md, and that will be created by the usethis::use_cran_comments() you use at first. There is no need to manually add it.
Submit to CRAN
Once you’re satisfied that all issues have been addressed and it’s time to submit your package to CRAN, run usethis::use_version() to reach the final version you would like for the first release to CRAN, and then submit using devtools::submit_cran() without any hesitation.
Afterwards, you will receive an email telling you that the package is pending a manual inspection of this new CRAN submission. You will get a response within the next 10 working days, but sometime the feedback is very fast.
If there are some comments from CRAN, respond to any CRAN remarks and double-check everything. Fix what needs to be fixed. If not, write and provide a good reason as you can. Don't forget to add a "Resubmission" section at the top of cran-comments.md to clearly identify that the package is a resubmission, and list the changes that you have made. If you want to explain or clarify something, also can be added inside.
At last, if you receive an email telling your package will be published within 24 hours in the correponding CRAN directory, that means your package have been accepted and released on CRAN. And then you should push it to Github with the new version number. And next, use usethis::use_github_release() to create a new release with tag version on your github, and then update the NEW document as well to illustrate that this is the CRAN release.
Now you can continue increasing the version number to the development version using usethis::use_dev_version(). It makes sense to immediately push to GitHub so that any update will be based on the development version.
Other checking lists for CRAN are also available for reference.