How the versioning works in SharePoint Framework solutions

This post is a sum up of the conversation held in Twitter regarding versioning of your SharePoint Framework solutions.
In package-solution.json file of the SPFx project there is a property version
The description from the currently tells us that:
Optionally, you may also specify a version number in the format "X.X.X.X", which is used to identify various versions of the package when upgrading.

But it doesn't explain what is actually affected by the version update.
So, here is how it actually works:
  • First of all, all the assets (JavaScript files, CSS, images, etc.) are automatically updated as soon as new version has been added to the App Catalog. You don't need to update the app on all of your sites.
  • If you're using Feature Framework and Feature declarations in your solution then these are the resources that need the actual App update.
This situation may lead to confusion but it is what it is.
And actually it makes sense for two reasons:
  1. As an app should be installed to every site (meaning every root site and if needed - every sub site) separately, it's really difficult to go through all the sites and update the app. So, automatic update is a good decision.
  2. Why this "automatic" update isn't applicable to Feature Framework? Because new version of features content (like fields, content types, etc.) could contain breaking changes and it's better to be aware of it. And anyway SharePoint Dev team does not recommend to use Feature Framework in your solutions at all. =)
Here is also a PnP Shorts video that describes how to update the SPFx solution.
Hopefully, this information will be helpful.

Have fun!