RFC: Multi-file changelogs

[newpavlov]

Rendered

This proposal defines a multi-file approach for handling changelogs with closer crates.io integration. It's proposed as a compatible alternative to using changelog field in the Cargo.toml.

It was initially part of this RFC.

[killercup]

I'm not yet sure if I like this or not. Having a changelog as prominent feature will be good, though!

Things that just came to my mind:

• Please add an empty line below each headline in markdown text :)
• I think it'd be a good idea to also have a canonical naming schema for git/hg/... tags that correspond to version in the changelog
  • I currently use Github releases for that, and I think syncing it with the changelog is not hard
  • This should also work for multi-crate repositories

[newpavlov]

@killercup
I've used keepchangelog format as an example and they do not use empty lines after headlines. I think it's not important, as rendered result will be the same.

I haven't thought about naming schema for repository tags, but I am not sure how to integrate them into this proposal. Simply add link in the generated headlines which will point to the repository? Then we'll need to write support not only for VCSes, but also for different repositories. I think it's better to leave this functionality for future extensions.

[tblair]

For the reasons mentioned in my previous comment, I'm 👎 on this one. This kind of functionality is useful, but too opinionated and should be part of tools on crates.io, not part of cargo proper.

Perhaps cargo changelog could act as a hook to run a changelog tool? The default can assume a manually-curated CHANGELOG.md, but project authors that want to adopt this multi-file approach or any other generating approach would add a line to Cargo.toml to invoke their chosen tool.

[newpavlov]

@tblair
Hm, it could be an interesting solution to use hooks to external tools on cargo publish which will generate changes description, but we'll have to either duplicate information into generated file (be it from small changelogs as described here, from github releases, clog, or whatever), or to split changelog information from the crate and supply it as a separate meta-information. Both approaches have their respective drawbacks.

[withoutboats]

I think this makes sense as an out-of-band tool, which compiles this directory to a single CHANGELOG.md file for cargo to pick up using whatever mechanism is decided in #2129

[newpavlov]

I will close this RFC and will try to write an extension RFC for supporting changelog hooks.