Imagine, the R code you’ve poured your heart and soul into, those clever functions and efficient analysis workflows, no longer just slumbering on your personal computer’s hard drive, but transformed into an elegant, professional toolkit. R users worldwide—be they academic researchers, industry data scientists, or curious learners—can easily obtain and apply your intellectual creations with a simple install.packages("your_package_name") command. Your code might even become a widely adopted standard tool in a particular field. Doesn’t this vision sound captivating?
Encapsulating your code into an R package and submitting it to CRAN (Comprehensive R Archive Network) is the key path to realizing this grand vision. CRAN is not only the official “app store” for the R language but also the go-to platform for R users globally to find and trust various tools. However, for your work to grace this prominent stage, it must evolve from a “personal script” into a “professional resource” that meets community sharing standards. This means your code needs a clear structure, comprehensive documentation, and rigorous testing. This journey is undoubtedly challenging, but the joy of success and its profound impact are absolutely worth your utmost effort.
First, we need to build a “home” for your code that conforms to R package standards. This “home” has a fixed “room” layout—that is, a standard directory structure. Imagine a well-organized house where each room has its specific function. When CRAN reviewers examine your package, the first thing they’ll check is whether this “floor plan” is up to standard. The DESCRIPTION file is the package’s “identity card,” recording basic information; the NAMESPACE file acts like an “access control list,” precisely controlling which functions are exposed; the R/ directory is the “main functional area,” housing your core R code; and the man/ directory is the “manual showroom,” where users can find detailed help documents. CRAN has extremely high requirements for the completeness and standardization of this structure; any “non-compliant construction” could lead to your submission being “politely declined” in the first round.
Speaking of the DESCRIPTION file, it’s practically your R package’s “official ID” on CRAN, and its importance cannot be overstated. CRAN reviewers will meticulously check every piece of information in it, much like customs officers examining a passport: What’s your package name (Package)? What’s the version number (Version)? A concise title summarizing its function (Title), followed by a detailed description (Description). Is the author information (Authors@R) using the person() function correctly, and are roles clearly defined? Most critically, is the license (License) a CRAN-approved open-source license? CRAN has an almost obsessive insistence on the accuracy and completeness of metadata.
Next, let’s focus on the “soul” of your package—the code—and the equally crucial “user manual”—the documentation. How high are CRAN’s documentation requirements? Let’s put it this way: all exported (i.e., user-callable) functions must have detailed and properly formatted help documents, so users can clearly understand how to use your package and what it can do. Here, I highly recommend roxygen2, a “godsend” of a tool. It allows you to conveniently write documentation while writing code. Just add specially formatted comments above your functions, like @param to describe parameters, @return for the return value, @export to declare the function for user access, and, very importantly, @examples to provide runnable example code. CRAN will automatically check if these examples run successfully. If your examples have issues, or depend on packages not declared in the Suggests field, your package is almost certain to be rejected.
Once you’ve carefully written these special comments using roxygen2, you can “summon” the devtools::document() command. Like a diligent assistant, it automatically parses these comments, generates the .Rd help files in the man/ directory, and updates the NAMESPACE file in the root directory. The NAMESPACE file, as mentioned before, acts like an “access control list”; it precisely defines which functions are visible to users (via export directives) and which “components” your package imports from other packages (via importFrom etc.). This automated process can save you a great deal of time and effort. However, if your roxygen2 comments themselves are messy or non-compliant, this assistant can only generate equally unsatisfactory documentation and NAMESPACE files.
Alright, your package is now taking shape. But before sending it to CRAN, the “ultimate testing ground,” you must conduct a rigorous “mock exam” locally by running devtools::check(). This command is an “impartial examiner”; it will perform a comprehensive and extremely strict check on your package, from code standards, documentation completeness, and example code runnability, to dependency correctness and even cross-platform compatibility. Its goal is to sniff out all potential “minefields” before you formally submit. When CRAN reviewers receive your package, one of the first things they do is run similar checks. An ERROR is like a “critical condition notice” and must be “rescued” immediately. A WARNING is equivalent to a “severe warning”; CRAN has extremely low tolerance for these, and virtually all WARNINGs need to be completely resolved. NOTEs are more nuanced; some might be friendly reminders, but many NOTEs can also hint at potential “health hazards” in your package. For example, the common “Undefined global functions or variables” usually means you forgot to declare functions imported from other packages in your NAMESPACE file (e.g., using importFrom), or you directly used “rogue variables” of unknown origin—this is absolutely forbidden on CRAN. CRAN reviewers will carefully examine every NOTE and expect you to provide logical, well-reasoned explanations in your cran-comments.md file (more on this later) for any NOTEs you genuinely cannot eliminate.
At this point, you need to carefully prepare a special “communication letter”—a file named cran-comments.md. This is your primary channel for written communication with CRAN reviewers. In this file, you need to provide them with necessary background information in a clear, polite, and professional tone. First, clearly state whether it’s a new submission or an update to an existing package. If it’s an update, briefly describe the main changes from the previous version. Crucially, if devtools::check() flags any NOTEs that you genuinely cannot eliminate but believe are reasonable, you must provide detailed explanations here, clarifying why these NOTEs can be accepted, or what measures you’ve taken to mitigate them as much as possible. If you’re resubmitting a package that was previously “sent back,” you’ll need to respond point-by-point to CRAN’s previous feedback and detail all the changes you’ve made. Remember, a well-organized, informative, and sincere cran-comments.md file can greatly help reviewers understand your package and may even expedite the review process.
Once all checks and preparations are complete, you can use the devtools::build() command to “bundle” your R package into a .tar.gz source archive. This is the standard “delivery package” you need to submit to CRAN. CRAN only accepts source packages and will perform a strict “unboxing inspection” of the package’s internal structure and content. devtools::build() ensures your package adheres to CRAN’s “packaging specifications,” but it cannot fix fundamental issues inherent in your package.
Everything is ready, just waiting for the final push! Now, open the CRAN submission page (easy to find on the CRAN website). You need to accurately fill in the maintainer’s name and email address—this is CRAN’s sole “messenger” for contacting you. Then, upload the .tar.gz “package” generated by devtools::build() and paste the entire content of your cran-comments.md file into the corresponding text box. Before pressing that exciting “Submit” button, please carefully review all information to ensure it’s flawless. Any errors in the information can stall your submission process. “
After submission, your R package officially enters CRAN’s “review queue,” awaiting “judgment.” This is a manual review process conducted entirely by a team of experienced volunteers. They will meticulously examine your package: from reviewing code, checking documentation, and running examples and tests, to assessing if your package complies with all CRAN Policies—no step is overlooked. This process can take several days, or even weeks, depending on the current number of packages awaiting review and the reviewers’ workload. So, what you need to do is—be patient. CRAN reviewers may contact you via email to point out issues in your package and request modifications. Upon receiving feedback, be sure to read it carefully, understand the root of the problem, and then meticulously make corrections as requested. After making changes, you’ll need to increment the version number in your DESCRIPTION file (e.g., from 0.1.0 to 0.1.1), then resubmit, detailing all adjustments in a new cran-comments.md file. When communicating with CRAN reviewers, always maintain politeness and professionalism, remembering they are all contributing to the R community voluntarily. For first-time submitters, being asked for multiple revisions and resubmissions is very common; don’t be discouraged by this.
Finally, after enduring several rounds of “back-and-forth” refinement and communication, if all goes well, your R package will knock open CRAN’s doors, be gladly accepted, and made public! You’ll receive that coveted CRAN confirmation email—from that moment on, millions of R users worldwide can easily obtain and use your labor of love with the lovely install.packages() command.
