Publish Package

CRAN and Beyond

Once you’ve developed and tested your R package, the next step is sharing it with the broader R community. This typically involves submitting your package to CRAN (the Comprehensive R Archive Network) or publishing it on GitHub for open-source access. In this blog post, we’ll guide you through the process of testing and submitting your package to CRAN, as well as sharing your package on GitHub, a popular platform for version control and collaboration.

1. Testing and Submitting to CRAN

CRAN is the official repository for R packages, and it’s the most widely used platform for sharing R packages. However, before you can submit your package to CRAN, it must meet certain criteria and pass specific tests to ensure it’s stable, well-documented, and free of errors.

Preparing Your Package for CRAN Submission

  1. Ensure your package passes all checks: Before submitting your package, you need to run the R CMD check to ensure that there are no errors, warnings, or notes in your package. This check validates your code, documentation, and metadata to confirm that it follows CRAN’s policies.

    To run the check locally, use the following command:

    r
Copy code
devtools::check()

    This will run the R CMD check process and give you a detailed report. It’s crucial to address any issues before proceeding. Common issues include missing documentation, incorrect file paths, or errors in your code.

  2. Fix any issues: If the check identifies any problems, review the messages carefully and fix them. Pay attention to warnings and notes, as these can prevent your package from being accepted by CRAN.

  3. Add necessary documentation: Ensure your package has a comprehensive DESCRIPTION file with accurate metadata about the package, such as the title, version, dependencies, and author information. CRAN requires this file to be complete and accurate.

    Example of a DESCRIPTION file:

    makefile
Copy code
Package: myPackage
Type: Package
Title: A brief description of what your package does
Version: 0.1.0
Author: Your Name <youremail@example.com>
Maintainer: Your Name <youremail@example.com>
Description: This package performs XYZ tasks.
Depends: R (>= 3.5.0)
License: MIT

  4. Check dependencies: Ensure your package doesn’t have any unnecessary or problematic dependencies. If your package depends on other R packages, make sure to list them under the Imports or Suggests section in the DESCRIPTION file.

    Example:

    makefile
Copy code
Imports:
    dplyr (>= 1.0.0),
    ggplot2

  5. Prepare for submission: If everything looks good and passes all checks, you can prepare the package for submission. The final step is to create a tarball (.tar.gz file) of your package:

    r
Copy code
devtools::build()

    This will generate a .tar.gz file, which is the file format used for CRAN submissions.

Submitting to CRAN

Once your package is ready, you can submit it to CRAN through the official CRAN submission page: https://cran.r-project.org/.

  1. Create a CRAN account: If you haven’t already, you will need to create an account on CRAN. This will allow you to submit and track your package submissions.
  2. Upload your package: After logging in, click the “Submit a package” link, and upload the .tar.gz file you generated earlier.
  3. Wait for CRAN review: Once your package is submitted, the CRAN maintainers will review it. This process can take anywhere from a few days to a few weeks, depending on the volume of submissions and the complexity of your package.
  4. Fix any feedback: If CRAN finds any issues with your package, they will send you feedback. You will need to address these issues and resubmit your package.
  5. Package accepted: If everything passes, your package will be listed on CRAN. You will receive a confirmation email, and your package will be publicly available for users to install via install.packages().

2. Sharing Packages on GitHub

While submitting to CRAN is a formal way to distribute your package, GitHub offers a more flexible, open-source platform for sharing your work. Many R developers publish their packages on GitHub to get early feedback, collaborate with others, or release cutting-edge versions of their work before they’re ready for CRAN.

Setting Up a GitHub Repository for Your Package

  1. Create a GitHub account: If you don’t already have a GitHub account, go to GitHub and create one.

  2. Create a new repository: After logging in, click on the “+” sign at the top right corner and select “New repository.” Choose a name for your repository, ideally the same as your package name, and select the public option (unless you want to keep it private).

  3. Initialize Git: If your package isn’t already under Git version control, initialize Git in your local package directory:

    r
Copy code
usethis::use_git()

    This will create a .git directory and initialize the repository.

  4. Link the repository: After setting up Git, link your local repository to the GitHub repository you created by running:

    r
Copy code
usethis::use_github()

    This will automatically push your package to GitHub.

Pushing Your Package to GitHub

Once your repository is set up, you can push your package to GitHub:

  1. Commit your changes: Commit all the files in your package directory to Git:

    r
Copy code
git add .
git commit -m "Initial commit of my R package"

  2. Push to GitHub: Finally, push your package to GitHub:

    r
Copy code
git push origin master

Your package is now available on GitHub for others to view, use, and contribute to.

Installing from GitHub

Users can install your package directly from GitHub using the devtools or remotes package:

r
Copy code
devtools::install_github("username/repository")

Or:

r
Copy code
remotes::install_github("username/repository")

This is a common method for sharing packages that are still under development or have not yet been submitted to CRAN.

Managing Releases on GitHub

You can create new releases of your package by tagging versions in GitHub. This is useful for providing stable versions of your package for users. Here’s how to do it:

  1. Go to your GitHub repository.
  2. Click on the “Releases” tab.
  3. Click “Draft a new release.”
  4. Add a version number (e.g., v0.1.0) and any release notes.
  5. Click “Publish release.”

3. Conclusion

Publishing your R package is a crucial step in sharing your work with the broader R community. CRAN is the most formal platform for sharing your packages, but GitHub offers a more flexible and accessible alternative for collaboration and versioning. By following the steps outlined in this post, you can ensure that your package is well-prepared for submission and accessible to other R users. Whether you choose CRAN or GitHub, your package will be a valuable contribution to the growing ecosystem of R tools and libraries.