One of the primary considerations when building a software platform on which other developers base their work is maintaining backward compatibility. As the platform grows more complex, this can become the major restraining factor when sustaining a high development pace.

Using strict semantic versioning, it becomes obvious that no API changes can be made, no matter how small or obscure the class is, unless a major version is released. And while releasing a major version might not be as big a deal as it used to be, it does add additional work, not just internally, but also for maintainers of third-party modules trying to keep their modules up-to-date.

internal, <internal> or .Internal?

The typical approach to this problem is to keep your public classes to a minimum and only expose classes that are useful to interact with for external developers. The API is currently limited primarily by keeping classes or methods internal.

One way of doing that is by adding the internal keyword to a class, but this is not usually the preferred way by users. Another option is to use the API documentation and explicitly call out the classes and methods that are considered internal. However, this has the drawback that it can sometimes be hard to track which APIs are public or not if they are spread out.

A third way, sometimes called "pubternal" or "internal namespaces," consists of using a specific namespace pattern to indicate that you are now dealing with classes not part of the public API. Previously, Optimizely used the first two options and has used the internal namespaces option since 2016.

This means that any class in a namespace named Internal is not considered a part of the supported public API. Such classes can still be used, but the semantic versioning promise does not cover them and can change between minor releases without prior warning. Usual support does not cover any problems that arise from using such classes.

It does, however, mean that Optimizely can expose more classes to the public in Optimizely assemblies, making them easier to use if you need to or for any non-production scenarios such as for unit testing.

📘
Note
This does not imply that everything outside these namespaces is a part of the public API as there are still classes and methods that are explicitly documented as being for “internal use” but these are kept to a minimal whenever possible.

Upgrade to CMS 10 and higher

In the first major release after Optimizely started using internal namespaces, Optimizely Content Management System (CMS 10), many classes were moved from their previous location to Internal namespaces. This included any classes not considered important for typical use cases or implementations of public abstractions. So, when you upgrade a pre-version CMS 10 solution, ensure that you do not accidentally add any internal namespaces to your statements, as this may cause problems in the future.