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)

[bb010g]

I don't think external links are a good idea. Changelogs in the repository are useful both for their offline access and for the interface options they allow. Crates.io could gain nicer rendering with a standard format in the future with files, but that requires using GitHub/GitLab/wherever's API and constantly tracking changes for each platform we support for external links.

[ehuss]

We discussed this RFC in the Cargo team meeting, and we feel like we probably don't want to move forward with this at this time. There are some points, such as the proposal for a single format that could be machine-readable that we think may be a little too strict. If the proposal then reduces to just a link that will be displayed, then it seems to not bring much value over placing a link within a README.

We acknowledge that there is a desire to encourage crate authors to provide a changelog, and to make it easier to access that information. We thank everyone for their work and discussion. There may be some solution to improve communication of release notes, but it's not clear what that would look like.

@rfcbot fcp close

[rfcbot]

Team member @ehuss has proposed to close this. The next step is review by the rest of the tagged team members:

• @Eh2406
• @Turbo87
• @alexcrichton
• @ashleygwilliams
• @carols10cents
• @ehuss
• @ishitatsuyuki
• @joshtriplett
• @jtgeibel
• @locks
• @nrc
• @pietroalbini
• @sgrif
• @smarnach
• @steveklabnik
• @withoutboats

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[ishitatsuyuki]

@rfcbot reviewed

[Eh2406]

@rfcbot reviewed

[smarnach]

@rfcbot reviewed

[sgrif]

@rfcbot reviewed

…

On Sun, Sep 22, 2019, 1:56 PM Sven Marnach ***@***.***> wrote: @rfcbot <https://github.com/rfcbot> reviewed — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2129?email_source=notifications&email_token=AALVMK367NYFUMMJNQ4GXLTQK7EV3A5CNFSM4DYOUGE2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7JN3NI#issuecomment-533913013>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AALVMK6EUFCPYS3L72GLYVDQK7EV3ANCNFSM4DYOUGEQ> .

[Turbo87]

@rfcbot reviewed

While I do agree that crates with more than one release should probably have a changelog, I don't think enforcing them like that is something we should do. If we built some sort of rating system into crates.io that judges the quality of a crate we could consider it as part of the metric though.

[jtgeibel]

@rfcbot reviewed

[locks]

@rfcbot reviewed

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to close, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC is now closed.

[georgefst]

Hmm, this is disappointing. The fact that so many crates don't provide any changelog is my number one frustration with the Rust ecosystem. As someone who only sporadically writes Rust, it tends to be that I come back to the language every few months, bump a load of dependencies, then spend ages trying to work out exactly what broke all of my code. I just need a migration guide!

I haven't read all of the above (it's a long discussion!), but would it be fair to say that there was significant support here for the idea that Cargo should encourage crate authors to write human-readable changelogs, but that that got lost amid a lot of bikeshedding about requiring a more precise format? If so, is anyone willing to submit a minimal version of the proposal?

[mathstuf]

If so, is anyone willing to submit a minimal version of the proposal?

IMO, I think "use markdown", "use one of these blessed filenames (CHANGELOG, CHANGELOG.md, etc.)", and "use the version number as a top-level heading (maybe with a v prefix)" is about as structured as anyone is going to agree on.