Incorrect semver releases

While routinely upgrading my libraries I noticed the release of laminas-config-aggregator 1.5.0. Coming from 1.4.0, I was curious to see what new features there might be. But I was surprised to find not a single feature affecting users in the changelog.

Checking the entire diff from 1.4.0 to 1.5.0, there is actually not a single change (feature or bugfix) that would affect users of the library.

From that I conclude two things. First of all, if there is no changes at all for users, then there is no need to release at all. It only produce noise for people who upgrade their libs and review what might be new.

Secondly, if for some reason it was decided that it had to be released anyway, then the version number breaks semver. Because it does not contains any features. Instead it should have been a patch release, as 1.4.1.

I believe the incorrect version numbering is due to the workflow used to manage changelog, where a version number is decided, before any work happened.

I would suggest to change the workflow to keep the version as TBD until we actually release it (as is done for the date).

tl;dr: pretty please, use Allow creating and promoting "Unreleased" versions by weierophinney · Pull Request #75 · phly/keep-a-changelog · GitHub to reduce noise ?

What do you think ?

PS: same goes for Release 1.11.0 · mezzio/mezzio-session-ext · GitHub

1 Like

Thanks for your feedback! I think you should start this discussion on the Chat to get more reactions and answers. (Use the “contributors” channel for that.)


Improvements go to new minors: patch releases are reserved to bug fixes exclusively.

I agree with that, but the releases mentioned here contain no features for the library users, and not even bug fixes for the library users.

Should feature and fixes for the library developers follow semver ?

I don’t think so, because it has zero impact for consumers.

I even think they should not be released at all (by themselves), because it’s more work for developers, more work for users (to update) with zero improvements of any kind to anybody.

I didn’t check this particular case, but it is likely that all modified files are excluded from composer package. If that’s confirmed, then the two versions of the package are strictly identical (except changelog). Why bother then ?


Why bother then ?

We have a release automation in place now ( ) - if we skip releasing stuff when we’re “done with the day”, it means that the next maintainer touching the library will have to backtrack.

Overall, a release with minimal to zero advantages is still favorable to having stale changes sitting there in a development branch.

It can be annoying, but it is also true that this is the exception rather than the rule, compared to, for example, how symfony used to release package versions until very recently.

1 Like

From GitHub - laminas/automatic-releases: Automated release process for `laminas/` projects, usable as github action, I feel the step:

  1. create (if necessary) a “next minor” release branch x.y+1.z

tends to favorize the release of minor version, even if the milestone contains only bugfixes (or, like our case, features for maintainers).

Maybe informing the maintainers to do quick a review of the milestone content before closing it could allow them to rename a minor milestone into a patch milestone, and thus avoiding confusion for library users ?

Or if we would like to go further and force maintainers to make a decision at release time, we could create the milestone, as x.y-next. So the maintainer would be “forced” to either rename into x.y+1.z or x.y.z+1, before closing the milestone ?

Let me go into the concrete examples. Yes, the two releases of laminas-config-aggregator (1.5.0) and mezzio-session-ext (1.11.0) should be bugfix releases and should follow the patch version of semantic versioning.

To put this right: the changelog file is being removed everywhere and was also not relevant for a next version.
In both examples, the milestone was added to the pull requests and the essential work was done before.
And sometimes the four-eyes principle doesn’t work either, see mezzio-session-ext.

We are only human and sometimes in a hurry or under pressure to create new releases. And as we know, that leads to mistakes.
In my opinion, we have two of these mistakes here.

Is there something to improve? Sure, but I don’t see the problem in the process with automatic releases or in the rules for new versions, because these are based on semantic versioning.

1 Like

Glad we agree on this.

Couldn’t agree more with you on that. And that’s a perfectly valid, acceptable and sufficient explanation.

I guess I was mostly worried if that was the beginning of a new trend (specifically crafted to work that way, and possibly somehow related to the new automatic process), or if it was more of something that went overlooked once or twice.

As long as it mostly works as intended, with patch release still being a possibility, I’m totally fine with a few mishaps from time to time :smiley:

Thanks to both of you for your time here, but also for all the effort you put in OSS in general :pray:

But I still see a problem here because how do you define the change “Move dflydev/fig-cookies package to require-dev” in mezzio-session-ext? New functionality or bugfix?

The semantic versioning says:

What should I do if I update my own dependencies without changing the public API?

Determining whether the change is a patch level or minor level modification depends on whether you updated your dependencies in order to fix a bug or introduce new functionality. I would usually expect additional code for the latter instance, in which case it’s obviously a minor level increment.

Therefore, I also follow @ocramius argument: if it is not a bugfix, then it cannot be a patch version.
(I seem to remember that I created the minor release for that reason.)

Excellent point. And I don’t have an absolute answer, but to me, if it has to be released, then it would be a patch release. Because from the user point of view absolutely nothing changed, except there is one less package in vendor/. There is absolutely no new features, not even from the developer point of view.

So “not a feature” means “bugfix” means “patch release”. Interestingly enough it’s the opposite reasoning that you mentioned :stuck_out_tongue:

You might argue that if the user used dflydev/fig-cookies in his own code, then it might break his code. But I would answer that if he uses that package, then he should have declared his dependencies in his composer.json, instead of relying on transitive dependencies.

I see two options for this problem:

  1. One solution for these types of changes is to release them along with other bug fixes and/or improvements where the type of the release is clear.
  2. Another option is to improve communication. This means for mezzio-session-ext (dflydev/fig-cookies) that the information of extending PHP 8 support will be added in the release notes.

(The topic was also discussed in the Technical Steering Committee channel on Slack.)

I’m super late to reply…

…but of your two options I’d definitely pick option 1. If what we are releasing doesn’t bring value to consumers, then just don’t bother at all.

And yes, it would leave stale changes that might need to be reviewed again when releasing later on. But I’d assume it would either be quick to review, or it wouldn’t actually matter if those stale changes are not reviewed at all, since they were deemed not important enough to be released (by themselves) in the first place.