Changelog/semver disagreement

[TomFryersMidsummer]

Describe the bug
Semver suggests that 5.0.0 would contain breaking changes from 4.x.y, but the changelog doesn't list any that seem to qualify. This means I don't know whether I can safely update my code to the latest version.

To Reproduce
Steps to reproduce the behaviour:

1. View https://github.com/zip-rs/zip2/blob/master/CHANGELOG.md.
2. Observe that the listed changes for 5.0.0 are all semver-minor.

Expected behavior
The changes in semantic version match the described changes in functionality.

Screenshots

Desktop (please complete the following information):

• OS: Ubuntu 25.04
• Browser Firefox
• Version 5.0.0

Smartphone (please complete the following information):
I have not verified that the changelog looks the same on a smartphone, but would hope that it does.

Additional context
Adding methods to a struct is semver-minor, but the major version has increased. I can see three likely possibilities.

1. There are undocumented breaking changes, in which case the changelog is missing some information.
2. There are no breaking changes, in which case the major version number has been incremented unnecessarily.
3. Adding methods is in this case breaking, because they override some commonly used trait or something. In this case, I think this is unusual enough to be worth spelling out in the changelog.

[Pr0methean]

It's always worth trying to upgrade; even when breaking changes do occur, they tend to affect only a small minority of users.

I'll look into ways to automatically document these breaking changes and check for unnecessary major-version bumps. The tool I'm using, cargo semver, seems to be more oriented toward preventing the opposite problem.

[Pr0methean]

Update: From cargo public-api diff 4.6.1 --all-features:

Removed items from the public API

(none)

Changed items in the public API

(none)

Added items to the public API

+pub fn zip::ZipArchive::by_path<T: core::convert::AsRefstd::path::Path>(&mut self, path: T) -> zip::result::ZipResult<zip::read::ZipFile<', R>>
+pub fn zip::ZipArchive::by_path<T: core::convert::AsRefstd::path::Path>(&mut self, path: T) -> zip::result::ZipResult<zip::read::ZipFile<', R>>
+pub fn zip::ZipArchive::by_path_decrypt<T: core::convert::AsRefstd::path::Path>(&mut self, path: T, password: &[u8]) -> zip::result::ZipResult<zip::read::ZipFile<', R>>
+pub fn zip::ZipArchive::by_path_decrypt<T: core::convert::AsRefstd::path::Path>(&mut self, path: T, password: &[u8]) -> zip::result::ZipResult<zip::read::ZipFile<', R>>
+pub zip::CompressionMethod::Implode
+pub zip::CompressionMethod::Reduce(u8)
+pub zip::CompressionMethod::Shrink

[bart-acc]

Do you manage the library on your own? I might have missed it but there is no issue/discussion on if there should be a new major version, any features people would like to do that need breaking changes, any breaking changes that were avoided and could now be made etc. For example, the lzma-static and xz-static feature flags, introduced LAST MONTH, are already obsoleted by #405, and this breaking change could have removed them, but they were left in.

I don't want to be too negative, maintaining an open source library can be a lot of thankless work but still, multiple things in that process seem wrong to me.

Overall this library seems to change at a breakneck pace and I'm not sure that API stability is properly discussed or that contributions, whether from AI agents or actual people, are properly checked before being accepted.

[Pr0methean]

Do you manage the library on your own?

Yes I do, although another pair of hands would be greatly appreciated.

[Pr0methean]

My general policy is to merge and release all pull requests that serve a useful purpose and aren't made redundant by other PRs, as soon as they satisfy my review and pass all tests (or as soon as I can get them into that state), for 3 reasons:

1. It lets the PR author know I appreciate their contribution.
2. It prevents issue reports on issues for which a fix has already been written.
3. The number of open issues and PRs stays relatively manageable.

That does sometimes mean a lot of releases in a short time, when there are over 60 open issues. I'd be willing to consider a different approach, but I don't know of any that would still meet the above goals, or any reason to give up on those goals.

[Pr0methean]

Part of the problem seems to be that release-plz, the tool that maintains the CHANGELOG, doesn't take into account PRs that are merged while a release PR is being generated and tested. This causes releases with an incomplete CHANGELOG. For example, in #442 (the release PR for 6.0.0) I had to manually add the entry for #435. I've opened release-plz/release-plz#2446 to hopefully get this fixed.

[Pr0methean]

Another upstream issue contributing to this is obi1kenobi/cargo-semver-checks#1466.

[Pr0methean]

Update: per my latest comments on obi1kenobi/cargo-semver-checks#1466 and release-plz/release-plz#2446, I've discovered that the two tools seem to have incompatible expectations about when Cargo.toml is to start reflecting plans for the next release to be minor or major rather than patch. I'm still waiting to hear back on whether the disparity can somehow be reconciled in a development model where all releases are snapshots of the default branch.