From e88c5e13c4aa376644c749d5566a990780ec784c Mon Sep 17 00:00:00 2001 From: vince-fugnitto Date: Mon, 2 Aug 2021 09:21:59 -0400 Subject: [PATCH 1/2] documentation: include `migration` guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Co-authored-by: Paul Maréchal --- README.md | 1 + doc/Migration.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 doc/Migration.md diff --git a/README.md b/README.md index b4c676558bdbc..172aec83d5a9c 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/doc/Migration.md b/doc/Migration.md new file mode 100644 index 0000000000000..36d7287716b2b --- /dev/null +++ b/doc/Migration.md @@ -0,0 +1,55 @@ +# 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` + - Alpine: `apk add libsecret-dev` +- 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", + } + ``` + From 0f23304769c0a3818a5fa600f1c55fbc09d3637d Mon Sep 17 00:00:00 2001 From: vince-fugnitto Date: Tue, 3 Aug 2021 13:39:15 -0400 Subject: [PATCH 2/2] documentation: update `keytar` prerequisites The commit updates the prerequisites documentation to include an update for `keytar` on `alpine linux`. Signed-off-by: vince-fugnitto --- doc/Developing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Developing.md b/doc/Developing.md index 5888b862244a6..935b9fc3eb3b1 100644 --- a/doc/Developing.md +++ b/doc/Developing.md @@ -74,6 +74,7 @@ Some additional tools and libraries are needed depending on your platform: - Debian/Ubuntu: `sudo apt-get install libsecret-1-dev` - Red Hat-based: `sudo yum install libsecret-devel` - Arch Linux: `sudo pacman -S libsecret` + - Alpine: `apk add libsecret-dev` - Linux/MacOS - [nvm](https://github.com/nvm-sh/nvm) is recommended to easily switch between Node.js versions.