Add changelog support to cargo, crates.io and doc.rs.

Motivation

What is a changelog?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why keep a changelog?

To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

Who needs a changelog?

People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how.

Encouraging crate authors to keep changelogs and increase its visibility for crate users will definitely benefit crates ecosystem.

From a consumer's perspective, this feature could make the discovery of the changelog much easier. For instance, the "crates" plugin could leaverage this field to show a link to the changelog when a user hovers on a dependency in Cargo.toml.

crates-hover

Current situation: a consumer usually needs to jump through several hops to find the changelog:

flowchart LR;
    editor["crates" plugin in vscode]
    crates-io[crates.io crate page]
    doc-rs[doc.rs crate page]
    crate-web[crate website]
    github[crate repository]
    google["Google search result"]
    repo-changelog[changelog in repository]
    web-changelog[changelog on a website]
    doc-changelog[changelog on doc.rs]
    editor --> crates-io
    editor --> doc-rs
    crates-io --> github
    github --> repo-changelog
    github --> web-changelog
    github --> doc-changelog
    google --> crates-io
    google --> github
    google --> doc-rs
    google -->|unlikely| repo-changelog
    google --> web-changelog
    google --> doc-changelog
    google --> crate-web
    crate-web --> web-changelog
    crate-web --> repo-changelog
    crate-web --> doc-changelog
    doc-rs --> doc-changelog
    doc-rs --> web-changelog
    doc-rs --> crates-io
    doc-rs --> crate-web
    doc-rs --> github

This topic was brought several times, most notable notions are:

Guide-level explanation

An optional changelog field is available, which is currently in the format of a URL to an external resource.

Examples:

[package]
name = "foo"
version = "0.1.0"
changelog = "https://github.com/foo-org/foo/releases"

[package]
name = "bar"
version = "1.0.0"
changelog = "https://github.com/bar-org/bar/blob/main/CHANGELOG.md"

For crates with changelog field, crates.io and docs.rs show a link to the changelog in the corresponding page of the crate.

Reference-level explanation

Cargo

A new changelog field will be added to crate manifest, which only accepts valid URL for now. However, it is explicitly stated that in the future the field could be extended to handle other formats than URL and such a change is not considered breaking. So external tools should expect that the field could contain contents that are not valid URL and handle it with caution.

For a cargo workspace, it is possible for several crates to share a changelog via the usage of changelog.workspace, just like documentation.workspace.

For now, cargo publish will check if the changelog field is a valid URL, unless --no-verify is also specified. cargo publish does not check if the URL in the changelog field points to a valid changelog resource.

Crates.io and docs.rs

A new link to the changelog will show up in crates.io and docs.rs for crates that uses the changelog field.

crates.io and docs.rs should again check if the field is valid URL. If the field is not valid URL, nothing shows.

For docs.rs, this link can be added to the Links section of the <crate-name>-<version> drop-down menu.

For crates.io, this link can be placed in the right(in desktop mode) sidebar, alongside with other links like Repository and Documentation. And additionally, the link can show in the crate cards in crates.io search results, as Homepage and Repository links also show there.

Drawbacks

This proposal does not check if the changelog field points to a valid external changelog, requiring crate authors to do that check themselves.
This proposal does not require the changelog to be present in the crate, making offline usage of the chagelog field impractical.
This proposal does not constrain the format of the changelog, making it hard for external tools to consume the contents of the changelog.
Although changelog URL usually won't change from release to release, sometimes a crate might change its changelog URL, which could invalidate the changelog URLs in previously published versions. This is a clear indication that changelog URL is inheritly a piece of mutable metadata that could be kept per crate instead of per crate version. However, currently there is no ideal solution to handle mutable metadata associated with crates.

Rationale and Alternatives

Rationale

Most of the time, the producer of changelogs are crate authors and the consumer of changelogs are other crate authors. For human consumption, it is ideal to have the changelog in a rendered format. But handling rendering of various formats in crates.io is a heavy task. However, many existing crates already have changelogs available in their repository and the websites backing their repositories can already render the changelogs. So, in order to avoid unnecessary efforts, this RFC proposes to just use a valid URL for the changelog field.

