RFC: Crate changelogs

[newpavlov]

Rendered

This RFC proposes addition of changelog support to cargo and crates.io.

The main proposal is to add changelog field to [package] section of Cargo.toml which can point either to changelog file supplied with the crate, or to external resources. (e.g. GitHub releases or custom websites)

In the first case, changelog file should follow the minimal set of rules. Also this RFC specifies additional check for cargo publish, so crate authors will not forget to update changelog before publishing the new version.

Changelog rendering on the crates.io can be done through additional link on top bar:

This proposal initially also included a multi-file approach to handling changelogs. (most of the initial comments discuss this part) While I believe it would be good for ecosystem to define stricter conventions around changelogs with enhanced machine readability, but based on response, I've moved this part to a separate (closed) RFC.

[Lokathor]

I'm not professional enough to write changelogs. Will cargo and/or crates.io be able to automatically generate an API diff from one version to the next and spit out that as the change log?

[newpavlov]

@Lokathor
Certainly not as part of this RFC. But this functionality can be introduced by subsequent RFCs in the form of additional cargo changelog subcommands.

[nvzqz]

Glad my post could help get this discussion going! :)

I don't think that having a changelog be a commit diff is a good idea. There's lots of irrelevant messages from commits like with merge commits.

@Lokathor If you don't believe you're professional enough to write a changelog, open an issue to ask for help with it. The issue will bring attention to the lack of changelog to people who see the repo.

---

Edit:

For this scenario, having a decent grasp of the project's native language (usually English) should be enough for writing a base changelog. If others expect more from it, they can open pull requests to improve it. This can also happen to explain certain nuances of changes that may not be expressed in the original text.

[nvzqz]

How should a changelog address a project that has been deprecated in favor of another project?

And if not in favor of another, it should address that the author may not have enough time to support it. Or maybe the project had unsafe effects (accidental malware?) that people want to study rather than used in legitimate software?

[boustrophedon]

@nvzqz Wouldn't that sort of stuff just go in the README? Changelogs (as promoted by keepachangelog) don't usurp readmes.

[nvzqz]

@boustrophedon the changelog described has an Unreleased section. It would just be a message stating that no more releases should be expected.

[tblair]

I'm uncomfortable with Rust tooling taking an opinionated view towards changelogs, especially when that opinion marginalizes a project like clog that's been part of the Rust ecosystem for a long time now. I can definitely see why people would prefer the keepachangelog.com approach, but I don't think Cargo should make that decision for project authors. This would be especially galling to any project that has put the time and effort into maintaining a conventional commit history.

This is an area where there are multiple specifications and whatever Rust tooling gets built should allow project authors to choose whichever approach they prefer.

For anyone unfamiliar, here is the spec for the conventional commit method of handling changelogs and here are the Angular commit guidelines on which its based.

[sunjay]

I think changelog support would be awesome, but I don't get the need for the custom split-file format. As stated in the RFC, this deviates from the norm. I don't know if anyone would think to look for a changelog folder. I certainly wouldn't want to have one in my repo because I prefer the single file changelog.

I like everything about adding the changelog link to crates.io and I'm in favor of having the key for that in Cargo.toml, but I'm not sold on the split changelog thing. I don't see why the changelog needs be generated at all.

I know maintaining a changelog by updating it's links and adding new sections can be a pain, so maybe an external tool that makes that awesome would be a good idea. Just working on changelogs doesn't seem like something that should be part of cargo.

Thanks for making the RFC! I'm glad someone is talking about this. :)

[vorner]

I like the intent to add a changelog to crates.io and to Cargo.toml. I even agree with requiring certain format (it makes sense, if it needs to be rendered somewhere).

However, I very much dislike the split into files. I keep changelogs with my crates (at least once the API settles a bit), but I prefer having all the changes in one file. It's easier to search for something. And when I download a repository (or open it at github), having to either generate the changelog locally or searching multiple files feels like a lot of added work for no real gain (and keeping a generated file in git is also wrong). Also, having to be online for generating the changelog feels somewhat inconsistent with the fact that almost everything cargo does works offline (except when adding and downloading dependencies).

What work is actually saved by that split? Adding the dates? Moving the lines from unreleased section to the current version? If the changelog has a standardized format (MD with the given sections), any tooling should be able to handle it in a single file as well.

[mehcode]

👍 on prescribing a general format as loose as possible

• Headers with version/date
• Bullet lists with updates
• Bullet lists can be optionally categorized

