Feature request: Switch to semver

Describe the problem you’d like to see solved or task you’d like to see made easier

Pretty much everything on NPM uses Semver at this point, meaning version numbers work like this:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backward-compatible manner, and
3. PATCH version when you make backward-compatible bug fixes.

But this library only ever updates the MINOR number, even when making breaking changes.

To make matters worse, you’ve gone for the nuclear option of raising errors for recommending changes. Recently, while preparing for a demo for EXCO, one of the developers needed to update a few packages and did Fontawesome at the same time - it’s just a point release, right? Suddenly we had thousands of errors at startup, making it difficult to find actual problems.

Obviously the programmer is to blame as well, but using the versioning format everyone expects would go far to help avoid problems like this.

Is this in relation to an existing part of angular-fontawesome or something new?

Versioning format

What is 1 thing that we can do when building this feature that will guarantee that it is awesome?

Make it follow semver.

Why would other angular-fontawesome users care about this?

It protects them from unexpected breaking changes.

On a scale of 1 (sometime in the future) to 10 (absolutely right now), how soon would you recommend we make this feature?

8 - It can probably take a backseat to critical bug fixes, but there’s no reason to delay this.

Feature request checklist

• This is a single feature (i.e. not a re-write of all of Font Awesome)
• The title starts with "Feature request: " and is followed by a clear feature name (Ex: Feature request: moar cowbell)
• I have searched for existing issues and to the best of my knowledge this is not a duplicate

[devoto13]

I hear you, folks.

But what kind of protection do you expect? 0.x.y explicitly tells you: I’m unstable, breaking changes are possible in every version, check release notes and migration docs when you upgrade. Does it really makes difference if we would release 1.0.0, 2.0.0 and 3.0.0 (all releases are breaking) instead of 0.4.0, 0.5.0 and 0.6.0? It would still be same content with same breaking changes in every release.

Maybe the problem is exactly that the library is not on a major release, nearly two years on.

And it is not on a major release for a reason. There are fundamental problems with the current architecture, which make it impossible to solve several important issues without breaking changes and I don’t think it is acceptable to claim library stable before these are tackled (or at least we have a way to tackle them post 1.0.0 release): https://github.com/FortAwesome/angular-fontawesome/issues/18, https://github.com/FortAwesome/angular-fontawesome/issues/41, https://github.com/FortAwesome/angular-fontawesome/issues/48 to name a few.

Most of the breaking changes are going in the direction where fontawesome-svg-core would become an implementation detail, so angular-fontawesome would control its API surface completely and it will be possible to do internal architecture changes without breaking the users. Without this I don’t think the library is ready for 1.0.0.

As for the slow development speed, I’m maintaining this library on my spare time. You’re always welcome to contribute code if you want to speed things up.

I’ve used 0.4.0 for a while and it seemed excellent and production-ready as far as I could tell - it could easily have been a 1.0.0 release instead.

I guess the fact that a specific release works great for you means that angular-fontawesome contributors did a good job 😉. But it tells nothing about its API stability, in fact every release since then had breaking changes.

We realise that people can’t wait until library is 1.0.0 and want to use it already now in their production apps. And we appreciate it. In fact we try to provide detailed changelogs and migration guides to ease the upgrade pain. We also try to have a deprecation warning for one version, before making a painful change.

Then at least semver would shield me from unexpected breaking changes, but while it stays in the 0.x.x range I get no protection at all. Of course I’d love to update, but this is not the time as far as my own deadlines go.

According to SemVer with MAJOR=0, you should expect breaking changes in every release. And if you don’t have time to deal with them now then upgrade later.

You asked about the errors: I’m talking about the deprecation warning, as described in #201.

I would be fine with a deprecation warning when the library initializes, but it shows up as errors, and thousands upon thousands of them. I’m guessing the warning is shown on each library access? My devtools console fills up with errors that all say the same thing, making it difficult to spot actual errors. Having this situation arise with no prior warning is not great.

This is described in the migration notes. Global library was deprecated in 0.5.0 and became hard error only in 0.6.0. It even mentions the configuration property, which allows to revert to the previous behaviours (show warning or allow) - FaConfig.globalLibrary.

There is no way to check whether you actually use global library on initialisation and there is no reason to show a warning to users, who don’t use a global library. Also the purpose of hard error is to make sure that these are actually fixed, so it does not quite make sense to only throw on first usage. What should happen with further usages? Should they just silently don’t work?

The PR making a warning appear only once would be accepted, although not sure how useful it is given that 0.6.0 already at hard error stage.

---

The bottom line is that I think API is not yet stable and library should stay on MAJOR=0 until API is stable. This is also according to SemVer. Once all necessary changes have landed we’ll cut a stable 1.0.0 release. If everything goes well we’ll have 0.7.0 and then 1.0.0 after some alphas.

[CobusKruger]

@devoto13 Just one final comment om this:

As for the slow development speed, I’m maintaining this library on my spare time. You’re always welcome to contribute code if you want to speed things up.

I wasn’t actually commenting on development speed at all, just that (based on my view of 0.4.0) it seemed ready for 1.0.0 many months ago.

I’m highly appreciative of the work you’ve done and note your views on the topic.