Alternative: Previously closed RFC

Previously closed RFC proposed to use a strictly formatted Markdown file or an external link for the changelog field. The strict format, while ideal for machine consumption, imposes too much constraint and lead to a refusal.

Another critic of the previous RFC is that if this field is just a link that will be displayed, then it seems to not bring much value over placing a link within a README. However, placing a link in README adds another indirection for discovering the changelog, and it effectively prevents other sources from making the changelog more discoverable. For example, third-party editor plugins showing crate information in the context of cargo manifest files cannot leverage the link from README to make changelog more discoverable.

Alternative: Local File

The changelog field can be a path to a file within the crate, which opens the possibility for crates.io to render it directly. However, people have different opinions when it comes to what format the changelog should use. While markdown is currently the most popular choice, plain text and reStructuredText are also in use. Instead of handling the rendering of various different formats of changelog in crates.io, it is much easier to just have an external link, where an external website handles the rendering of the changelog so that crate authors can use any format they see fit for their changelogs.

And changelogs grow over time, which can take significant amount of disk spaces for crates.io, considering that usually every single release of a crate will contain all changelogs up to that release. This particular drawback can be solved by introducing new linting rules.

From another perspective, using an external link can guarantee that we can always link to the latest changelog, which is supposed to contain all changelog entries from initial versions to unreleased commits. If we adopt the local file approach, when we view an outdated version of a crate on docs.rs, we only get a link to the outdated changelog, which is not helpful for viewing the breaking changes introduced in new versions, requiring another click on the doc.rs page to switch to the latest version.

Alternative: Do Nothing

It has been several years after the initial changelog RFC. We can continue to live without this enhancement.

It is possible to create an external registry that collects the links of changelogs. However, such effort is neither scalable nor ideal.

Prior art

NPM

Before npm v7, files named CHANGES / CHANGELOG / HISTORY are always included regardless of settings. In npm v7, those files are no longer always included. npm does not impose any constraint on the format of those files. And the website of npm registry doesn't make the changelog more accessible to users.

A changelog RFC that purposes to introduce changelog command to npm was approved in 2018 but got withdrawn later in 2021. This command makes it easy to view the changelog for a library.

The main points for withdrawal are

npm no longer always include CHANGES / CHANGELOG / HISTORY files after v7.
Managing changelog is considered outside of the scope of the npm cli
The RFC is long inactive after being approved.
Current npm cli team is unlikely to implement it

PyPI

pyproject.toml supports project.urls table which includes a list of URLs associated with the project. And these URLs are displayed on the left sidebar of the project page on PyPI.

[project.urls]
Homepage = "https://example.com"
Documentation = "https://readthedocs.org"
Repository = "https://github.com/me/spam.git"
Issues = "https://github.com/me/spam/issues"
Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"

They keeps a list of well-known labels which includes changelog(with alias changes, whatsnew and history) and releasenotes.

A search for the usage of changelog url in pyproject.toml yields many results.

CRAN

The R community follows the GNU convention for NEWS and ChangeLog files.

The NEWS file contains a list of user-visible changes worth mentioning. Items for old versions are not discarded. When NEWS file become too big, some of the older items should be moved into ONEWS file and a note referring the user to that file should be put at the end of NEWS file.

The NEWS file can be in plaintext(NEWS), Markdown(NEWS.md) or R document(inst/NEWS.Rd) formats.

The Changelog file is more detailed and accurate, including developer-facing changes.

By default, NEWS file will be included into a CRAN package but Changelog will not, as documented in the package structure of an R package.

The CRAN website shows a link to the rendered NEWS file on the package's web page.

R also provides a function news() for building and querying R or package news information, which comes handy when in a REPL or IDE like RStudio.

Unresolved questions

Future possibilities

Future RFC could make other formats of the changelog field possible as this RFC has explicitly reserved that possibility.

Future RFC could introduce changelog.generator/changelog.format fields which could indicate the generator or the format of the changelog. This is helpful for machine consumption.

Future RFC could introduce a clippy warning that warns if the crate does not contain a changelog field.

crate-changelog-field