Add "changelog" to Cargo.toml and crates.io

[jFransham]

Inspired by this blog post, I think it would be a great idea for the [package] section in the Cargo.toml to contain a changelog option (as it contains a readme option), and for crates.io to recognise this and have it as a link under "Links", or to somehow reference it under the "versions" links.

[dbrgn]

This would be fantastic.

[emoon]

Yeah this would be great to have.

[yupferris]

+1

[dbrgn]

I'm giving this a stab. Do you think the changelog metadata entry should be a file path (relative to Cargo.toml) or an URL? If it were a path, it could be parsed, but since there's no standard changelog format I think a URL would be more flexible.

[alexcrichton]

@dbrgn this'd probably want to be the same as readme which is just a path relative to Cargo.toml. The cargo publish process could then basically make sure it's a file and send it off to crates.io, although crates.io may not necessarily do anything with it just yet.

[zofrex]

Is this still something we want?

[Boscop]

Yes, definitely. I often find myself wading through git commits trying to figure out how much effort it would be to upgrade to a newer version of a crate.
It would be a huge time saver to have a succinct changelog.
The changes should be recorded as a diff from each last version, so that when I'm interested in upgrading from version x to y, it will integrate all those diffs of the intermediate versions into one changelog summary on crates.io.
The changelog should have annotations for how much effort each change requires when upgrading, e.g. 1 to 3 stars *** in front. And if possible it should say what changes have to be made to code using the crate to accommodate each change.

Also, since often the situation occurs where multiple crates depend on each other and updating one requires updating others, (especially with openssl on windows), I would really appreciate a way to figure out quickly if there is a way to update all crates that depend on each other together to newer versions so that they still work with each other.

[dbrgn]

The changelog should have annotations for how much effort each change requires when upgrading, e.g. 1 to 3 stars *** in front.

That is very subjective. But it would be good to at least link to existing CHANGELOGs as a first step.

[Boscop]

Yes, I kinda said it to revive this discussion. It's not really necessary but what would be very useful is to get an changelog summary integrated over all versions from my current version to the one I want to update to.

[newpavlov]

How about instead of using changelog="CHANGELOG.md" provide a folder changelog="changelog" (or maybe even use autodetection as with tests and benchmarks) which will contain files with format <version>.<extension>, something like that:

changelog/
- 0.1.0.md
- 0.1.1.md

Some versions can be omitted, but on omitted minor/major versions it's probably worth to issue warnings. And 0.1.0.md will contain familiar list of changes:

# Added
- foo
- bar
# Depracated
- zoo

And to provide cargo subcommand cargo changelog which will generate full CHANGELOG.md with versions and dates retrieved from crates.io, adding [YANKED] mark when needed. This way changelog will not be desynchronized from submitted crates and we save some work compared to maintaining changelog manually.

[nagisa]

I do this and find it works way better than a file in root IMO.

[dead10ck]

@newpavlov I actually really like that idea, except that I'd maybe add a title section similar to the existing Keep a Changelog format, and always keep an extra newline at the end of the file. That way you can just cat changelog/* to get the whole CHANGELOG.md. This takes care of the problem of having a single file grow forever, and it would make it easy to enforce change logs in CI builds and such.