[R-pkg-devel] How to format the NEWS.md file for CRAN submissions?

[Duncan Murdoch]

On 24/04/2023 4:39 p.m., Konrad Rudolph wrote:
> My package is creating a CRAN check NOTE because CRAN does not like the way
> my NEWS.md file [1] is formatted.
> 
> I am largely adhering to existing conventions with regards to my NEWS.md,
> in particular the (rather minimal) GNU conventions [2] mentioned in R-exts
> as well as the conventions used by ‘pkgdown’ to compile the file into a web
> page. The one peculiarity of my NEWS.md file (and where it diverges from
> the documented ‘pkgdown’ convention) is caused by the fact that my package
> has undergone a name change in the past. As a consequence, not all headings
> in the NEWS.md file follow the format `# ‹pkgname› ‹version›`.
> Consequently, the CRAN check complains
> 
>>    Cannot extract version info from the following section titles:
>>      modules 0.x
> 
> I have two questions:
> 
> 1. Am I overlooking where the CRAN requirements for NEWS files are
> documented? As far as I can see I am not violating a documented rule.

The documentation is in the ?util::news help topic.  It says:

"File ‘NEWS.md’ should contain the news in Markdown (following the 
CommonMark (https://commonmark.org/) specification), with the primary 
heading level giving the version number after a prefix followed by a 
space, and optionally followed by a space and a parenthesized ISO 8601 
format date."


> 2. What is the best way of avoiding this NOTE _without_ dropping the
> changelog pre package name change? In particular, since ‘pkgdown’ does not
> support this I would like keep these changes in a single NEWS.md file
> rather than moving them into a separate file. Likewise, I think it would be
> misleading (and hence undesirable) to change the section headings to use
> the current package name for the old revisions.

I don't think it cares what the prefix is, so you could use something 
other than the current package name there.

Duncan Murdoch


> 
> [1]
> https://github.com/klmr/box/blob/9f35bd28b26306fe94ade874c2b93a89ae3f3a61/NEWS.md
> [2] https://www.gnu.org/prep/standards/standards.html#NEWS-File
> 
> Cheers,
> Konrad
>