RFC: Crate changelog field

[kxxt]

Rendered

This is the second attempt to introduce the changelog field into crate manifest.

Previous attempt: https://github.com/rust-lang/rfcs/pull/2129

Comparing with previous attempt, this RFC does not impose any format constraint over the contents of the changelog and instead only requires an external URL.

This RFC also reserves the possibility of using a local file included in crate as changelog while leaving it to future RFCs.

[kornelski]

For https://lib.rs, I've tried to guess changelog URLs, and found these problems:

• Crates may have a changelog file in the repo, but repos are annoying to deal with, especially at scale:

  • cloning of the repos just to check the files is a massive operational headache. That's a lot of data, lots of files. Some repos are massive and take an hour to clone. Shallow clones are slow to update, and flaky (e.g. updates cause bloat that triggers expensive git gc, which may break the local copy if interrupted).
  • Plenty of crates have missing or broken repo URLs. Some point to wrong repos (not updated after a fork). Sometimes crates are in a branch, and cloning the main branch gets a wrong thing. Some crates use pijul or hg, or point to a web front-end, not cloneable URL.
  • In monorepos, it's hard to find the relevant file. The /Changelog.md at the root may apply to some primary crate only, or no crates at all. Sometimes it may contain "For the crate X, please see crates/X/Changelog.md". Conversely, there may be a crates/X/Changelog.md that says "We track all changes in the /Changelog.md", or may be a symlink to such file, that really contains all changes for all crates in the repo.
  • People use CHANGELOG.md, Changelog.md, changelog, changes.txt, History.md, HISTORY, etc.

• GitHub-based projects sometimes use GitHub's Releases as a changelog substitute. The GitHub API allows checking if Releases exist, but they may be outdated (project stopped updating them, only does cargo publish), or may be garbage (e.g. release notes are always "please see Changelog.md instead!")

A simple changelog URL won't solve all of these issues, but it can help:

• Crates have a way to be explicit about the preferred location (disambiguate whether they use GH Releases, or a file in the repo, and where it is in a monorepo). changelog = false could be supported too, as a way to opt-out of any default guesswork.
• A single HTTP URL is easier to fetch than a repo (GitHub allows fetching individual repo files via HTTP, but that's GitHub-specific, and requires guessing the file path).

[kornelski]

A changelog URL is useful outside of a README. It can be displayed in a context of a "Just Updated" section of a crate index, where users may wonder what has been updated.

It could be displayed in a summary of cargo update, especially when Cargo can't update a dependency because of semver-major change. In such case the next action for the user is to check what has been broken to see if it's safe to upgrade.

The changelog doesn't have to be parseable, but when it is, it could be neatly integrated into crate's detailed /versions page.

Getting such URL out of a README requires ability to parse the markup, and heuristics to find a relevant link. Something like <a rel=changelog …> could work to make it unambiguous, but the solution is non-obvious, especially in Markdown. HTML parsing is harder than TOML parsing.

The content of the README is user-visible, and not all projects may think it's the right place to advertise a changelog. Metadata gives ability to display the link in the right context, without the rest of the readme.

[mathstuf]

Of particular interest to me is showing the difference between the current version (either in Cargo.toml or Cargo.lock) and the current version. Beyond the "bug fixes and performance improvements" non-statements that are so rife today, it is also the changelog between the previous update and the current one that I really care about, not the one that I have now and the current one.

I understand that changelog formats are all over the place, so getting agreement there is unlikely to get any useful consensus, but at least pointing me at the document itself can get me the information I'm looking for.

[mathstuf]

If anyone could teach Dependabot about that stuff as well, I think we might get more useful update PRs and incentives to actually make (useful) changelogs.

[Aloso]

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

crates.io is already able to render READMEs written in Markdown. Other formats like reStructuredText are not supported, but that doesn't seem to be a big problem.

Cargo doesn't enforce READMEs to be written in Markdown, even .txt is allowed. But since Markdown looks nicer on crates.io, people are encouraged to use it. The same could apply to changelog files.

crates.io could add support for other formats like RST and AsciiDoc, but it's not a requirement to support changelogs as local files.

[Turbo87]

FWIW I'm in favor of this RFC, though I feel a bit uneasy about the "it's a URL... for now... might change later" part. I realize though that having a behavior similar to the readme field (relativ file path) could also be desirable in some situations. I would like to see future extensions of that field to go through the RFC process again though, to ensure that the relevant people can chime in on such changes.

[kxxt]

Sorry for lack of progress here, I'm feeling a little overwhelmed and currently focusing on my academic research. I think maybe pypi's approach is more suitable and scalable, where people can just throw any links they want into a dictionary and pypi can define some of them (like changelog, homepage) as well-known and then display them.

[carols10cents]

I'm in favor of a top-level changelog metadata key rather than an open-ended, user-defined key-value map:

• We already have repository and homepage as top-level fields, so if we added the key-value map, people might expect repository and homepage to be well-known keys in the map as well and we'd have to support both ways (and priority, if a key is specified in both places with different values) forever
• User-defined metadata seems like it'd become a mess, with people adding silly things, trying to do XSS or other attacks, swear words or other things that need moderation attention, etc. Cargo/crates.io should be opinionated instead.