Episerver breaking changes policies
There has been a small confusion regarding our breaking changes policies, and some developers understand it as "Episerver promises to not introduce breaking changes in non-major releases".
That's not entirely correct. We promises to not introduce public APIs breaking changes in non-major release.
What do we consider as public APIs:
- The API is not in an internal assembly. Some assemblies, such as EPiServer.Commerce.Internal.Migration.dll, are "internal assemblies", therefore any types, methods or properties from such assemblies are not public APIs.
- The API is not in an Internal namespace.
- The API is not marked with a special summary, usually "This class is intended to be used internally by EPiServer..."
Those APIs are considered "internal", even if the type itself is public. We reserve the right to change such APIs when needed.
For public APIs, we follow the sematic version rules strictly. Any breaking changes will require a major version. In most of the cases, we obsolete the APIs first, and will leave them there for at least 12 months before actually removing them (in a major release). In extraordinary circumstances, we can remove non obsolete APIs in a major release, but if and only if it's non avoidable.
Sounds like a good strategy!
What about breaking changes in Episerver UI? If some feature is disabled or removed, is it considered as a breaking change? Technically such changes will break solutions that depend on disabled feature. We have exactly this case with Commerce package to product relation support, that was removed in a minor update. Now we need to reimplement our product structure, update code and migrate from old structure - unexpected tasks to receive after minor non-breaking update.
The policies seems logical enough in theory. However in practice we always have to treat every episerver commerce update as a breaking, since we have a lot of cases using internal classes that we found no other workaround for.
@Joel: When you use the internal classes, you know the risk :).
@Joel: In other hands, which internal APIs do you use - and why? We can make some of the internal APIs public if they can help avoiding some situation like that.
@Pavel: We are looking into the change you mentioned. What we've done is to make sure the behaviors are consistent across the framework. However if you can tell us about your catalog modeling, and what you are trying to do - we can probably help somehow.
@Quan:
A very common usage is ILineItemExtensions.TryGetDiscountValue. We also required the PromotionEngineContentLoader to implement several single use coupon codes for a discount. Those were just the top search results on ".Internal" in the solution, we use a lot more in other projects as well.
Interesting. Can you spend some time to sum up what you would like to be public - just like the one about Marketing UI performance (that one was a great feedback, btw)? While we can't make all of them public, we will surely take a look into that, and the better we understand the problems, the better the solution will be.
@Quan: we use packages for special product systems that consist of several products. This solution allows to use product systems together with other products as entries in the code (comparing to using nodes instead of packages) and Commerce UI looks logical - you see all systems together with other products under the same category and you can unfold the system to see its components. Now this structure is not working anymore after a minor update. I understand that disabling products support in packages can be driven by some framework refactoring, but this should be a breaking change in major version update, allowing existing customers to calculate the costs of the next major update, instead of breaking existing solutions unexpectedly after a minor update.
@Quan:
I will if time and priorities allows it... :) Where do you prefer such feedback, post on the forum or a blog post?
@Joel: Whatever you like best. As long as we can read, it's fine