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
Optimizely community meetup - Sept 29 (virtual + Melbourne)

Super excited to be presenting this Thursday the 29th of September at the Optimizely community meetup. For the full details and RSVP's see the...

Ynze | Sep 27, 2022 | Syndicated blog

Preview multiple Visitor Groups directly while browsing your Optimizely site

Visitor groups are great - it's an easy way to add personalization towards market segments to your site. But it does come with it's own set of...

Allan Thraen | Sep 26, 2022 | Syndicated blog

The Report Center is finally back in Optimizely CMS 12

With Episerver.CMS.UI 12.12.0 the Report Center is finally re-introduced in the core product.

Tomas Hensrud Gulla | Sep 26, 2022 | Syndicated blog

Dynamic Route in ASP.NET Core When MapDynamicControllerRoute Does Not Work

Background Creating one of the add-on for Optimizely I had to deal with challenge to register dynamically route for the API controller. Dynamic rou...

valdis | Sep 25, 2022 | Syndicated blog