I'd like to define the layout enough that we could do this on crates.io but no more.

I strongly dislike the tool that generates a changelog from a folder structure being officially part of Rust. I'd rather see that tool compete with clog as separate crates.

---

Huge +💯 to a link. I just think we can do better than a link ( see gemnasium link above ) if we describe a loose format as well.

[est31]

I'm not really a fan of adding yet another folder. One file should be enough IMO. If I look at the changelog I keep for my lewton crate, I see some releases with only two bullet points. Making a file for only one or two bullet points is a waste IMO.

Generally I think we should be as liberal as possible with the changelog format, and not dictate one.

[bluss]

I agree with @est31. From the author's perspective, a file per release is neat and simple. From the user's perspective, when I look at a change log, I am probably reading it like a timeline: I'm going to read everything from some point and up until the current state, so I'll read through multiple releases, and a single file is then much easier to read.

Of course for big enough projects, splitting the change log per release again becomes reasonable.

[sunng87]

+1 for keeping changelogs in a single file. Also I think a changelog needs to be written by hand to include information curated and prioritized.

In recent version of handlebars, I put unreleased changes in an Unreleased section, when the change is merged into master. And I configured cargo-release to replace Unreleased with new version number. Then the changelog is ready.

I knew a lot effort has been put into changelog auto generation. But this is my best workflow by far.

Sent from my Google Nexus 9 using FastHub

[flosse]

+1 for keeping changelogs in a single file. Also I think a changelog needs to be written by hand to include information curated and prioritized.

+1

[arthurprs]

I have mixed feelings about this.

What about just inserting a changelog link on crates.io that shows the rendered CHANGELOG{.md} if present?

[ruuda]

It looks like the consensus so far is that a single file is preferred over multiple files. What the format of that file should be is less clear.

• It could be strictly specified, which can be useful for machine readability, but which would force a format onto projects that might not be suitable for them.
• Projects could be free to choose the format which makes sense for them, just like they can with a readme.

I would prefer the second option. What a good changelog looks like depends a lot on the size, release schedule, and purpose of the project.

[mathstuf]

I'd love to have the changelog rendered, but I'd rather it just be "we will render any of these paths in crates.io" and how it gets there is uncared about (additional tooling is fine). I really don't like the type: prefix specs because I feel it wastes precious subject space (I prefer area: prefixes because they are easier to sort/skim on).

The way I usually do release notes is that each PR which needs one drops a new file in a specified directory and at release time, they get collated into a single file and deleted. This stops conflicts from happening, supports cherry-picking into backport branches easily with no change in process, and allows for the maintainer to collate and group release notes as necessary or wanted.

[newpavlov]

Thank you for your responses!

While it was not my intention I think emphasis on a new multi-file approach was too strong. I've moved it into a separate RFC and updated this one to a minimal version.

One thing which I think is very important is to have at least minimal degree of machine readability and safety check in cargo publish based on that. So cargo will be able to help library authors to remember to update their changelogs.

[mathstuf]

typo: "dropping"

[jimmycuadra]

The changelog field in the Cargo manifest should just be a URL like the documentation field. It doesn't make sense to impose any particular mechanism for change logging. As proposed in the RFC, this would not be useful to me because I use GitHub's releases page instead of a file in the repository. I've also seen some projects use detailed commit messages on Git tags instead of a file. I don't think users really care what format the change log is in, just that there is one and that they can find it.

[newpavlov]

@jimmycuadra
I don't agree with your position, I think it's quite important to have a coherent way of showing changelogs, instead of linking to a dozen of external resources. Also projects which would like to use a different approach always can specify it in the readme.

But either way I will mention your proposal as an alternative solution.

[killercup]

My comment on your other changelog RFC is also valid for this one :) #2131 (comment)

[newpavlov]

@BurntSushi
Yes, it does. It's just that instead of # you use underline style to define headlines. (probably should mention in the RFC that it's fine to use both methods)

[mehcode]

I'd like to see at least the following minimally specified:

• Consistent level markdown headings must start with a semver. To parse, check the first heading of each level for valid leading semver. When found, assume that level is our "version level".

# Anything goes here

Anything goes here.

## 1.2.3

Anything goes here.

## 0.2.3

Anything goes here.

## 0.0.3

Anything goes here.

or

# 1.2.3

Anything goes here.

# 0.2.3

Anything goes here.

# 0.0.3

Anything goes here.

or

### 1.2.3

Anything goes here.

#### Bug Fixes

More anything goes here.

