Loading
Network error

Agorakit : Users & developers

Agorakit : Users & developers

Semantic versioning

Started by linc in Agorakit : Users & developers March 23, 2025 3:24 PM

Are we using semantic versioning? If not, could we change to that?

If we followed that, requiring a higher version of PHP would have made 1.9.3 the 2.0 release instead. I think it's a best practice to follow this unless there are strong reasons not to.

First, imagine having 1.9.2 installed on PHP 8.0 and assuming this was a patch release. You'd completely break your site.

Second, imagine we had a security patch and needed to release it immediately. We now have no path to getting a quick fix to a PHP 8.0 user. Because going from 1.9.2 to 1.9.3 involves a major PHP upgrade, there's no version number space left for a security patch or other backwards compatibility.

Third, it makes it clearer what the next release version should be. "Saving up" for a "big" major point release stops being a thing to worry about.

Odile B
March 23, 2025 3:45 PM

I think so. At least, I think we intend to.


Agorakit (Philippe)
March 24, 2025 10:24 AM

Great idea! I was supposed to be wanting doing this, then I stopped, approaching the supposedly incredible 2.0 release :-)

Let's stop this and follow best practices.

Do you have any recommandation as to how to proceed? I know what semantic versioning is in theory, but how to apply it to the project now and put everything back on track?

linc
March 29, 2025 4:32 PM

I suggest we leave the current releases as-is.

It's tempting to mess with releases retroactively, but I think it can create more confusion than it's worth.

Let's simply be clear about patch-level changes, minor changes, and backwards-incompatible changes going forward, and use the changelog to determine the next appropriate version number.

Agorakit (Philippe)
March 30, 2025 11:19 AM

Is it a good idea to release a 2.0 quite soon because of recent PHP requirements changes ?

Or we continue 1.x where x can be > 9 ?

linc
March 30, 2025 8:44 PM

I'd simply evaluate each new release based on the new criteria. It's fine to release 1.10 if the next release is a minor-point.

  • If it's a patch, it's 1.9.4.
  • If it's changed functionality but not backward-compatibility ("BC") breaking, it's 1.10.
  • If it's breaking BC, it's 2.0.

I'd define "breaking BC" in our context as:

  • Requiring a higher PHP or MySQL (or other OS-level library) version.
  • Moving a full version of Laravel.
  • Changing an API (or feed or integration) in a way that could cause existing calls to break.
  • Anything requiring a non-standard upgrade process.
  • Making a large enough app-level change that an extension or customization may reasonably break (this may be a judgment call).
linc
March 31, 2025 1:57 AM

A good example of an issue that would cause us to move to 2.0: https://github.com/agorakit/agorakit/issues/524 

Changing the namespace would definitely be a BC break.

plusone
linc
19:31

Since we have a few backwards-compatibility breaks identified now, I grouped them under a '2.0' milestone to see if we can roll them out together and avoid repeated breaks.

plusone
Agorakit (Philippe)
20:29

Good idea!


i'll fix more little stuff and hopefully will dedicate a day or two on the bigger stuff in the following week.

You've read everything in this discussion