Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README.md #2608

Merged
merged 4 commits into from
May 27, 2021
Merged

Update README.md #2608

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5101bfc
Update README.md
mai93 May 12, 2021
633fab2
Update README.md
mai93 May 24, 2021
a195baf
Applying review comments
mai93 May 26, 2021
c7ea284
Apply review comments
mai93 May 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 48 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
mai93 marked this conversation as resolved.
Show resolved Hide resolved
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.
mai93 marked this conversation as resolved.
Show resolved Hide resolved

* 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`
mai93 marked this conversation as resolved.
Show resolved Hide resolved
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
mai93 marked this conversation as resolved.
Show resolved Hide resolved
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
Expand Down