### 0.2.3

Anything goes here.

### 0.0.3

Anything goes here.

---

I don't think we should try and specify the format inside each chunk. I just want crates.io to be able to extract a version chunk and show it.

[newpavlov]

@mehcode
I've tried to define exactly that you've demonstrated in your examples. Probably wording was not clear enough. Later I will update RFC with your examples.

UPD: Well, except for third example. I haven't seen changelogs which use sub-sub-headers.

[withoutboats]

But it means we'll have a significant incoherence in the ecosystem, some will support this feature, others will not. It will make working with changelogs harder, as tools will have to know about different features and their combinations.

We've already established that breaking changes are a no go, which means the guarantees in this RFC are all the guarantees we could enforce. The guarantees in this RFC are that headers begin with a version number. Can you explain how having crates on crates.io which don't follow this format will make it hard for tools to process change logs?

At minimum they can just report an error on those crates - unfortunate but not a big loss. At maximum they can accept slightly more inputs. For example, a more liberal tool might accept headers that containing a semver version in their header, possibly not in the initial position, to handle people who might write "Release 1.2.0" or " (2.0.0)" in their headers.

Moreover, this RFC defines the changelong syntax in terms of markdown. While today crates.io only renders markdown, there are feature requests to render other formats types, such as asciidoc. I feel quite strongly that, at least as far as crates.io is concerned, any features should be based on the header tags in the rendered HTML output, not in the syntax of the source text.

[carols10cents]

I agree with the goals of this RFC, in that making changelogs more visible will encourage more people to keep them!

I'd like to suggest, however, that the changelog key in Cargo.toml could go to a URL or to a file in the .crate package. In both cases, if this key was present, we would show a link on a crate's page to changelog. If the changelog key specifies a file, crates.io would render that using the same mechanisms/support as we recently added for readmes, and the link would go to that file. If the key was a URL, it would be a normal external link.

This would support the case that @jimmycuadra raised of using Github's releases page as the changelog, and would also support people who have a whole website for their crate of which changelogs is one part.

I would be in favor of this proposal if that change was made, but currently I'm skeptical of the (lack of) flexibility the current proposal has.

[tapeinosyne]

Could you please provide examples of changelog formats used in the wild by crates and which do not fall under rules described in the RFC?

Excepting the prohibition of Unreleased or similar, I expect that most projects would fall under the proposed rules. However, there aren't very many in the first place, and "most" of "not many" is not enough, in my eyes, to warrant standardization as a leading step. Standards are expensive demands, and direct experience is valuable. We can draw ideas from other communities, but we need more insight into our own before doing anything so bold as demanding.

As I see it, this argument works better in a backward direction. If it's not a common practice yet then we can establish a good standard, which people will be able to follow, because they'll start to keep changelog after introduction of this feature.

I agree that newly recommended practices should come with guidelines, but not a standard; not for something like changelogs, where needs and wants can vary considerably across projects, as others already remarked.

I also have a scruple: changelogs, like readmes, are traditionally authored in plaintext. From plaintext I expect freedom of form. For a tool to mandate plaintext but demand adherence to external conventions, however reasonable they may be, would be a small treachery: the failure to meet long-established expectations. (Markdown is valid plaintext, at least for the purpose of this comment.) Perhaps the tool could offer conventions which guarantee additional capabilities – much like GitHub may render commit hashes as links in release notes without demanding anything much of maintainers. Again, however, I am not persuaded we should lead with that.

[newpavlov]

I've updated RFC and added ability to link changelogs published on external resources. Hope this will address most of the concerns regarding perceived strictness of the rules, as it will provide additional flexibility if desired.

But I still firmly believe that rules for explicitly provided changelog files and basic cargo publish support should be left as described.

[vorner]

I think the current set of rules makes some kind of sense. I mean, changelog is technically free form and every author can do whatever they like, but:

