Materialdesign: Upgrading from 1.9.32 to current 3.7.95

[chipsterva69]

We are planning on upgrading our current icon set (1.9.32 - self-hosted font files) to the current set, but can't find anything really definitive about backwards compatibility or upgrade challenges. What is the recommended path of action? Thanks in advance!

[Templarian]

https://dev.materialdesignicons.com/upgrade

Small issue we never documented renames back that far. They are in the database though if you view the history page below.

https://dev.materialdesignicons.com/history

[goyney]

We don't follow semver; the version number is simply the number of icons we have in the library. This means, for version 1.9.32, that was at the time we had 1,932 icons available.

However, there are some breaking changes for specific icons. We've recently starting releasing upgrade guides in cases where code points change. You can see that here: http://dev.materialdesignicons.com/upgrade

You can see the full history here: http://dev.materialdesignicons.com/history

Though we don't follow semver, we try to keep major breaking changes to the major version number as best as possible.

[chipsterva69]

Great - thanks for the info and prompt replies!

[vladimyr]

We don't follow semver; the version number is simply the number of icons we have in the library. This means, for version 1.9.32, that was at the time we had 1,932 icons available.

Though we don't follow semver, we try to keep major breaking changes to the major version number as best as possible.

There are at least 3 issues with this versioning system:

1. It is not obvious and it is not prominently advertised. Digging through issue log to find it out isn't expected way of communicating it.
2. Due to frequent renames it makes upgrading between versions painful which is clearly outlined here: https://github.com/Templarian/MaterialDesign-Webfont/issues/54#issuecomment-521329485
   And it is especially nasty if you are not aware of _not following semver_ part and blindly assume that minor release won't break things while in fact it may and most certainly will! (FWIW it makes mdi only package I need to explicitly pin in all of my projects.)
3. Your second statement is simply awkward. There aren't _major_ and _minor_ breaking changes there are breaking changes. If you rename an icon without keeping old name as an alias UI gets broken. If UI gets broken it is a breaking change! For example, here is what happened going from v3.8.95 to v3.9.97: https://diff.intrinsic.com/@mdi/font/3.8.95/3.9.97#file-scss___variables.scss
   book-multiple-minus → renamed without alias i.e. gone
   book-multiple-plus → renamed without alias i.e. gone
   ...
   All those changes are breaking changes and major version stayed the same despite your statement!

I understand it is your freedom to pick versioning system you like most even if it creates hassle for everyone else breaking expectations and requiring more work to handle it properly - but if you do so please make sure that everyone is aware of that. I may be wrong but couldn't find that info in the docs.

[Templarian]

@vladimyr We switched from this system after 4.0 after feedback. Breaking changes are marked with a label now and are going to be compiled into the 5.0 update.

If you're still on a pre 4.0 version there are a lot of breaking changes going to a 4.x version.

https://dev.materialdesignicons.com/upgrade
https://dev.materialdesignicons.com/changelog

[Templarian]

https://github.com/Templarian/MaterialDesign/issues?q=is%3Aopen+is%3Aissue+label%3A%22Breaking+Change%22 You can use the label filter to see the breaking changes for 5.0 (there are going to be a lot).

[vladimyr]

First, what a response time 🏆 👍

@vladimyr We switched from this system after 4.0 after feedback. Breaking changes are marked with a label now and are going to be compiled into the 5.0 update.

I get the labels part on github but you switched to what exactly? semver? 🤔 Does it mean that future 5.x.x releases, if any, won't contain any breaking icon renames and/or removals?

https://github.com/Templarian/MaterialDesign/issues?q=is%3Aopen+is%3Aissue+label%3A%22Breaking+Change%22 You can use the label filter to see the breaking changes for 5.0 (there are going to be a lot).

Without entering into issue closing policies I believe you should remove is:open part and add explicit milestone identifier: milestone:"Next Major - 5.0.xx" so it becomes:
https://github.com/Templarian/MaterialDesign/issues?q=is%3Aissue+label%3A%22Breaking+Change%22+milestone%3A%22Next+Major+-+5.0.xx%22
🤔

So to keep things clear and double check stuff, going forward:

1. Are there any compatibility promises baked into version number itself?
2. If not, recommended course of action is going through labeled issues for given release as demonstrated earlier?

[Templarian]

I get the labels part on github but you switched to what exactly? semver? 🤔 Does it mean that future 5.x.x releases, if any, won't contain any breaking icon renames and/or removals?

That's the plan.

Without entering into issue closing policies I believe you should remove is:open part and add explicit milestone identifier: milestone:"Next Major - 5.0.xx" so it becomes:
https://github.com/Templarian/MaterialDesign/issues?q=is%3Aissue+label%3A%22Breaking+Change%22+milestone%3A%22Next+Major+-+5.0.xx%22
🤔

Yep, it's mostly for the team to internally track things during 5.0 planning.

So to keep things clear and double check stuff, going forward:

1. Are there any compatibility promises baked into version number itself?
2. If not, recommended course of action is going through labeled issues for given release as demonstrated earlier?

1. Nope, but we've made it a priority after 4.0 to try and tracking breaking changes. Small things like typo in previous release may be fixed.
2. Follow the upgrade / changelog guides linked above.

4.0 was a large release to address these issues. We expect 5.0 should be a lot smoother now that our core team is larger to manage the influx of issues.

[vladimyr]

Thanks for clarification and good luck with future releases 👍