You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Alternatively, if you have separately built the plugin and already installed it
41
+
in a Gateway distribution you can launch that distribution with the URL as the
42
+
first argument (no `--args` in this case).
43
+
44
+
If your change is something users ought to be aware of, add an entry in the
45
+
changelog.
46
+
47
+
Generally we prefer that PRs be squashed into `main` but you can rebase or merge
48
+
if it is important to keep the individual commits (make sure to clean up the
49
+
commits first if you are doing this).
50
+
51
+
## Testing
52
+
53
+
Run tests with `./gradlew test`. By default this will test against
54
+
`https://dev.coder.com` but you can set `CODER_GATEWAY_TEST_DEPLOYMENT` to a URL
55
+
of your choice or to `mock` to use mocks only.
56
+
57
+
There are two ways of using the plugin: from standalone Gateway, and from within
58
+
an IDE (`File` > `Remote Development`). There are subtle differences so it
59
+
makes usually sense to test both. We should also be testing both the latest
60
+
stable and latest EAP.
61
+
62
+
## Plugin compatibility
63
+
64
+
`./gradlew runPluginVerifier` can check the plugin compatibility against the specified Gateway. The integration with Github Actions is commented until [this gradle intellij plugin issue](https://github.com/JetBrains/gradle-intellij-plugin/issues/1027) is fixed.
65
+
66
+
## Releasing
67
+
68
+
1. Check that the changelog lists all the important changes.
69
+
2. Update the gradle.properties version.
70
+
3. Publish the resulting draft release after validating it.
71
+
4. Merge the resulting changelog PR.
72
+
73
+
## `main` vs `eap` branch
74
+
75
+
Sometimes there can be API incompatibilities between the latest stable version
76
+
of Gateway and EAP ones (Early Access Program).
77
+
78
+
If this happens, use the `eap` branch to make a separate release. Once it
79
+
becomes stable, update the versions in `main`.
80
+
81
+
## Supported Coder versions
82
+
83
+
`Coder Gateway` includes checks for compatibility with a specified version
84
+
range. A warning is raised when the Coder deployment build version is outside of
85
+
compatibility range.
86
+
87
+
At the moment the upper range is 3.0.0 so the check essentially has no effect,
88
+
but in the future we may want to keep this updated.
2. run `./gradlew clean buildPlugin` to generate a zip distribution
38
-
3. locate the zip file in the `build/distributions` folder and follow [these instructions](https://www.jetbrains.com/help/idea/managing-plugins.html#install_plugin_from_disk) on how to install a plugin from disk.
39
-
40
-
Alternatively, `./gradlew clean runIde` will deploy a Gateway distribution (the one specified in `gradle.properties` - `platformVersion`) with the latest plugin changes deployed.
41
-
42
-
To simulate opening a workspace from the dashboard pass the Gateway link via `--args`. For example:
`src` directory is the most important part of the project, the Coder Gateway implementation and the manifest for the plugin – [`plugin.xml`](src/main/resources/META-INF/plugin.xml).
77
-
78
-
### Gradle Configuration Properties
79
-
80
-
The project-specific configuration file [`gradle.properties`](gradle.properties) contains:
|`pluginGroup`| Package name, set to `com.coder.gateway`. |
85
-
|`pluginName`| Zip filename. |
86
-
|`pluginVersion`| The current version of the plugin in [SemVer](https://semver.org/) format. |
87
-
|`pluginSinceBuild`| The `since-build` attribute of the `<idea-version>` tag. The minimum Gateway build supported by the plugin |
88
-
|`pluginUntilBuild`| The `until-build` attribute of the `<idea-version>` tag. Supported Gateway builds, until & not inclusive |
89
-
|`platformType`| The type of IDE distribution, in this GW. |
90
-
|`platformVersion`| The version of the Gateway used to build&run the plugin. |
91
-
|`platformDownloadSources`| Gateway sources downloaded while initializing the Gradle build. Note: Gateway does not have open sources |
92
-
|`platformPlugins`| Comma-separated list of dependencies to the bundled Gateway plugins and plugins from the Plugin Repositories. |
93
-
|`javaVersion`| Java language level used to compile sources and generate the files for - Java 11 is required since 2020.3. |
94
-
|`gradleVersion`| Version of Gradle used for plugin development. |
95
-
96
-
The properties listed define the plugin itself or configure the [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin) – check its documentation for more details.
97
-
98
-
### Testing
99
-
100
-
Run tests with `./gradlew test`. By default this will test against
101
-
`https://dev.coder.com` but you can set `CODER_GATEWAY_TEST_DEPLOYMENT` to a URL
102
-
of your choice or to `mock` to use mocks only.
103
-
104
-
### Code Monitoring
105
-
106
-
Code quality is monitored with the help of [Qodana](https://www.jetbrains.com/qodana/)
107
-
108
-
Qodana inspections are accessible within the project on two levels:
109
-
110
-
- using the [Qodana IntelliJ GitHub Action][docs:qodana-github-action], run automatically within the [Build](.github/workflows/build.yml) workflow,
111
-
- with the [Gradle Qodana Plugin](https://github.com/JetBrains/gradle-qodana-plugin), so you can use it on the local environment or any CI other than GitHub Actions.
112
-
113
-
Qodana inspection is configured with the `qodana { ... }` section in the [Gradle build file](build.gradle.kts) and [`qodana.yml`](qodana.yml) YAML configuration file.
114
-
115
-
> **NOTE:** Qodana requires Docker to be installed and available in your environment.
116
-
117
-
To run inspections, you can use a predefined *Run Qodana* configuration, which will provide a full report on `http://localhost:8080`, or invoke the Gradle task directly with the `./gradlew runInspections` command.
118
-
119
-
A final report is available in the `./build/reports/inspections/` directory.
120
-
121
-
122
-
123
-
### Plugin compatibility
124
-
125
-
`./gradlew runPluginVerifier` can check the plugin compatibility against the specified Gateway. The integration with Github Actions is commented until [this gradle intellij plugin issue](https://github.com/JetBrains/gradle-intellij-plugin/issues/1027) is fixed.
126
-
127
-
## Continuous integration
128
-
129
-
In the `.github/workflows` directory, you can find definitions for the following GitHub Actions workflows:
130
-
131
-
-[Build](.github/workflows/build.yml)
132
-
- Triggered on `push` and `pull_request` events.
133
-
- Runs the *Gradle Wrapper Validation Action* to verify the wrapper's checksum.
134
-
- Runs the `verifyPlugin` and `test` Gradle tasks.
135
-
- Builds the plugin with the `buildPlugin` Gradle task and provides the artifact for the next jobs in the workflow.
136
-
-~~Verifies the plugin using the *IntelliJ Plugin Verifier* tool.~~ (this is commented until [this issue](https://github.com/JetBrains/gradle-intellij-plugin/issues/1027) is fixed)
137
-
- Prepares a draft release of the GitHub Releases page for manual verification.
138
-
-[Release](.github/workflows/release.yml)
139
-
- Triggered on `Publish release` event.
140
-
- Updates `CHANGELOG.md` file with the content provided with the release note.
141
-
- Publishes the plugin to JetBrains Marketplace using the provided `PUBLISH_TOKEN`.
142
-
- Sets publish channel depending on the plugin version, i.e. `1.0.0-beta` -> `beta` channel. For now, both `main`
143
-
and `eap` branches are published on default release channel.
144
-
- Patches the Changelog and commits.
145
-
146
-
### Release flow
147
-
148
-
When the `main` or `eap` branch receives a new pull request or a direct push, the [Build](.github/workflows/build.yml) workflow runs builds the plugin and prepares a draft release.
149
-
150
-
The draft release is a working copy of a release, which you can review before publishing.
151
-
It includes a predefined title and git tag, the current plugin version, for example, `v2.1.0`.
152
-
The changelog is provided automatically using the [gradle-changelog-plugin][gh:gradle-changelog-plugin].
153
-
An artifact file is also built with the plugin attached. Every new Build overrides the previous draft to keep the *Releases* page clean.
154
-
155
-
When you edit the draft and use the <kbd>Publish release</kbd> button, GitHub will tag the repository with the given version and add a new entry to the Releases tab.
156
-
Next, it will notify users who are *watching* the repository, triggering the final [Release](.github/workflows/release.yml) workflow.
157
-
158
-
> **IMPORTANT:**`pluginVersion` from `gradle.properties` needs to be manually increased after a release.
159
-
160
-
### Plugin signing
161
-
162
-
Plugin Signing is a mechanism introduced in the 2021.2 release cycle to increase security in [JetBrains Marketplace](https://plugins.jetbrains.com).
163
-
164
-
JetBrains Marketplace signing is designed to ensure that plugins are not modified over the course of the publishing and delivery pipeline.
165
-
166
-
The plugin signing configuration is disabled for coder-gateway. To find out how to generate signing certificates and how to configure the signing task,
167
-
check the [Plugin Signing][docs:plugin-signing] section in the IntelliJ Platform Plugin SDK documentation.
168
-
169
-
### Publishing the plugin
170
-
171
-
[gradle-intellij-plugin][gh:gradle-intellij-plugin-docs] provides the `publishPlugin` Gradle task to upload the plugin artifacts. The [Release](.github/workflows/release.yml) workflow
172
-
automates this process by running the task when a new release appears in the GitHub Releases section.
173
-
174
-
> **Note**
175
-
>
176
-
> Set a suffix to the plugin version to publish it in the custom repository channel, i.e. `v1.0.0-beta` will push your plugin to the `beta`[release channel][docs:release-channel].
177
-
178
-
The authorization process relies on the `PUBLISH_TOKEN` secret environment variable, specified in the _Secrets_ section of the repository _Settings_.
179
-
180
-
You can get that token in your JetBrains Marketplace profile dashboard in the [My Tokens][jb:my-tokens] tab.
181
-
182
-
## Changelog maintenance
183
-
184
-
When releasing an update, it is essential to let users know what the new version offers.
185
-
The best way to do this is to provide release notes.
186
-
187
-
The changelog is a curated list that contains information about any new features, fixes, and deprecations.
188
-
When they are provided, these lists are available in a few different places:
189
-
190
-
- the [CHANGELOG.md](./CHANGELOG.md) file,
191
-
- the [Releases page][gh:releases],
192
-
- the *What's new* section of JetBrains Marketplace Plugin page,
193
-
- and inside the Plugin Manager's item details.
194
-
195
-
Coder Gateway follows the [Keep a Changelog][keep-a-changelog] approach for handling the project's changelog.
196
-
197
-
The [Gradle Changelog Plugin][gh:gradle-changelog-plugin] takes care of propagating information provided within the [CHANGELOG.md](./CHANGELOG.md) to the [Gradle IntelliJ Plugin][gh:gradle-intellij-plugin].
198
-
You only have to take care of writing down the actual changes in proper sections of the `[Unreleased]` section.
199
-
200
-
You start with an almost empty changelog:
201
-
202
-
```
203
-
# YourPlugin Changelog
204
-
205
-
## [Unreleased]
206
-
### Added
207
-
- Initial scaffold created from [IntelliJ Platform Plugin Template](https://github.com/JetBrains/intellij-platform-plugin-template)
208
-
```
209
-
210
-
Now proceed with providing more entries to the `Added` group, or any other one that suits your change the most (see [How do I make a good changelog?][keep-a-changelog-how] for more details).
211
-
212
-
When releasing a plugin update, you don't have to care about bumping the `[Unreleased]` header to the upcoming version – it will be handled automatically on the Continuous Integration (CI) after you publish your plugin.
213
-
GitHub Actions will swap it and provide you an empty section for the next release so that you can proceed with the development:
214
-
215
-
```
216
-
# YourPlugin Changelog
217
-
218
-
## [Unreleased]
219
-
220
-
## [0.0.1]
221
-
### Added
222
-
- An awesome feature
223
-
224
-
### Fixed
225
-
- One annoying bug
226
-
```
227
-
228
-
## `main` vs `eap` branch
229
-
230
-
Gateway API has not reached maturity. More often than not, there are API incompatibilities between
231
-
the latest stable version of Gateway and EAP ones (Early Access Program). To provide support for both
232
-
versions of Gateway we've decided:
233
-
234
-
- to have two branches for releases: `main` and `eap`
235
-
-`main` branch will provide support for the latest stable Gateway release, while `eap` will provide
236
-
support for releases in the EAP program.
237
-
- both versions of the plugin will keep the MAJOR.MINOR.PATCH numbers in sync. When there is a fix
238
-
in the plugin's business code, these versions will change and the changes on the `main` branch will
239
-
have to be merged on the `eap` branch as well.
240
-
- releases from `eap` branch are suffixed with `-eap.x`. `x` will allow releases for the same plugin
241
-
functionality but with support for a different Gateway EAP version. In other words, version `2.1.2`
242
-
of the plugin supports Gateway 2022.2 while version `2.1.2-eap.0` supports some builds in the Gateway
243
-
2022.3 EAP. `2.1.2-eap.1` might have to support a newer version of EAP.
244
-
- when Gateway 2022.3 EAP is released in the stable channel then `eap` branch will have to be merged back
245
-
in the `main` branch, and it will start supporting the next EAP builds.
246
-
- releases from both branches are published in the stable release channel. Jetbrains provides support for
247
-
different release channels (ex: `eap` or `beta`), but all of them except the stable channel have to be
248
-
manually configured by users in Gateway - which is super inconvenient.
249
-
250
-
## Supported Coder versions
251
-
252
-
`Coder Gateway` includes checks for compatibility with a specified version range. A warning is raised when
253
-
the Coder deployment build version is outside of compatibility range:
254
-
255
-
256
-
The range needs to be manually updated as often as possible. The lowest bound is specified by `minCompatibleCoderVersion`
257
-
property in the [CoderSupportedVersions.properties](src/main/resources/version/CoderSupportedVersions.properties)
258
-
while `maxCompatibleCoderVersion` specifies the upper bound.
0 commit comments