Skip to content

Update cran-comments.md template to be more actionable for CRAN maintainers #2112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
coatless opened this issue Mar 12, 2025 · 3 comments
Open

Comments

@coatless
Copy link
Contributor

coatless commented Mar 12, 2025

Summary

The current cran-comments.md template provided by usethis focuses heavily on reporting R CMD check results, which CRAN maintainers don't rely on as they run their own checks. This issue proposes a revised template that focuses on information CRAN maintainers have specifically requested and find actionable during the review process.

Current issues

The current template emphasizes R CMD check results for a new package:

0 errors | 0 warnings | 1 note

However, based on feedback from CRAN maintainers and experiences with submission processes like devtools::release() or a Github Action workflow, the most common issues flagged during review are:

  1. Unanswered questions from previous submissions
  2. Lack of justification for rapid resubmissions
  3. Insufficient information about breaking changes to reverse dependencies

Proposed template change

Replace the current template with one that directly addresses these key concerns:

## Package Submission

* Submission type: [initial/update/resubmission]

## Response to Previous CRAN Feedback

[Direct responses to each point raised in previous submissions]

## Urgency Justification (if applicable)

[Explain why this update is urgent, if submitted soon after previous version]

## Reverse Dependency Impact

* Breaking changes: [Yes/No]
* If Yes:
  * Affected packages: [list]
  * Maintainers notified: [When, response summary]

## Additional Information

[Any other relevant details requested by CRAN maintainers or useful to them]

This change requires updating the template file at inst/templates/cran-comments.md in the usethis package.

@jennybc
Copy link
Member

jennybc commented Mar 12, 2025

Have you got evidence that CRAN actually reads these? I never have, i.e. I feel like I always have to reply-all and address whatever the specific concern is in a hand-crafted email. I basically regard this file as an internal-to-the-package document that tracks submission details over time and that I draw on when writing said emails. In that sense, sticking with the existing format has value.

I'm not saying your proposal is a bad idea, but I think we should acknowledge that this file isn't actually typically consulted by CRAN maintainers, despite the name.

@coatless
Copy link
Contributor Author

@jennybc I do via private communication with CRAN related to non-submission form package submissions.

I can provide off-site. (rOpenSci Slack?)

@jennybc
Copy link
Member

jennybc commented Mar 12, 2025

Sure, I am happy to hear more.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants