Try our conversational search powered by Generative AI!

Quan Mai
Jun 22, 2017
(6 votes)

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.

Jun 22, 2017


Jun 22, 2017 02:00 PM

Sounds like a good strategy!

Pavel Nezhencev
Pavel Nezhencev Jun 23, 2017 12:57 PM

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.

Joel Yourstone
Joel Yourstone Jun 26, 2017 10:08 AM

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.

Quan Mai
Quan Mai Jun 26, 2017 10:17 AM

@Joel: When you use the internal classes, you know the risk :).

Quan Mai
Quan Mai Jun 26, 2017 11:52 AM

@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.

Joel Yourstone
Joel Yourstone Jun 26, 2017 02:40 PM


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. 

Quan Mai
Quan Mai Jun 26, 2017 02:53 PM

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.

Pavel Nezhencev
Pavel Nezhencev Jun 27, 2017 01:05 PM

@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.

Joel Yourstone
Joel Yourstone Jun 27, 2017 04:38 PM


I will if time and priorities allows it... :) Where do you prefer such feedback, post on the forum or a blog post?

Quan Mai
Quan Mai Jul 5, 2017 09:01 PM

@Joel: Whatever you like best. As long as we can read, it's fine

Please login to comment.
Latest blogs
Build a headless blog with Astro and Optimizely SaaS CMS

I’m a big fan of using the right tool for the right job. I’m also a big fan of Astro , for the right use case. Let's explore Astro to see what it's...

Jacob Pretorius | May 28, 2024

Microsoft announces Natural language to SQL

Finally, Microsoft launches "Natural language to SQL," after it has been available for several months in Optimizely CMS!

Tomas Hensrud Gulla | May 23, 2024 | Syndicated blog

Five easy ways to start personalizing your content right now

If you clicked on this article, you already know that getting the right message to the right person at the right time helps drive conversions and...

Kara Andersen | May 23, 2024

ExtendedCms.TinyMceEnhancements – serwer side webp support

Today I will introduce another small feature of TinyMceEnhancements plugin. The functionality is used to automatically detect whether a browser...

Grzegorz Wiecheć | May 22, 2024 | Syndicated blog

Azure AI Language– Detect Healthcare Content in Optimizely CMS

In this blog post, I showcase how the Azure AI Language service's Text Analytics for health feature can be used to detect healthcare content within...

Anil Patel | May 22, 2024 | Syndicated blog

Stott Security Version 2 So Far

In December 2023, I unveiled the initial version of Stott Security version 2. Although I typically announce each version I release on LinkedIn and...

Mark Stott | May 22, 2024