New releases need summary of breaking changes

[pjohnson31]

Hey @Templarian! Big fans of your MDI icon library here. However we have some issues with the versioning of this module. Mainly, there is no way for us to verify consistency from one version to another. Recently we upgraded MDI versions, and a customer noticed that one of our icons had disappeared, rendering the button useless. We realized afterwards that the icon name had changed in a version update.

Our request is mainly that if there are breaking changes to existing icon names, there's a place for us to see those changes and correct them before we push changes (without having to go through line by line on your commits).

Also, if you can have some sort of rules about when you release breaking changes (e.g. major version changes) it would be easier for us to manage. In another example your update from v1.7.22 to v1.8.36 completely deleted an icon called "mdi-appnet".

If this already exists somewhere, please let me know! Thanks

[tagliala]

Hi,

I do agree in following SemVer for this repo

In this specific case, it is worth to notice that App.net shut down their services, so maybe you need to remove a feature from your application

On January 12, 2017, the founders announced that the platform App.net would be shut down on March 15, 2017.[13] However, due to a significant number of user data export failures that deadline was extended until March 16, 2017. App.net finally ceased to operate as a social network at 2017-03-17-06:45UTC. The source code for App.net will be made available on their Github Page.[needs update]

(from Wikipedia)

(I'm having this App.net issue for the upcoming Font Awesome 5, it's not sure we will keep the icon since the service is no longer active)

[PeterShaggyNoble]

It sounds like you're looking for the history page, which details all changes made including additions, edits and renamings.

[pjohnson31]

Thanks @PeterShaggyNoble that is really helpful. However It doesn't seem to mention removals or deletion (like the appnet example). Another example, is that the 'unfold-less' and 'unfold-more' icons changed to be unfold-more-horizontal, -veritical, etc. Yet the history has no reference to the modification, it just says created new icons So we likely wouldn't have been able to spot a breaking change from the history page.

[PeterShaggyNoble]

Those 2 were actually renamed unfold-*-horizontal and I believe, at that time, there was a bug preventing renamed files from being properly tracked, which has since been fixed.

Icons are very rarely deleted, they are usually repurposed, allowing their IDs and codepoints to be recycled. In the case of appnet, it was repurposed as font-awesome (if you hit "Compare" by the only entry for font-awesome on that list, you can see that). However, we have been discussing a better way to label and highlight repurposed icons on the history page for the new site as it can cause some confusion.

By the way, just in case you are still using it, the vine icon will be replaced with a venmo icon in the next release.

[PeterShaggyNoble]

Incidentally, if you do still have need of the old appnet icon, it's available in the MaterialDesign SVG repo.

[itsnydell]

For renamed icons in future, could you keep the name intact and point to the new name to prevent issues for people who use the icon? Should be able to use the same codepoint twice for different name variations as long as the icon is the same.

[Templarian]

Renames are very rare after the v2.x release. In the next release there are 1 renamed icons as far as I recall (and the vine became the venmo logo as said above). The system really isn't built for me removing icons at the moment, its one reason why we replace codepoints instead of deleting.

I like SemVer, but realistically I probably will not be moving in that direction any time soon.

I know I say this a lot, but we'll be addressing a lot of these issues in the new site. Trying to making a lot of these things more apparent. The History page currently has a bug with renames. Need to fix these manually in the DB at the moment (recoded all the endpoints for the new site).

I'm thinking about adding Change Log (aka History) to the top navigation to the right of the Icons to make it really easy for people to track changes. The icon pages will each show individual icon history also.

http://dev.materialdesignicons.com/ "Change Log" to the right of "Icons"

[Templarian]

Forgot to update this with more details. The http://dev.materialdesignicons.com/history page now contains issue ids associated with every change we're making (we also went back in the list and added issue ids).

This will allow use to create a more detailed change log with each release. We're still working on the new site and documentation, but am going to try and work on a way to generate a nicely formatted .md with the changes.

[Templarian]

By the way if you are working with React you can use @mdi/react, this will ensure any updates will cause a compilation error. Still trying to think of a nice way to handle this for the webfont.

We're up to 146kb for the Woff2... so would highly recommend to move to the @mdi/js library if possible.

[Templarian]

http://templarian.com/2018/09/02/material-design-icons-2-7-94/ Breaking changes for 2.7.94.

[jacobq]

See also https://github.com/Templarian/MaterialDesign/issues/2274

[Templarian]

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

I'm currently going back and adding changelogs for the last releases since 2.x and we will be using this document and the upgrade guide. Thinking of a nice format to handle the upgrade guide. It will mostly focus on just the renames, so hopefully people can quickly do global renames.

[jacobq]

@Templarian LGTM -- thanks for creating those. For me, API/usage/name changes are, indeed, the main thing I want to know when upgrading.

Is creating and maintaining those docs going to be a maintenance burden though? Lately I have noticed so many projects using conventional commits and automated changelog generation tools like standard-version so am wondering if there might be something like that that would be well suited to mdi.

[Templarian]

Yea, we actually can automate the page from the database. Eventually we'll do just that. Out of our 10 core contributors or anyone wanting to submit a PR to upgrade.md or changelog.md file it should be easy to keep up to date. We only really do a release once a month.

We've standardized a lot of the naming now also, so hopefully there will be very few breaking changes going forward.

Want to work with the team on generating a nightly build to the CDN. That will allow for a larger testing audience. Right now our release structure is very manual to verify all the new glyphs exported correctly.

We'll be updating the upgrade docs and linking to it from the legacy page this week. Will close this issue after that is complete.

[Templarian]

Okay, got the format for both documents down and updated for 3.2.89. Will close this once I link to on the legacy site.

• Changelog: https://dev.materialdesignicons.com/changelog#version-3.2.89
• Upgrade Guide: https://dev.materialdesignicons.com/upgrade#3.0.39-to-3.2.89

[Templarian]

Forgot to close this. We've found the two documents are doing a good job of informing larger projects of our breaking changes (haven't seen any issues in a long time around our release process).