NEWS advises re-using <h1>, contradicting other HTML/markdown advice elsewhere

[MichaelChirico]

style/news.qmd

Line 109 in 8d69afc

Each release should have a level 1 heading (`#`) containing the package name

https://www.youtube.com/watch?v=GIn5qJKU8VM

https://yoast.com/one-h1-heading-per-post/

https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements

Wouldn't a better NEWS style be like

# <package> NEWS

## release 1

## release 2

## release 3

[luciorq]

The current NEWS.md format simply reflects a conversion from the LaTeX content in the R NEWS.Rd file.

According to the R manuals, the recommendation is to follow the GNU project conventions:

For the conventions for files NEWS and ChangeLog in the GNU project see https://www.gnu.org/prep/standards/standards.html#Documentation.

In addition, the documentation for the utils::news() function states:

 'NEWS.md':

       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.  Where available,
       secondary headings are taken to indicate categories.  To
       accommodate for common practice, news entries are only split
       down to the category level.

However, the current format of NEWS.md is CommonMark-compliant. Most Markdown linters would flag it for using multiple level-1 headings, which goes against best practices.

It's important to note that this behavior stems from base R itself, not from devtools. The NEWS.md file is copied as-is into the installed package directory.
The news database creation and rendering are performed dynamically by utils::news(), which relies on the nested functions tools:::.build_news_db() and tools:::.build_news_db_from_package_NEWS_md() inside it.

For reference, here's the source code for tools:::.build_news_db().

[MichaelChirico]

Ah, so it's really an R issue. I'm not sure I have the heart to advocate for fixing that. Anyway, I don't think there's anything wrong with the guide while that's the R guidance.

[MichaelChirico]

Hm, it seems ?utils::news is being a bit misleading -- actually it's perfectly happy with an h2/h3 hierarchy, though the wording seems to imply it wants h1/h2:

news_fmt <- "%1$s My NEWS

%1$s# pkg 1.0.0 (2020-01-01)

%1$s## Categ 1

%1$s# pkg 0.4.0 (2019-01-01)

%1$s## Categ 1

%1$s## Categ 2"

writeLines(sprintf(news_fmt, ""), h1_tmp<-tempfile())
writeLines(sprintf(news_fmt, "#"), h2_tmp<-tempfile())

build_db_from_str <- function(s) {
  tmp <- tempfile()
  on.exit(unlink(tmp))
  writeLines(s, tmp)
  tools:::.build_news_db_from_package_NEWS_md(tmp)
}
all.equal(
  build_db_from_str(sprintf(news_fmt, "")),
  build_db_from_str(sprintf(news_fmt, "#"))
)
# [1] TRUE

[MichaelChirico]

Let's see 🤷 https://stat.ethz.ch/pipermail/r-devel/2025-May/084009.html

[luciorq]

Indeed, this is great!

It’s also worth discussing what the top-level H1 heading should look like. Some possible conventions include:

• Just the package name:

  # PkgName

• Package name followed by "NEWS":

  # PkgName NEWS

• Package name followed by "ChangeLog":

  # PkgName ChangeLog

• Or omitting the package name entirely, using only "NEWS" or "ChangeLog":

  # NEWS

It would be helpful to agree on a recommended pattern for consistency across packages.

P.S. "ChangeLog" with capitalized "L" comes from the GNU documentation, but I'm not sure if that can be considered a widely used standard.

[MichaelChirico]

It's very common, there are dozens/hundreds of examples on CRAN, but there is usually a split among packages using NEWS or ChangeLog:

https://github.com/search?q=org%3Acran+path%3A%2FChangeLog%24%2F&type=code

I often see ChangeLog as a developer-facing document -- each commit is documented:

https://github.com/eddelbuettel/rprotobuf/blob/master/ChangeLog

Whereas NEWS is user-facing -- digested & summarized.

So I would say <h1> should be " NEWS", or " Updates".

[MichaelChirico]

OK, ?news now clearer:

r-devel/r-svn@e6ff645

[MLopez-Ibanez]

The h2/h3 hierarchy seems to break pkgdown: https://rdatatable.gitlab.io/data.table/news/index.html

[MichaelChirico]

Argh, thanks for flagging...

[luciorq]

I just found out that the H2/H3 hierarchy also breaks usethis::use_github_release().

If you structure the changelog with H2s for versions and H3s for topics, it pulls all the H2 sections into the GitHub release, not just the latest one.