Semantic Versioning

[ejmr]

I am a big fan and supporter of Semantic Versioning. I have been thinking it could be useful on various @emacs-php projects, to help give both users and devs important information at a glance about neeeew, big releases, when updates are minor and unlikely to affect their installation and ettings, and so on. I felt like phpactor.el could be a good "test-bed" for using Semantic Versioning and evaluating whether or not it would be valuable to use in future proeects.

Thoughts?

[kermorgant]

I'm open to it, just unsure what that would change.

Please correct if I'm wrong but I guess every PR getting merged is made available directly though melpa, and using semantic versioning means we should also update versions when that happens.

So if I'm correct, maybe we should merge PRs into another branch (develop like phpactor ?) and make semantic versioned releases decoupled from those PRs ?

[ejmr]

I do not think MELPA version numbers and semvers are mutually exclusive; I feel like they serve difference puposes. The former is very useful for package management but doesn't tell me much of anything as a user, e.g. "Is 20180917 backwards compatible with 20180830?" Whereas if I see two semantic version numbers, e.g. 2.0.3 and 1.7.0, I immediately know the important differences between them, i.e. the former is not backwards-compatibility with the latter but would be a non-breaking upgrade from, say, 2.0.1.

Again none of this may be helpful to users in general. I just personally over the years have grown in favor of version numbers that actually convey information to the user instead of being little more than a build date (which again has its place in certain tools).

[ejmr]

...and using semantic versioning means we should also update versions when that happens.

Sorry, I forgot to add, for projects that use semvers, updating them is something you do when you do something like update the changelog for a new release, not every time you merge a PR.

[zonuexe]

By the way, many Emacs-PHP packages (except php-mode) still have a major version of 0.

https://semver.org/#spec-item-4 Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

These can still be considered compatible with semver. Especially Phpactor and phpactor.el is still in development stage.

[zonuexe]

As you say, we should provide a clear Changelog for users. refs https://github.com/emacs-php/php-mode/issues/457

I'm sorry I have not prepared a release for the last change.

[ejmr]

By the way, many Emacs-PHP packages (except php-mode) still have a major version of 0.

Good point, and that's true. I must admit that is a pet peeve of mine, however. I swear ninety percent of the "crates" (i.e. packages) I use for the Rust programming language are still in major version zero because no one wants to declare their work is ready for public comsumption while shirking the responsibilities of possibly having to break compatibility in the future, lol.

[ejmr]

Regarding changelogs, I find this guide to be very helpful and it is what I often follow myself. I am adamantly against any changelogs that people amke by simply running:

$ git shortlog -ns > CHANGELOG.txt