• It can hardly be called a changelog if it is not separated by versions.
• The rules need to be followed only if you want your changelog to be rendered on crates.io. If you want to link to it (then you provide an url), have it as a .bmp image in your repository (then you don't provide the changelog key), etc, you're free to do that, only crates.io won't provide the service of rendering and hosting it. And if you ask it to render it for you, it is sane to provide a format it understands.
• It is always possible to relax the rules in the future.

There's only the question of the unreleased section. On one hand, it makes sense, because at the time you publish the crate, nothing is unreleased, so that's a lint you forgot to move the entries to specific version. On the other hand it might make sense to keep it there in the meantime, not delete and recreate it every time a release is made. There's the possibility of allowing only empty unreleased section, but that feels a bit adhoc.

Also, I was wondering, could cargo new crate an empty changelog, as a hint that it's a good idea to have one?

[newpavlov]

On the other hand it might make sense to keep it there in the meantime, not delete and recreate it every time a release is made.

Good point, I will add it to unresolved questions. Personally I do not like that much idea to keep it, as I think initially changelog will be rendered in the same way as readme, so it will be strange to see empty "unreleased" section in it. Or we'll need to add filtering which will feel even more adhoc.

Also, I was wondering, could cargo new crate an empty changelog, as a hint that it's a good idea to have one?

I think it сould be done as a separate RFC. Because for example currently cargo new does not create empty readme file, while arguably good readme is more important than changelog, especially for potential crate users.

[bluss]

Some existing crates have a changelog in a different format (restructuredtext) so anything that allows such things are a plus to me. It's not required that it can render it, but it requires that non-markdown isn't forced through a markdown renderer.

[newpavlov]

@bluss
As I wrote in the RFC it's definitely possible to extend number of supported markup languages. But to simplify the process I think it should be done through issues for cargo and crates.io after implementation of this RFC using MarkDown. If we'll support validation it will be logical to synchronously add rendering support to crates.io as well.

[dbrgn]

As the author of the first linked blogpost I very much approve of this RFC in general :) I have a few remarks though.

In my opinion some things in this RFC are too strict:

As a consequence of the last requirement changelog must not contain "Unreleased" section

I think that's overly strict and that Cargo should not add such a requirement. It will only result in workarounds, like not adding a heading for the unreleased changes.

All crate versions listed in the changelog must have been published earlier on crates.io, except the first entry

Why is that? It only makes it harder for projects that have had a few releases before their first crates.io release to publish. I see no advantage in adding this restriction.

In general, I'd either go for a specification that makes the format machine readable (to make it easier for automated tooling), or keep the format unspecified (except for markdown, so it can be rendered). I tend to favor the second approach. It can also be a gradual approach, where advanced rendering is done if the format corresponds to certain rules. As others in this thread have written, we could wait until some conventions form and until some tooling exists. If - for example - cargo would start to show changes on package updates, people would probably automatically start to format their changelogs in a way that they're supported by the tooling.

Oh, and I like the fact that you can link an external changelog, as an escape hatch for people that don't want to conform to the rules required for an explicit changelog file.

Regarding one of the unresolved questions:

Should we check correctness and/or availability of URL in the changelog field?

I would definitely do a check and warn the user if the URL isn't reachable (e.g. if a status code different than 2xx or 3xx is returned). But I'd provide a way to publish even if that URL is (temporarily?) unavailable.

(PS: I found two typos: additionall -> additional and externall -> external)

[tapeinosyne]

I feel we should open another RFC for the sole introduction of the changelog key. That much is uncontroversional, indisputably useful, and there is a strong precedent in readme, whereas detailed changelog formats require far more discussion. If we can agree that any guidelines can be established incrementally as conventions emerge, instead of enforcing a standard from the start, there would be no risk of breaking changes; even then, stabilization could still be delayed.

[newpavlov]

@dbrgn

I think that's overly strict and that Cargo should not add such a requirement. It will only result in workarounds, like not adding a heading for the unreleased changes.

I don't think it makes much sense to have "unreleased" section in the changelog for published crate, especially if changelogs will be initially rendered as readme without any post-processing.

Why is that? It only makes it harder for projects that have had a few releases before their first crates.io release to publish. I see no advantage in adding this restriction.

Hm, you are right, I haven't considered cases when crate can be initially developed without getting published on crates.io. I've removed this requirement.

@tapeinosyne
This "detailed changelog format" currently essentially boils down to "headline must start with the version", plus a safeguard to help crate authors remember to update their changelogs before publishing new crate version, which can be disabled if needed. As I see it, what you propose is to have the second readme, which seriously hinders any attempts to develop tooling around changelogs. And I believe it's overly optimistic to think that such approach will result in emergence of a common convention.

Also it's always useful to keep in mind that: "nothing is more permanent than the temporary".

[dbrgn]

I don't think it makes much sense to have "unreleased" section in the changelog for published crate, especially if changelogs will be initially rendered as readme without any post-processing.

Hm, that's a good point. Some workflows will need to change, as some people add the unreleased section at the same time they release the previous version. But that change can just as well be done after the release commit.