search

rust-lang / flate2-rs

DEFLATE, gzip, and zlib bindings for Rust
https://docs.rs/flate2
Apache License 2.0
929 stars 163 forks source link

Introduce a changelog with `cargo changelog` #354

Closed Byron closed 1 year ago

Byron commented 1 year ago

This is a proposal for maintaining a changelog, which currently does not exist.

The way this works is to use conventional commits only when those notes should appear in the changelog next time it is updated with cargo changelog or cargo smart-release.

This way, useful changelog can be generated with minimal effort, while making it possible to hand-write portions of it as one sees fit.

I am using this system to maintain changelogs for more than 40 interconnected crates over at gitoxide, and without it I would definitely have lost my sanity already.

With that said, I understand that this might be a complicated topic and if there is any hestancy there is certainly no issue to continue without a changelog as well.

CHANGELOG.md rendered MAINTENANCE.md rendered

Byron commented 1 year ago

Thanks, that's a great idea! I have added a MAINTENANCE.md document where I am guessing how the current workflow might have been, along with the additions needed to maintain the CHANGELOG.md.

Since I opened this PR thinking there was no changelog at all, I admit that having to do extra steps to maintain it seems like a nuisance. After all, it's meant to be fully automatic but without the use of cargo smart-release that's not happening and I think in this case, there is also no need for it either (and it would force the tagging convention to v<version> from <version>).

Considering all that, I think maybe it's enough to document the current release workflow and add a line that has us auto-generate the CHANGELOG.md for people who (like me) don't look at GitHub releases and expect to see a file. That would be minimal added effort I think, while adding a lot of value.

I am looking forward to hearing what you think.

Byron commented 1 year ago

Closing as the current workflow with GitHub generated changelogs seems to be sufficient while the GitHub dependency isn't a problem, might as well embrace it.

However, I will open another PR with the new maintenance document.