Since I have finally got the blsAPI posted to CRAN I want to capture the lessons learned from this experience. I can honestly say some of this is still black box to me but with persistence I can promise things will work out.
Let’s begin with some back story. My package came from a script that I wrote. I had built and installed the package locally and could use it without any problem. I had posted it on GitHub and when I got a request to publish it on CRAN I thought why not. I created a tar.gz file and submitted it but it was rejected. Here’s what I had to do to get things resolved:
Roxygen2 is Your Friend
Early on I hacked the man page even though there was “% Generated by roxygen2 (4.1.0): do not edit by hand” at the top of it. After reading Hadley Wickham’s guide I learned some neat tricks. Don’t fight roxygen2. Use it.
No Hidden Files
I work primarily in a Windows environment and so my first submission included hidden git files and directories. Delete these out before submitting them. I had to copy the directory over to a Linux machine and clean it up, then build the tar.gz file for submission.
Check it Using RStudio Over and Over
RStudio is a wonderful environment! I learned how to test my package thanks to this article. This introduced me to the concept of a NOTE. As I understand it, a NOTE is like a very mild WARNING. I worked hard to resolve all NOTES because according to Karl Broman
… even a “Note” will likely disqualify you.
No Library or Require Commands – Use Import
The script uses the rjson and RCurl packages. I loaded them in my function using a *cringe* require() call. I quickly changed it to a library() call (read Yihui Xie’s excellent explanation why you should do it too!) but when I checked it in RStudio the feedback was to remove the lines. Then when I commented out the lines the feedback was the functions were not found! After a lot of frustration I found out the secret. In my R file you will see the following:
#' @import rjson RCurl
This is an roxygen2 line that tells the program to load these two libraries. I also added the following to the mysterious DESCRIPTION file:
Imports: rjson, RCurl
These two things ensure the libraries are loaded properly.
Don’t Forget to Export
While I’m thinking of it you have to remember to export your functions. I did it with the following roxygen2 line in the R file:
#' @export blsAPI
This allows people to use your functions. I was getting frustrated because I could check and build my package and install it but couldn’t use it. R kept saying it couldn’t find the function. I added this line and the problem was solved and I felt like an idiot.
Get the Title Case Right!
This was particularly frustrating for me. Burried in Writting R Extensions in the middle of a sentance there is the following clause:
[The title] should use title case (that is, use capitals for the principal words)
There seems to be little agreement out there on what constitutes principal words. Some posts I read explained that of should be “Of” in order to meet the title case requirement. Yes it’s bad English but that’s what you have to do.
Never Give Up, Never Surrender
I had to submit my package 8 times before it was accepted to CRAN. Some of the changes were substantive and some were superficial. Karl Broman gave some sage advice when he said:
Finally, put on your armor. One of the people that handles CRAN submissions can be unnecessarily offensive and pedantic. Try to put his little barbs out of your mind and focus on his actual advice on how to revise your package to make it suitable for CRAN.
With my economic training I viewed some of the request as a “barrier to entry” by the CRAN gatekeepers. I could have become easily offended but I kept working and submitting and was, in the end, successful. And I know you can too.