Bloc: Using semver and mark breaking changes when they happen

[nerder]

Is your feature request related to a problem? Please describe.
Would be nice to follow semver for versioning of the packages here, i'm not able to understand how the version number got chosen at the moment, plus breaking changes are not explicit when they happen.

Describe the solution you'd like
https://semver.org/

Describe alternatives you've considered
None
Additional context
This is the defacto standard for libraries

[felangel]

Hi @nerder 👋
Thanks for opening an issue.

Is there a specific case you're referring to? We use semver in all bloc packages.

[nerder]

As far as i know/understand, insemver :

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
PATCH version when you make backwards compatible bug fixes.

This does not seems like the case here for instance

This is a minor version upgrade but you deprecate a method entirely breaking the api it means that i can't simply upgrade a minor version here because it will make my code base to not compile anymore, and this is the definition of a Breaking change which should trigger a major version not a minor.

TLDR; from v0.15.0 you should have gone to v1.0.0not to v0.16.0 if you were following semver

I've seen this in equatable as well, not sure in flutter_bloc.

[felangel]

This is because those changes were pre-1.0.0 but it was still following semver.

If your pubspec.yaml looked like:

bloc: ^0.15.0

You would not automatically get the updates to v0.16.0 as they were breaking changes.

Although semantic versioning doesn’t promise any compatibility between versions prior to 1.0.0, the Dart community convention is to treat those versions semantically as well. The interpretation of each number is just shifted down one slot: going from 0.1.2 to 0.2.0 indicates a breaking change, going to 0.1.3 indicates a new feature, and going to 0.1.2+1 indicates a change that doesn’t affect the public API.
https://dart.dev/tools/pub/versioning

[nerder]

I see, that looks like an opinionated choice indeed, but if it's written out i think it's ok.
Thank you so much for the clarification 👍

Edit: even if I still think that it would be nice to add [BREAKING CHANGES] notation in the CHANGELOG.md to make it extra clear, to maybe avoid this kind of misunderstanding.

[felangel]

@nerder thanks for the feedback. I'll add [BREAKING CHANGES] in the changelog moving forward to make it extra clear 👍