Adhere to CRAN Submission Policy

Oct 13, 2025 by wbrum.org 99 views

Introduction

Releasing a package on CRAN (Comprehensive R Archive Network) is a crucial step in making your R package available to the R community. This article provides a comprehensive guide on how to prepare, test, and submit your package for release on CRAN.

Blocked by

Before starting the release process, make sure to address the following:

PRs

[ ] PR 1: This PR is blocking the release, please resolve it before proceeding.

Issues

[ ] Issue 1: This issue is blocking the release, please resolve it before proceeding.

Pre-release

Before starting the release process, make sure to:

Adhere to CRAN Submission Policy

Make sure you adhere to the CRAN submission policy:
- https://cran.r-project.org/web/packages/submission_checklist.html
- https://cran.r-project.org/web/packages/policies.html
Review the submission checklist and policies to ensure your package meets the requirements.

Resolve High Priority Bugs

Make sure that high priority bugs (label "priority" + "bug") have been resolved before going into the release.
Review the bug tracker to ensure that all high priority bugs have been addressed.

Review Old/Hanging PRs

Review old/hanging PRs before going into the release (Optional).
Make sure that all PRs are up-to-date and do not contain any conflicts.

Revisit R-package's Lifecycle Badges

Revisit R-package's lifecycle badges (Optional).
Make sure that the badges are up-to-date and reflect the current state of the package.

Ensure Upstream Dependencies are Accepted

Make sure that all upstream dependencies of this package that need to be submitted to CRAN were accepted before going into release activities.
Review the dependencies to ensure that they are up-to-date and accepted by CRAN.

Ensure Integration Tests are Green

Make sure that integration tests are green 2-3 days before the release.
Review the test logs to ensure that there are no warnings or notes.

Decide What Gets Merged in

Decide what gets merged in before starting release activities.
Make sure that all changes are reviewed and approved before merging them into the release branch.

Release

Prepare the Release

Create a new release candidate branch:
- git checkout -b release-candidate-vX.Y.Z
Update the NEWS.md file to reflect a holistic summary of what has changed in the package.
Remove the additional fields (Remotes) from the DESCRIPTION file where applicable.
Make sure that the minimum dependency versions are updated in the DESCRIPTION file for the package and its reverse dependencies (Optional).
Increase versioned dependency on {package name} to >=X.Y.Z (Optional).
Commit your changes and create the PR on GitHub (add "[skip vbump]" in the PR title).

Test the Release

Execute the manual tests on Shiny apps that are deployed on various hosting providers (Posit connect and shinyapps.io) - track the results in GitHub issue (Applicable only for frameworks that use Shiny).
Monitor integration tests, if integration fails, create priority issues on the board.
Execute UAT tests (Optional).

CRAN Submission

Tag the update(s) as a release candidate vX.Y.Z-rc (e.g. v0.5.3-rc1) on the release candidate branch (release-candidate-vX.Y.Z).
Build the package locally using the command:R CMD build . which will generate a .tar.gz file necessary for the CRAN submission.
Submit the package to https://win-builder.r-project.org/upload.aspx for testing, for more details please see "Building and checking R source packages for Windows": https://win-builder.r-project.org/.
Once tested, send the package that was built in the previous steps to CRAN via this form: https://cran.r-project.org/submit.html.
Address CRAN feedback, tag the package vX.Y.Z-rc(n+1) and repeat the submission to CRAN whenever necessary.
Get the package accepted and published on CRAN.

Tag the Release

If the additional fields were removed, add them back in a separate PR, and then merge the PR back to main (add "[skip vbump]" in the PR title). If nothing was removed just merge the PR you created in the "Prepare the release" section to 'main'. Note the commit hash of the merged commit.
Make sure of the following before continuing:
- CI checks are passing in GH before releasing the package.
- Shiny apps are deployable and there are no errors/warnings (Applicable only for frameworks that use Shiny).
Create a git tag with the final version set to vX.Y.Z on the main branch. In order to do this:
1. Checkout the commit hash.
  - git checkout <commit hash>
2. Tag the hash with the release version (vX.Y.Z).
  - git tag vX.Y.Z
3. Push the tag to make the final release.
  - git push origin vX.Y.Z
Update downstream package dependencies to (>=X.Y.Z) in {package name}. Note: Once the release tag is created, the package is automatically published to internal repositories.

Post-release

Ensure CRAN Checks are Passing

Ensure that CRAN checks are passing for the package.
Review the CRAN checks to ensure that the package meets the requirements.

Publish to Internal Repositories

Make sure that the package is published to internal repositories.
Review the internal repositories to ensure that the package is available.

Update Internal Documentation

Make sure internal documentation is up to date.
Review the internal documentation to ensure that it is accurate and up-to-date.

Review and Update Installation Instructions

Review and update installation instructions for the package wherever needed (Optional).
Make sure that the installation instructions are accurate and up-to-date.

Announce the Release

Announce the release on ________.

Decision Tree

Introduction

Releasing a package on CRAN (Comprehensive R Archive Network) can be a complex process, and it's natural to have questions and concerns. In this article, we'll address some of the most frequently asked questions about releasing a package on CRAN.

Q: What is the CRAN submission policy?

A: The CRAN submission policy is a set of guidelines that package authors must follow when submitting their package to CRAN. The policy can be found on the CRAN website at https://cran.r-project.org/web/packages/submission_checklist.html.

Q: What are the requirements for a package to be submitted to CRAN?

A: A package must meet the following requirements to be submitted to CRAN:

The package must be written in R.
The package must be in a format that can be easily installed and used by R users.
The package must have a clear and concise description of its purpose and functionality.
The package must have a set of tests that can be run to ensure that it works correctly.
The package must have a set of documentation that explains how to use it.

Q: What is the difference between a release candidate and a final release?

A: A release candidate is a version of the package that has been tested and validated, but has not yet been officially released. A final release is the official version of the package that has been tested and validated, and is ready for use by R users.

Q: How do I create a release candidate?

A: To create a release candidate, you will need to:

Create a new branch in your package's Git repository.
Make any necessary changes to the package.
Commit the changes and push them to the branch.
Tag the branch with a version number (e.g. v0.5.3-rc1).
Build the package and test it to ensure that it works correctly.

Q: How do I submit my package to CRAN?

A: To submit your package to CRAN, you will need to:

Create a new issue on the CRAN website.
Attach the package to the issue.
Fill out the submission form with information about the package.
Wait for CRAN to review and validate the package.

Q: What happens if my package is rejected by CRAN?

A: If your package is rejected by CRAN, you will receive an email with feedback on why the package was rejected. You will need to address the issues raised in the feedback and resubmit the package for review.

Q: How do I update my package after it has been released?

A: To update your package after it has been released, you will need to:

Create a new branch in your package's Git repository.
Make any necessary changes to the package.
Commit the changes and push them to the branch.
Tag the branch with a new version number (e.g. v0.5.4).
Build the package and test it to ensure that it works correctly.
Submit the updated package to CRAN for review and validation.

Q: What is the CRAN release decision tree?

A: The CRAN release decision tree is a set of guidelines that package authors must follow when releasing a package on CRAN. The decision tree can be found on the CRAN website at https://github.com/insightsengineering/.github/blob/main/.github/ISSUE_TEMPLATE/RELEASE_DECISION_TREE.md.

Conclusion

Releasing a package on CRAN can be a complex process, but with the right guidance and support, it can be a successful and rewarding experience. We hope that this Q&A article has provided you with the information and answers you need to successfully release your package on CRAN.