release major version on incompatible changes

[phaumer]

Building against a specific older version of Theia (such as 3.17) can cause issues when just using a package.json to select Theia components from npm, because the components themselves define dependencies amongst each other using "^0.3.17" instead of "0.3.17". So even if we specify to use 3.17 the Theia components themselves will pick the newer version 3.18 and the build can break. Symptoms are errors showing incompatible version of Theia classes such as URI being used etc.

To avoid such breakages Theia packages should reference each other with exact versions.

A workaround would be to add a long list of "resolutions" to the top-level package.json, but that would mean double maintenance of list of extensions available.

[akosyakov]

I've remembered why we cannot do it. It would break all existing clients, because external extensions are published against ^0.3.x as well. If we pin versions in core and there is a client depending on external extensions, it will get 2 versions of core extension.

I don't think we are going to change external extensions, if we pin then we have to go over and publish all of them on each release. Right now they are published once and forward compatible with the patch version.

A workaround would be to add a long list of "resolutions" to the top-level package.json, but that would mean double maintenance of list of extensions available.

As I mentioned already, a proper way is to use the lock file: https://yarnpkg.com/blog/2016/11/24/lockfiles-for-all/

[phaumer]

Thanks. I will investigate more on our end as we do commit the lock file.

Would using version numbers differently help? You did have breaking changes that were just declared as new patch-level versions, e.g. changes in the EditorManager behavior when adding Preview between 0.3.16 and 0.3.17 that broke our code, as well as changes I read about to the Debug interfaces. Do you think using major version updates for those kind of changes could help?

[akosyakov]

@phaumer sorry to hear that, we are trying to avoid breaking APIs and behaviour

Do you think using major version updates for those kind of changes could help?

It would require us to update external extensions as well. I think we should do it but after we have the official release 1.0.0, before it we don't really have commitments and new APIs are subject to change, like the editor preview or debugging.

You can join the dev meeting to discuss the issue there. Maybe we can go somehow differently about it.

// cc @svenefftinge @marcdumais-work

[akosyakov]

@phaumer We've discussed it at the last dev meeting. Since Theia is already used in production by different products and we are approaching 1.0.0 release, we've decided that we should update the major version for breaking changes as you suggested.

For now, while we are still in the initial development (0.x.y), we would consider the minor version as major and the patch version as minor. It's aligned with semver.

Before we start doing it, we should align latest releases of our external extensions. Right now they are always published against latest version, for example:

npm view @theia/[email protected] dependencies
 
{ '@theia/callhierarchy': 'latest',
  '@theia/core': 'latest',
  '@theia/languages': 'latest',
  '@theia/monaco': 'latest',
  'go-language-server': '^0.1.0' }

It is bogus, since @theia/[email protected] cannot be used with @theia/[email protected], but with the current latest version, 0.3.18 at the moment.

We need to make sure that when we publish @theia/[email protected], its Theia dependencies has ^0.x.y version, not latest. Plus it would be nice to have it somehow automated to reduce overhead of publishing it on each release.

Obviously, we should not break much anymore. If we do, it should be controllable, go through deprecation and we should release new major on removal of deprecated APIs. There can be exceptions, when we know for sure that APIs not used anywhere.

@svenefftinge @marcdumais-work makes sense? Someone should take care of fixing and automating builds for external extensions.

[akosyakov]

@marcdumais-work is it related to #2980?

[msujew]

We're using pinned versions now, closing.