Make it easier to maintain and consume Theia extensions

[colin-grant-work]

Creating and consuming Theia extensions involves quite a bit of friction at the moment.

• From the perspective of the consumer, if the extension doesn't release regularly with updated Theia dependencies, the consumer needs to use resolutions to ensure that only one set of @theia dependencies is present in the application, and has to hope that no API used by the extension have been broken since the last release. From the perspective of the extension author, you have to keep synched with the Theia release cycle to ensure that your consumers don't end up unable to use your extension.
• There isn't a convenient way to develop or test an extension in the context of a given Theia version (the equivalent of the VSCode extension host mode). Most extensions therefore maintain specifications for whole Theia applications inside their repos, which is an additional chore to maintain and increases the risk of staleness, since it insulates the authors (but not necesarrily consumers!) from changes in Theia core.

Some of this ties in with API management: we don't have any concept of more and less stable API for extenders to rely on, so there's a chance of breakage at any uplift, and consuming extensions on different releases cycles from Theia core is a potentially risky business.

Some additional details:
#9153

[Niklas-Dahlquist]

has to hope that no API used by the extension have been broken

This is a big issue when using resolutions and currently you must rebuild every extension you develop when a new version of Theia arrives to circumvent any possibility of API breakage. This overhead makes it hard to reuse and integrate Theia Extensions as npm packages, also as only one version of Theia Extensions is allowed, you fall back to resolutions as the only option if you publish extensions with the described pitfall. So even with a proper API management more is needed to make the consumers solution improved and easier.

[tortmayr]

From the perspective of an extension provider I think one huge improvement would be if Theia would properly support declaring extension dependencies as peerDependencies.
From the official yarn doc:

Peer dependencies are a special type of dependency that would only ever come up if you were publishing your own package.

Having a peer dependency means that your package needs a dependency that is the same exact dependency as the person installing your package. This is useful for packages like react that need to have a single copy of react-dom that is also used by the person installing it.

Extension providers could declare their dependencies to other theia extensions as peerDependencies and the extension consumer is responsible for providing a compatible version (typically in the package.json of the consuming Theia application). This would also ensure that only one specific version of a Theia extension is resolved which guarantees that DI with inversify doesn't break.

