Skip to content

Commit

Permalink
documentation: include migration guide
Browse files Browse the repository at this point in the history
The commit introduces a `migration guide` to the framework to help
downstream extensions and applications migrate to newer versions of the
framework.

Signed-off-by: vince-fugnitto <[email protected]>
Co-authored-by: Paul Maréchal <[email protected]>
  • Loading branch information
vince-fugnitto and paul-marechal committed Aug 3, 2021
1 parent dece352 commit d09ffdc
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 0 deletions.
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@ Read below how to engage with Theia community:
- Useful Links:
- [Developing](doc/Developing.md)
- [Testing](doc/Testing.md)
- [Migration Guide](doc/Migration.md)
- [API Integration Testing](doc/api-testing.md)
- [Coding Guidelines](https://github.com/eclipse-theia/theia/wiki/Coding-Guidelines)
- [Code Organization](https://github.com/eclipse-theia/theia/wiki/Code-Organization)
Expand Down
54 changes: 54 additions & 0 deletions doc/Migration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Migration Guide

## Description

The following guide highlights potential migration steps necessary during `theia` upgrades discovered when adopting the framework.
Please see the latest version (`master`) for the most up-to-date information.

## Guide

### v1.16.0

[Release](https://github.com/eclipse-theia/theia/releases/tag/v1.16.0)

- N/A.

### v1.15.0

[Release](https://github.com/eclipse-theia/theia/releases/tag/v1.15.0)

#### Keytar:

- [`keytar`](https://github.com/atom/node-keytar) was added as a dependency for the secrets API. and may require `libsecret` in your particular distribution to be functional:
- Debian/Ubuntu: `sudo apt-get install libsecret-1-dev`
- Red Hat-based: `sudo yum install libsecret-devel`
- Arch Linux: `sudo pacman -S libsecret`
- It is possible that a `yarn resolution` is necessary for `keytar` to work on older distributions (the fix was added in `1.16.0` by downgrading the dependency version):

```json
"resolutions": {
"**/keytar": "7.6.0",
}
```

- `keytar` uses [`prebuild-install`](https://github.com/prebuild/prebuild-install) to download prebuilt binaries. If you are experiencing issues where some shared libraries are missing from the system it was originally built upon, you can tell `prebuild-install` to build the native extension locally by setting the environment variable before performing `yarn`:

```sh
# either:
export npm_config_build_from_source=true
yarn
# or:
npm_config_build_from_source=true yarn
```

#### Webpack

- The version of webpack was upgraded from 4 to 5 and may require additional shims to work properly given an application's particular setup.
- The `webpack` dependency may need to be updated if there are errors when performing a `production` build of the application due to a bogus `webpack-sources` dependency. The valid `webpack` version includes `^5.36.2 <5.47.0`. If necessary, you can use a `yarn resolution` to fix the issue:

```json
"resolutions": {
"**/webpack": "5.46.0",
}
```

0 comments on commit d09ffdc

Please sign in to comment.