r-lib
Update `cran-comments.md` template to be more actionable for CRAN maintainers
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:
https://github.com/r-lib/usethis/blob/a653d6e05f9172772cea1055f8415cda2f26de69/inst/templates/cran-comments.md?plain=1#L3
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:
- Unanswered questions from previous submissions
- Lack of justification for rapid resubmissions
- 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.
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.
@jennybc I do via private communication with CRAN related to non-submission form package submissions.
I can provide off-site. (rOpenSci Slack?)
I feel like I have an active line of communication with Kurt and Uwe and I have not heard any requests for this, and I'm sceptical we want to make changes without that.