Currently this is not well supported because the application-manager does not consider peerDependencies when deriving the extension module loading order. This means modules of a third-party extension (with only `peerDependencies) are considered to be dependency free and will be loaded before the core extension modules. As a consequence it is then no longer possible to customize core Theia components in the the third party extension (rebind, unbind etc.).

[planger]

Thanks for bringing up this important topic!

Theia is awesome, provides tremendous flexibility and evolves fast! However, exactly for the reasons you mention, pain points arise if you want to share Theia extensions across teams and products, which may hamper the growth of the Theia extension ecosystem.

There are a few aspects involved that interrelate or contribute to the friction you mention:

• Semantic versioning approach

  While there is an excellent change log with a list of breaking changes, the Theia version alone doesn't really help in knowing whether a new version breaks compatibility with a set of Theia extensions.

  I acknowledge that Theia's dependency injection approach, which is excellent and imho crucial for Theia's flexibility though, essentially leads to nearly every class or interface being sort-of API, which in turn makes it much harder to avoid breaking API when evolving Theia.

• High release cadence without declared "main" releases that are less frequent

  Theia releases a new version every month, which is great! However, aside from the extensions in the Theia main repo, products or extensions keeping up with that cadence are rare.

  Of course, everyone is free to choose a certain version and only update at a slower pace. However, as there are no officially declared "main" releases, it is an arbitrary choice and each Theia extension and product makes this choice independently. This leads to an extension ecosystem (public or even within an organization) that isn't tested against a consistent version of Theia.

• No compatibility range of Theia extensions

  Because of the two items above, Theia extensions can't easily specify a range of compatible Theia versions but usually are pinned to a specific (sort-of arbitrary) Theia version.

• Accidentally pulling multiple versions of @theia/core into a product

  Because of the pinned Theia version of Theia extensions, it is easy to accidentally pull in multiple versions of @theia/core when depending on Theia extensions that aren't part of your product's monorepo.
  It almost never makes sense to pull in multiple different versions of @theia/core, as this will lead to a broken product at runtime. The build however passes without any errors or warnings.

This essentially leads to the common approach of using resolutions, which essentially throws away the compatibility declarations of Theia extensions, because those declarations aren't really useful for the reasons above.

The consequence is that consumers need to manually find a Theia version that works with the set of extensions they pull in. Of course, there might be combinations of Theia extensions where you won't find a common Theia version that works with all of them. There is nothing wrong with that per se (it can happen, that's life :-)), but the issue is that the only way to find out is manual trial and error.

I think it would be great, if we could come up with a mix of tools, processes, and best practices to avoid or mitigate the issues above and help organizations and products to establish a more structured approach. Some ideas that we could put up for discussions are

• CLI tooling to build and test a Theia extension against a range of Theia versions more conveniently
• Best practice for declaring verified compatible Theia versions for a Theia extension
• Discuss whether declaring the Theia dependency as peer dependencies could be a better practice for Theia extensions (as mentioned by @tortmayr above)
  • Avoiding the need for resolutions
  • Making use of declared compatibility ranges
• Have one or two releases of Theia a year that are qualified as main releases so that Theia extensions and products are guided in selecting a common compatible release
• Throwing a Theia build error if multiple versions of Theia extensions end up in a product, at least if they have modules
• CLI tooling that warns if two extensions in a product rebind the same key

What do you think?

[paul-marechal]

Accidentally pulling multiple versions of @theia/core into a product

There is a Theia CLI command to check hoisting issues: theia check:hoisted. This is an old problem, which might be solved with peerDependencies as it would ensure extensions share the same core package installed by the root of the application.

[planger]

Thanks for the feedback and the pointer to theia check:hoisted!
Right, peerDependencies have the potential to solve that issue in the first place and would also open other opportunities like better making use of compatibility declaration of extensions.

[paul-marechal]

Semantic versioning approach

No compatibility range of Theia extensions

This issue is related to the way we manage breaking changes... For the sake of fixing bugs or adding new features, we often need to at least break one or more internal APIs. The problem is that it is unclear what's internal vs what's public. Common contributions points are obviously public while more obscure implementation details might not be, but both are currently importable in the same way (by directly importing symbols from the files that define them).

Since it is so difficult to tell what's supposed to be public stable API vs not, it is difficult to follow semantic versioning...

See #10772 for one way of declaring API. It is not a complete solution, just one step towards only exposing stable APIs through each runtime's entrypoint.

[tortmayr]

Hi Philip,
great suggestions! I especially like the idea of dedicated main releases!

Discuss whether declaring the Theia dependency as peer dependencies could be a better practice for Theia extensions (as mentioned by @tortmayr above)
Avoiding the need for resolutions
Making use of declared compatibility ranges

I haven't looked into the implications of changing the dependencies of core extensions to peerDependencies yet. So I cannot make a recommendation for that. However, I think there is no good reason to prevent third-party extensions from declaring their dependencies to Theia core extensions as peer dependencies. AFAIK the only thing preventing that right now is the module loading issue mentioned above ( which presumable can be fixed rather easily).

[tsmaeder]

Hi folks, a couple of thoughts from my side: I think there is a technical side to this discussion (duplicate modules bad!) that can be solved with technical means and I'm all for it. However, there are more fundamental questions to be answered here, as well.

It might come as a surprise to some that we do have an API management policy (https://github.com/eclipse-theia/theia/blob/master/doc/api-management.md#stable) and even more surprisingly, we're following it to the letter. That is trivially true, because we have no stable API whatsoever. None, zero, zilch!

The first thing we would have to do in order to give the semantic versions any meaning would be to define a reasonable subset of our code as API. Interestingly, we're already doing this when deciding what to put in the "breaking changes" document. We're not putting every change to a public class in there, AFAIK. I can see two ways to go about defining API: push and pull. In "push", we would open an epic to go over parts of our code and identify the parts we (as the framework writers) feel clients should interact with (by extending, overriding, etc.). The "pull" approach would be for adopters to request something they rely on to be stable API. I kind of like the pull approach, because it would allow us to learn what is actually treated as API by clients. One thing to be aware of is that the API will always be smaller than some adopters would like: the framework creators might not want to promise stability in certain areas, even if clients use them.

Once we're accepting that we have stable API, I think semantic versioning is a good way to label releases. With our API stability rules as they are, we might just end up with "funny" release sequences: "14.0.0, 15.0.0, 15.1.0, 16.0.0", so not many point releases.

The second topic to be considered is API stability over time. We're not breaking API just because it's fun. API breakages are caused by improvements to the code (functional or quality), and if there is a non-breaking way to do the same, we will embrace it. So by keeping API stable for longer, we're postponing positive changes to the code base. I'm not in favor or that. What API stability brings you is that you can update to a newer version without needing to update your own code. The alternative is to depend on an older version. That is sometimes undesirable because you might want fixes and features from later versions. However, unless we commit to some kind of LTS releases (including doing fixes for older versions), you'll have to catch up to the API changes eventually (and do more changes). What I could envision is that we declare every nth release a "stable" release in that we invest more in testing and focus on fixing bugs before the "stable" release. Large scary changes would not go into that release. That would make it a good base for updating to.

With the resources available to the project, I can't see us maintaining LTS releases right now. Maybe that is something that adopter companies could pay for? The Theia project would declare a release "LTS" so when people contribute fixes for an old release, they all contribute to the same branch.

One thing we're missing right now is a succinct documentation of stable API. Some kind of theia-extensions.d.ts folks can refer to (and maybe even program against). We'd have to figure out how that works.

just my 2 kopiyky.

[paul-marechal]

It might come as a surprise to some that we do have an API management policy (https://github.com/eclipse-theia/theia/blob/master/doc/api-management.md#stable) and even more surprisingly, we're following it to the letter. That is trivially true, because we have no stable API whatsoever. None, zero, zilch!

;)

Interestingly, we're already doing this when deciding what to put in the "breaking changes" document.

It's often more of an "just in case" measure: the class is exported and bound using Inversify so someone might depend on it...

I can see two ways to go about defining API: push and pull. In "push", we would open an epic to go over parts of our code and identify the parts we (as the framework writers) feel clients should interact with (by extending, overriding, etc.). The "pull" approach would be for adopters to request something they rely on to be stable API. I kind of like the pull approach, because it would allow us to learn what is actually treated as API by clients. One thing to be aware of is that the API will always be smaller than some adopters would like: the framework creators might not want to promise stability in certain areas, even if clients use them.

Realistically we need to mix both "push" and "pull": We define a very minimal set of API as "public & stable-ish" and then wait for use-cases to present themselves in order to "pull" new public APIs from those. When I talk about an initial set of APIs I have things like Widgets and other common things in mind.

The second topic to be considered is API stability over time.

It will be easier to keep things stable once we have a small set of things we want to keep stable. Once we have that, we shall also make sure that those APIs as well as new ones are made in a way that makes it easy to adapt against potential internal refactorings: it's easier said than done, but it means we need to put careful thought not to leak implementation details.

One thing we're missing right now is a succinct documentation of stable API. Some kind of theia-extensions.d.ts folks can refer to (and maybe even program against). We'd have to figure out how that works.

We have multiple packages that all should have their own public API and that need to consider multiple runtimes.

I go over the way I think has the most chances of being done here: #10772