From 5101bfc141c7bd24d8ad65c7f54bdcb5e8479f55 Mon Sep 17 00:00:00 2001 From: mai93 <70515749+mai93@users.noreply.github.com> Date: Thu, 13 May 2021 00:03:33 +0200 Subject: [PATCH 1/4] Update README.md --- README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 89 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 55d314cfc78..8852c64859f 100644 --- a/README.md +++ b/README.md @@ -26,44 +26,125 @@ and follow the instructions in the project import wizard. Detailed docs are available [here](http://ij.bazel.build). + ## Building the plugin Install Bazel, then build the target `*:*_bazel_zip` for your desired product: -* `bazel build //ijwb:ijwb_bazel_zip --define=ij_product=intellij-ue-latest` -* `bazel build //clwb:clwb_bazel_zip --define=ij_product=clion-latest` -* `bazel build //aswb:aswb_bazel_zip --define=ij_product=android-studio-latest` +* `bazel build //ijwb:ijwb_bazel_zip --define=ij_product=intellij-ue-oss-stable` +* `bazel build //clwb:clwb_bazel_zip --define=ij_product=clion-oss-stable` +* `bazel build //aswb:aswb_bazel_zip --define=ij_product=android-studio-oss-stable` from the project root. This will create a plugin zip file at `bazel-bin//_bazel.zip`, which can be installed directly from the IDE. `` can be one of `ijwb, clwb, aswb`. If the IDE refuses to load the plugin because of version issues, specify the -correct `ij_product`. These are in the form `-` with +correct `ij_product`. These are in the form `-oss-` with * `` being one of `intellij-ue, intellij, clion, android-studio`, - * `` being one of `latest, beta, canary`. + * `` being one of `stable, beta, under-dev`. Note that there is a difference between `intellij` and `intellij-ue`. `ue` stands for IntelliJ Ultimate Edition and contains additional features for JavaScript as well as Go. If you are using the most recent version of your IDE, you likely want -`--define=ij_product=-beta` which will be the next version after -`-latest`. Additionally, `canary` can be a largely untested `alpha` +`--define=ij_product=-oss-beta` which will be the next version after +`-oss-stable`. Additionally, `under-dev` can be a largely untested `alpha` build of an upcoming version. A complete mapping of all currently defined versions can be found in `intellij_platform_sdk/build_defs.bzl`. You can import the project into IntelliJ (with the Bazel plugin) via importing the `ijwb/ijwb.bazelproject` file. +## Compatibility with IDE Versions + +You can build the plugin for different IDE versions by adjusting the `ij_product` +option either from command line or by updating the `.bazelproject` file to specify +the correct value for `ij_product` under `build_flags`. + +We have three aliases for product versions; + * `stable` is the IDE version supported by the Bazel plugin released to + the JetBrains stable channel. + * `beta` is the IDE version supported by the Bazel plugin released to + the JetBrains Beta channel. + * `under-dev` is the IDE version we are currently working towards supporting. + +Th current corresponding IDE versions of these aliases are: + +| Product-version alias | Version | +| ---------------------------------|:-------:| +| intellij-ue-oss-stable | 2020.3 | +| intellij-ue-oss-beta | 2020.3 | +| intellij-ue-oss-under-dev | 2021.1 | +| intellij-oss-stable | 2020.3 | +| intellij-oss-beta | 2020.3 | +| intellij-oss-under-dev | 2021.1 | +| android-studio-oss-stable | 2020.3 | +| android-studio-oss-beta | 2020.3 | +| android-studio-oss-under-dev | 2021.1 | +| clion-oss-stable | 2020.3 | +| clion-oss-beta | 2020.3 | +| clion-oss-under-dev | 2021.1 | + ## Contributions -We may be able to accept contributions in some circumstances. Some caveats: +We welcome contributions to support new IDE versions. However, to make +the review process faster and easier, we recommend the following: + + * Try to make changes in smaller patches. A smaller pull request will + make the review faster and more thorough. You are encouraged to have + separate pull requests each focusing on a ceratin incompatible change + rather than having a large pull request fixing multiple ones. + + * Since we continue to support a number of IDE versions while working on a new + one, you need to make sure that your proposed changes does not break + older versions. Our presubmit pipeline will take care of testing your changes + against all the supported versions and lets you know it broke anything. + + * To facilitate merging your changes into upstream, we recommend following + our procedure for supporting SDK backward-compatibility if needed. The code + for maintaining SDK compatibility lives in + [sdkcompat](https://github.com/bazelbuild/intellij/tree/master/sdkcompat) directory. + We follow these three techniques for non-trivial incompatible changes. + + * **Compat** + Preferred for small changes like a change in the return type of a method. + We add a util-class with only static methods and a private constructor and + wrap the changed method by one of the static methods. If the change is small enough, + you do not need to create a new util-class and should add a new method in + [BaseSdkCompat class](https://github.com/bazelbuild/intellij/blob/master/sdkcompat/v201/com/google/idea/sdkcompat/general/BaseSdkCompat.java) instead. Example: [pr/2345](https://github.com/bazelbuild/intellij/pull/2345) + + * **Adapter** + Used when we extend a super class and an overriden method signature changes + (e.g. a new parameter is added) or the super class constructor is updated. + We create a new class extending the changed super class to override the updated methods appropriately then extend this new class + from the plugin code. Example: [pr/2114](https://github.com/bazelbuild/intellij/pull/2114) + + * **Wrapper** + Created when a new interface is used in a super class constructor. We create + a wrapper class that wraps and supplies the old or the new interface based on + the SDK version and use this wrapper class in the plugin code. + Example: [pr/2166](https://github.com/bazelbuild/intellij/pull/2166) + + * All compat changes should be commented with #api{API_VERSION}, e.g. #api203. + This represents the last API version that requires the code, i.e. the one before + the version you aim to support. This is needed to make it easier to find and + clean this functionality when paving old versions. + + * Compat classes must never import plugin code and we try to avoid control flow in them. + + +We aslo accept contributions to fix general issues or adding new features with some caveats: * Before opening a pull request, first file an issue and discuss potential changes with the devs. This will often save you time you would otherwise have invested in a patch which can't be applied. + * Your changes should target one of the currently supported IDE versions. + You can find a list of these versions [here](https://github.com/bazelbuild/intellij/blob/master/intellij_platform_sdk/build_defs.bzl#L31). + Improvements to older versions will not be accepted. * We can't accept sylistic, refactoring, or "cleanup" changes. * We have very limited bandwidth, and applying patches upstream is a time-consuming process. Large patches generally can't be accepted unless there's clear value for all our users. + From 633fab29872b90244d540875894b6444e157dcb2 Mon Sep 17 00:00:00 2001 From: mai93 <70515749+mai93@users.noreply.github.com> Date: Mon, 24 May 2021 12:42:25 +0200 Subject: [PATCH 2/4] Update README.md --- README.md | 99 +++++++++++++++++++++++++++---------------------------- 1 file changed, 48 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 8852c64859f..a73f6102e9e 100644 --- a/README.md +++ b/README.md @@ -70,79 +70,76 @@ We have three aliases for product versions; the JetBrains Beta channel. * `under-dev` is the IDE version we are currently working towards supporting. -Th current corresponding IDE versions of these aliases are: - -| Product-version alias | Version | -| ---------------------------------|:-------:| -| intellij-ue-oss-stable | 2020.3 | -| intellij-ue-oss-beta | 2020.3 | -| intellij-ue-oss-under-dev | 2021.1 | -| intellij-oss-stable | 2020.3 | -| intellij-oss-beta | 2020.3 | -| intellij-oss-under-dev | 2021.1 | -| android-studio-oss-stable | 2020.3 | -| android-studio-oss-beta | 2020.3 | -| android-studio-oss-under-dev | 2021.1 | -| clion-oss-stable | 2020.3 | -| clion-oss-beta | 2020.3 | -| clion-oss-under-dev | 2021.1 | +The current corresponding IDE versions of these aliases can be found [here](./intellij_platform_sdk/build_defs.bzl#L31). ## Contributions We welcome contributions to support new IDE versions. However, to make the review process faster and easier, we recommend the following: - * Try to make changes in smaller patches. A smaller pull request will - make the review faster and more thorough. You are encouraged to have - separate pull requests each focusing on a ceratin incompatible change + * We can only accept small pull requests. A smaller pull request would likely have less review + comments and hence can get submitted much faster. For us, it is also much easier to integrate + such a small, focused pull request as it likely conflicts less with our internal code base. + For example, you should have separate pull requests each focusing on a certain incompatible change rather than having a large pull request fixing multiple ones. * Since we continue to support a number of IDE versions while working on a new - one, you need to make sure that your proposed changes does not break + one, you need to make sure that your proposed changes do not break older versions. Our presubmit pipeline will take care of testing your changes - against all the supported versions and lets you know it broke anything. + against all the supported versions and lets you know whether it broke anything. * To facilitate merging your changes into upstream, we recommend following - our procedure for supporting SDK backward-compatibility if needed. The code - for maintaining SDK compatibility lives in - [sdkcompat](https://github.com/bazelbuild/intellij/tree/master/sdkcompat) directory. - We follow these three techniques for non-trivial incompatible changes. + our procedure for supporting SDK backward-compatibility. - * **Compat** - Preferred for small changes like a change in the return type of a method. - We add a util-class with only static methods and a private constructor and - wrap the changed method by one of the static methods. If the change is small enough, - you do not need to create a new util-class and should add a new method in - [BaseSdkCompat class](https://github.com/bazelbuild/intellij/blob/master/sdkcompat/v201/com/google/idea/sdkcompat/general/BaseSdkCompat.java) instead. Example: [pr/2345](https://github.com/bazelbuild/intellij/pull/2345) - - * **Adapter** - Used when we extend a super class and an overriden method signature changes - (e.g. a new parameter is added) or the super class constructor is updated. - We create a new class extending the changed super class to override the updated methods appropriately then extend this new class - from the plugin code. Example: [pr/2114](https://github.com/bazelbuild/intellij/pull/2114) - - * **Wrapper** - Created when a new interface is used in a super class constructor. We create - a wrapper class that wraps and supplies the old or the new interface based on - the SDK version and use this wrapper class in the plugin code. - Example: [pr/2166](https://github.com/bazelbuild/intellij/pull/2166) - - * All compat changes should be commented with #api{API_VERSION}, e.g. #api203. + * First consider adjusting the plugin code so that it directly works with different IDE versions. + Example strategies for this would be: + + * Switching to a (possibly newer) IntelliJ platform API which is available in all relevant IDE versions. Example: [pr/2623](https://github.com/bazelbuild/intellij/pull/2623) + * Switching to a raw class by removing a generic type parameter which differs across versions. Example: [pr/2631](https://github.com/bazelbuild/intellij/pull/2631) + + * For non-trivial incompatible changes, the code for maintaining SDK compatibility lives + in [sdkcompat](./sdkcompat) and [testing/testcompat](./testing/testcompat) directories. Where `testing/testcompat` + holds test-only SDK compatibility changes. Each of the two directories contains a sub-folder per supported IDE version with + version-specific implementations. The outside API of all classes must be the same across versions. + Just the implementation may differ. When introducing a new file in this directory, make sure to duplicate + it appropriately across all versions. + We follow these three techniques for non-trivial incompatible changes. + + * **Compat** + Preferred to Adapter and Wrapper when applicable. We add a util-class with + only static methods and a private constructor and wrap the changed method by one of the + static methods. If the change is small enough, you do not need to create a new util-class + and should add the change to [BaseSdkCompat class](./sdkcompat/v203/com/google/idea/sdkcompat/general/BaseSdkCompat.java) + instead. Example: [pr/2345](https://github.com/bazelbuild/intellij/pull/2345) + + * **Adapter** + Used when we extend a super class and its constructor is updated. + We create a new class extending the changed super class then extend this new class + from the plugin code. Example: [pr/2352](https://github.com/bazelbuild/intellij/pull/2352) + + * **Wrapper** + Created when a new interface is used in a super class constructor. We create + a wrapper class that wraps and supplies the old or the new interface based on + the SDK version and use this wrapper class in the plugin code. + Example: [pr/2166](https://github.com/bazelbuild/intellij/pull/2166) + + * All compat changes must be commented with `#api{API_VERSION}`, e.g. `#api203`. This represents the last API version that requires the code, i.e. the one before the version you aim to support. This is needed to make it easier to find and - clean this functionality when paving old versions. + clean up this functionality when paving old versions. - * Compat classes must never import plugin code and we try to avoid control flow in them. + * Compat classes must never import plugin code and we try to keep the logic and code in them + as minimal as possible. -We aslo accept contributions to fix general issues or adding new features with some caveats: +We may also be able to accept contributions to fix general issues or adding new features with some caveats: * Before opening a pull request, first file an issue and discuss potential changes with the devs. This will often save you time you would otherwise have invested in a patch which can't be applied. - * Your changes should target one of the currently supported IDE versions. - You can find a list of these versions [here](https://github.com/bazelbuild/intellij/blob/master/intellij_platform_sdk/build_defs.bzl#L31). - Improvements to older versions will not be accepted. + * Improvements for old not supported IDE versions will not be accepted. + Your changes should target the currently supported IDE versions. + You can find a list of these versions [here](./intellij_platform_sdk/build_defs.bzl#L31). * We can't accept sylistic, refactoring, or "cleanup" changes. * We have very limited bandwidth, and applying patches upstream is a time-consuming process. Large patches generally can't be accepted unless From a195bafd50209a076d52ea33da08b20ecc0323de Mon Sep 17 00:00:00 2001 From: mai93 <70515749+mai93@users.noreply.github.com> Date: Wed, 26 May 2021 17:20:26 +0200 Subject: [PATCH 3/4] Applying review comments --- README.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a73f6102e9e..8df242b7b61 100644 --- a/README.md +++ b/README.md @@ -77,11 +77,9 @@ The current corresponding IDE versions of these aliases can be found [here](./in We welcome contributions to support new IDE versions. However, to make the review process faster and easier, we recommend the following: - * We can only accept small pull requests. A smaller pull request would likely have less review - comments and hence can get submitted much faster. For us, it is also much easier to integrate - such a small, focused pull request as it likely conflicts less with our internal code base. - For example, you should have separate pull requests each focusing on a certain incompatible change - rather than having a large pull request fixing multiple ones. + * We can only accept small pull requests. Smaller pull requests tend to have + less review comments and hence can get submitted much faster. They also tend + to conflict less with our internal code base, simplifying the integration for us. * Since we continue to support a number of IDE versions while working on a new one, you need to make sure that your proposed changes do not break @@ -98,10 +96,10 @@ the review process faster and easier, we recommend the following: * Switching to a raw class by removing a generic type parameter which differs across versions. Example: [pr/2631](https://github.com/bazelbuild/intellij/pull/2631) * For non-trivial incompatible changes, the code for maintaining SDK compatibility lives - in [sdkcompat](./sdkcompat) and [testing/testcompat](./testing/testcompat) directories. Where `testing/testcompat` + in [sdkcompat](./sdkcompat) and [testing/testcompat](./testing/testcompat) directories, where `testing/testcompat` holds test-only SDK compatibility changes. Each of the two directories contains a sub-folder per supported IDE version with - version-specific implementations. The outside API of all classes must be the same across versions. - Just the implementation may differ. When introducing a new file in this directory, make sure to duplicate + version-specific implementations. The outside API of all classes must be the same across versions, just + the implementation may differ. When introducing a new file in this directory, make sure to duplicate it appropriately across all versions. We follow these three techniques for non-trivial incompatible changes. From c7ea284a5dcb989f3dd691669c50aba4ae490741 Mon Sep 17 00:00:00 2001 From: mai93 <70515749+mai93@users.noreply.github.com> Date: Thu, 27 May 2021 11:23:29 +0200 Subject: [PATCH 4/4] Apply review comments --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8df242b7b61..543290558ba 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,9 @@ the review process faster and easier, we recommend the following: * We can only accept small pull requests. Smaller pull requests tend to have less review comments and hence can get submitted much faster. They also tend - to conflict less with our internal code base, simplifying the integration for us. + to conflict less with our internal code base, simplifying the integration for us. + For example, you should have separate pull requests each focusing on a certain incompatible change + rather than having a large pull request fixing multiple ones. * Since we continue to support a number of IDE versions while working on a new one, you need to make sure that your proposed changes do not break