Virtual Happy Hour this month, Jun 28, we'll be getting a sneak preview at our soon to launch SaaS CMS!

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
Remove a segment from the URL in CMS 12

Problem : I have created thousands of pages dynamically using schedule jobs with different templates (e.g. one column, two columns, etc..) and stor...

Sanjay Kumar | Jun 21, 2024

Copying property values part 2

After publishing my last article about copying property values to other language versions, I received constructive feedback on how could I change t...

Grzegorz Wiecheć | Jun 18, 2024 | Syndicated blog

Enhancing online shopping through Optimizely's personalized product recommendations

In this blog, I have summarized my experience of using and learning product recommendation feature of Optimizely Personalization Artificial...

Hetaxi | Jun 18, 2024

New Series: Building a .NET Core headless site on Optimizely Graph and SaaS CMS

Welcome to this new multi-post series where you can follow along as I indulge in yet another crazy experiment: Can we make our beloved Alloy site r...

Allan Thraen | Jun 14, 2024 | Syndicated blog