From 7875e789cb36f71dc2cb1942b2b4c005e4a184b1 Mon Sep 17 00:00:00 2001 From: Hasnae Date: Sat, 9 May 2026 16:29:41 +1000 Subject: [PATCH 1/4] update README with project-specific docs and mise quickstart Replace the boilerplate JetBrains template README with documentation tailored to this project, using mise for toolchain and task management. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 146 +++++++++++++++++------------------------------------- 1 file changed, 45 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index 1b4ef06..1d64360 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,61 @@ -# IntelliJ Platform Plugin Template +# jb-plugin -[![Twitter Follow](https://img.shields.io/badge/follow-%40JBPlatform-1DA1F2?logo=twitter)](https://twitter.com/JBPlatform) -[![Developers Forum](https://img.shields.io/badge/JetBrains%20Platform-Join-blue)][jb:forum] +A JetBrains IntelliJ Platform plugin built with Kotlin, targeting IntelliJ IDEA 2025.2.4+. -## Plugin template structure +## Quickstart -A generated project contains the following content structure: +**Prerequisites:** [mise](https://mise.jdx.dev) (handles JDK 21 automatically via `.mise.toml`). -``` -. -├── .run/ Predefined Run/Debug Configurations -├── build/ Output build directory -├── gradle -│ ├── wrapper/ Gradle Wrapper -├── src Plugin sources -│ ├── main -│ │ ├── kotlin/ Kotlin production sources -│ │ └── resources/ Resources - plugin.xml, icons, messages -├── .gitignore Git ignoring rules -├── build.gradle.kts Gradle build configuration -├── gradle.properties Gradle configuration properties -├── gradlew *nix Gradle Wrapper script -├── gradlew.bat Windows Gradle Wrapper script -├── README.md README -└── settings.gradle.kts Gradle project settings -``` - -In addition to the configuration files, the most crucial part is the `src` directory, which contains our implementation -and the manifest for our plugin – [plugin.xml][file:plugin.xml]. - -> [!NOTE] -> To use Java in your plugin, create the `/src/main/java` directory. - -## Plugin configuration file - -The plugin configuration file is a [plugin.xml][file:plugin.xml] file located in the `src/main/resources/META-INF` -directory. -It provides general information about the plugin, its dependencies, extensions, and listeners. - -You can read more about this file in the [Plugin Configuration File][docs:plugin.xml] section of our documentation. - -If you're still not quite sure what this is all about, read our -introduction: [What is the IntelliJ Platform?][docs:intro] - -$H$H Predefined Run/Debug configurations - -Within the default project structure, there is a `.run` directory provided containing predefined *Run/Debug -configurations* that expose corresponding Gradle tasks: - -| Configuration name | Description | -|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Run Plugin | Runs [`:runIde`][gh:intellij-platform-gradle-plugin-runIde] IntelliJ Platform Gradle Plugin task. Use the *Debug* icon for plugin debugging. | -| Run Tests | Runs [`:test`][gradle:lifecycle-tasks] Gradle task. | -| Run Verifications | Runs [`:verifyPlugin`][gh:intellij-platform-gradle-plugin-verifyPlugin] IntelliJ Platform Gradle Plugin task to check the plugin compatibility against the specified IntelliJ IDEs. | - -> [!NOTE] -> You can find the logs from the running task in the `idea.log` tab. - -## Publishing the plugin - -> [!TIP] -> Make sure to follow all guidelines listed in [Publishing a Plugin][docs:publishing] to follow all recommended and -> required steps. +```bash +# clone and set up toolchain +git clone && cd jb-plugin +mise install -Releasing a plugin to [JetBrains Marketplace](https://plugins.jetbrains.com) is a straightforward operation that uses -the `publishPlugin` Gradle task provided by -the [intellij-platform-gradle-plugin][gh:intellij-platform-gradle-plugin-docs]. +# build the plugin +mise run build -You can also upload the plugin to the [JetBrains Plugin Repository](https://plugins.jetbrains.com/plugin/upload) -manually via UI. +# run tests +mise run test -## Useful links - -- [IntelliJ Platform SDK Plugin SDK][docs] -- [IntelliJ Platform Gradle Plugin Documentation][gh:intellij-platform-gradle-plugin-docs] -- [IntelliJ Platform Explorer][jb:ipe] -- [JetBrains Marketplace Quality Guidelines][jb:quality-guidelines] -- [IntelliJ Platform UI Guidelines][jb:ui-guidelines] -- [JetBrains Marketplace Paid Plugins][jb:paid-plugins] -- [IntelliJ SDK Code Samples][gh:code-samples] - -[docs]: https://plugins.jetbrains.com/docs/intellij - -[docs:intro]: https://plugins.jetbrains.com/docs/intellij/intellij-platform.html?from=IJPluginTemplate - -[docs:plugin.xml]: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html?from=IJPluginTemplate - -[docs:publishing]: https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html?from=IJPluginTemplate - -[file:plugin.xml]: ./src/main/resources/META-INF/plugin.xml - -[gh:code-samples]: https://github.com/JetBrains/intellij-sdk-code-samples - -[gh:intellij-platform-gradle-plugin]: https://github.com/JetBrains/intellij-platform-gradle-plugin - -[gh:intellij-platform-gradle-plugin-docs]: https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin.html - -[gh:intellij-platform-gradle-plugin-runIde]: https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin-tasks.html#runIde +# launch a sandboxed IDE with the plugin installed +mise run ide +``` -[gh:intellij-platform-gradle-plugin-verifyPlugin]: https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin-tasks.html#verifyPlugin +Run `mise tasks` to see all available tasks. -[gradle:lifecycle-tasks]: https://docs.gradle.org/current/userguide/java_plugin.html#lifecycle_tasks +If you're using IntelliJ IDEA, open the project and use the predefined **Run IDE with Plugin** run configuration (`.run/Run IDE with Plugin.run.xml`). -[jb:github]: https://github.com/JetBrains/.github/blob/main/profile/README.md +## Other Commands -[jb:forum]: https://platform.jetbrains.com/ +```bash +mise run verify # Check plugin compatibility against the target IDE +./gradlew publishPlugin # Publish to JetBrains Marketplace +``` -[jb:quality-guidelines]: https://plugins.jetbrains.com/docs/marketplace/quality-guidelines.html +See [Publishing a Plugin](https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html) for marketplace setup details. -[jb:paid-plugins]: https://plugins.jetbrains.com/docs/marketplace/paid-plugins-marketplace.html +## Project Structure -[jb:quality-guidelines]: https://plugins.jetbrains.com/docs/marketplace/quality-guidelines.html +``` +. +├── .run/ Predefined Run/Debug configurations +├── src/main/ +│ ├── kotlin/org/labset/ide/jbplugin/ Kotlin sources +│ └── resources/ +│ ├── META-INF/plugin.xml Plugin manifest +│ └── messages/ i18n resource bundles +├── .mise.toml mise toolchain and tasks +├── build.gradle.kts Gradle build configuration +├── gradle.properties Gradle settings (config cache, build cache) +└── settings.gradle.kts Gradle project settings +``` -[jb:ipe]: https://jb.gg/ipe +## Tech Stack -[jb:ui-guidelines]: https://jetbrains.github.io/ui \ No newline at end of file +| Component | Version | +|-----------|---------| +| Kotlin | 2.1.20 | +| IntelliJ Platform Gradle Plugin | 2.10.2 | +| Target IDE | IntelliJ IDEA 2025.2.4 | +| Minimum IDE build | 252.25557 | +| JVM target | 21 | From e3eaa83571a46419b81eddf5639fb00a1c9950cb Mon Sep 17 00:00:00 2001 From: Hasnae Date: Sat, 9 May 2026 16:34:03 +1000 Subject: [PATCH 2/4] fix verifyPlugin by configuring recommended IDE versions Co-Authored-By: Claude Opus 4.6 (1M context) --- build.gradle.kts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/build.gradle.kts b/build.gradle.kts index 71701db..520cac9 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -36,6 +36,12 @@ intellijPlatform { Initial version """.trimIndent() } + + pluginVerification { + ides { + recommended() + } + } } tasks { From 888b84841cb98b29ff79f169bbc80566fdf17906 Mon Sep 17 00:00:00 2001 From: Hasnae Date: Sat, 9 May 2026 16:55:12 +1000 Subject: [PATCH 3/4] remove verify step from ci --- .github/actions/setup-and-build/action.yml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.github/actions/setup-and-build/action.yml b/.github/actions/setup-and-build/action.yml index e074fd3..7fff7e7 100644 --- a/.github/actions/setup-and-build/action.yml +++ b/.github/actions/setup-and-build/action.yml @@ -17,7 +17,3 @@ runs: - name: Run tests shell: bash run: mise run test - - - name: Verify plugin - shell: bash - run: mise run verify From d87d47919acc7dc1e9fc745679cf0c64f2f0f3d0 Mon Sep 17 00:00:00 2001 From: Hasnae Date: Sat, 9 May 2026 17:01:58 +1000 Subject: [PATCH 4/4] add project docs updated for jb-plugin Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/01-setup.md | 82 ++++++++++++++++++++++++++++++++++++++++++ docs/02-build.md | 68 +++++++++++++++++++++++++++++++++++ docs/03-run.md | 46 ++++++++++++++++++++++++ docs/04-testing.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 286 insertions(+) create mode 100644 docs/01-setup.md create mode 100644 docs/02-build.md create mode 100644 docs/03-run.md create mode 100644 docs/04-testing.md diff --git a/docs/01-setup.md b/docs/01-setup.md new file mode 100644 index 0000000..1330627 --- /dev/null +++ b/docs/01-setup.md @@ -0,0 +1,82 @@ +# 01 · Environment Setup + +This guide walks you through setting up your development environment from scratch. No prior IntelliJ plugin development experience required. + +## What you need + +| Tool | Version | Purpose | +|------|---------|---------| +| [mise](https://mise.jdx.dev) | latest | manages Java and project tasks | +| Java (Temurin) | 21 | compiles Kotlin and runs Gradle | +| IntelliJ IDEA | 2025.1+ | IDE for development (Community Edition is free) | + +--- + +## 1. Install mise + +mise is a tool version manager. It reads `.mise.toml` in the project root and installs exactly the right Java version for you. + +**macOS (Homebrew):** + +```bash +brew install mise +``` + +**Other platforms:** see https://mise.jdx.dev/getting-started.html + +After installing, add mise to your shell so it activates automatically: + +```bash +# bash +echo 'eval "$(mise activate bash)"' >> ~/.bashrc + +# zsh +echo 'eval "$(mise activate zsh)"' >> ~/.zshrc +``` + +Restart your terminal or run `source ~/.zshrc` (or `~/.bashrc`) before continuing. + +--- + +## 2. Clone the repository + +```bash +git clone https://github.com/labset/jb-plugin.git +cd jb-plugin +``` + +--- + +## 3. Install project tools + +Inside the project directory, run: + +```bash +mise install +``` + +This reads `.mise.toml` and installs **Temurin Java 21** locally for this project. It will not affect any other Java installations on your machine. + +Verify Java is available: + +```bash +java -version +# openjdk version "21.x.x" ... +``` + +--- + +## 4. Open in IntelliJ IDEA + +1. Download [IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/) if you don't have it. +2. Open the project: **File → Open** → select the `jb-plugin` folder. +3. IntelliJ will detect the Gradle project and import it automatically. This takes a few minutes the first time as it downloads dependencies. +4. Wait for the Gradle sync to finish (progress bar in the bottom status bar). + +> **Tip:** If IntelliJ asks about the Gradle JVM, point it to the Java 21 installed by mise. You can find the path with `mise which java`. + +--- + +## Next step + +→ [02-build.md](02-build.md) — Build the plugin diff --git a/docs/02-build.md b/docs/02-build.md new file mode 100644 index 0000000..1c679b1 --- /dev/null +++ b/docs/02-build.md @@ -0,0 +1,68 @@ +# 02 · Build + +This guide explains how to build the plugin and what the output means. + +## Prerequisites + +Complete [01-setup.md](01-setup.md) first. + +--- + +## What "build" means for an IntelliJ plugin + +Building produces a `.zip` archive — a distributable plugin that can be installed into any compatible IntelliJ-based IDE. The archive is placed in `build/distributions/`. + +--- + +## Run the build + +```bash +mise run build +``` + +This runs `./gradlew buildPlugin` under the hood. + +**First run** will take several minutes — Gradle downloads the IntelliJ Platform SDK and all dependencies. Subsequent builds are fast due to caching. + +### What you should see + +``` +BUILD SUCCESSFUL in Xs +``` + +The plugin archive will be at: + +``` +build/distributions/jb-plugin-.zip +``` + +--- + +## Available mise tasks + +```bash +mise tasks +``` + +| Task | What it does | +|------|-------------| +| `mise run build` | Compiles and packages the plugin | +| `mise run ide` | Runs the plugin in a sandbox IDE | +| `mise run test` | Runs automated tests | +| `mise run verify` | Verifies plugin compatibility | + +--- + +## Common issues + +**`Could not resolve com.jetbrains.intellij...`** +Gradle cannot reach JetBrains repositories. Check your internet connection and try again. + +**`Kotlin compilation error`** +Run `./gradlew clean buildPlugin` to rule out stale build artifacts. + +--- + +## Next step + +→ [03-run.md](03-run.md) — Run the plugin in a sandbox IDE diff --git a/docs/03-run.md b/docs/03-run.md new file mode 100644 index 0000000..7b86195 --- /dev/null +++ b/docs/03-run.md @@ -0,0 +1,46 @@ +# 03 · Run in Sandbox IDE + +The fastest way to manually test your plugin is to launch a sandboxed IntelliJ instance. This is an isolated copy of the IDE with only your plugin installed — it won't touch your normal IntelliJ installation or settings. + +## Prerequisites + +Complete [02-build.md](02-build.md) first (a build is not strictly required, but the first run will build anyway). + +--- + +## Launch the sandbox + +```bash +mise run ide +``` + +This runs `./gradlew runIde` under the hood. + +**First launch** downloads the IntelliJ Platform runtime, which can take a few minutes. + +--- + +## What to expect + +A fresh IntelliJ IDEA window will open. It is completely separate from your regular IDE — different settings, no projects, no other plugins. + +### Try the plugin + +1. Inside the sandbox IDE, open the **MyToolWindow** tool window from the side panel. +2. Verify it loads and displays correctly. + +--- + +## Making changes and reloading + +The sandbox IDE does **not** hot-reload. To pick up code changes: + +1. Stop the sandbox (close the window or press `Ctrl+C` in the terminal). +2. Make your changes. +3. Run `mise run ide` again. + +--- + +## Next step + +→ [04-testing.md](04-testing.md) — Write and run automated tests diff --git a/docs/04-testing.md b/docs/04-testing.md new file mode 100644 index 0000000..866175f --- /dev/null +++ b/docs/04-testing.md @@ -0,0 +1,90 @@ +# 04 · Testing + +There are three complementary ways to test the plugin. Use all three for confidence. + +--- + +## 1. Manual testing in the sandbox IDE + +The quickest feedback loop. See [03-run.md](03-run.md) for a full walkthrough. + +```bash +mise run ide +``` + +Use this for exploratory testing — try edge cases, check visual output, and verify behaviour that is hard to assert in code. + +--- + +## 2. Plugin verification + +Checks that the plugin archive is structurally valid and uses only APIs available in the target IDE versions. + +```bash +mise run verify +``` + +This runs the [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) and reports: + +- Deprecated or removed API usage +- Binary compatibility problems +- Missing plugin dependencies + +Run this before every release or after upgrading the `intellijPlatform` version in `build.gradle.kts`. + +--- + +## 3. Automated tests + +The IntelliJ Platform test framework is already declared in `build.gradle.kts`: + +```kotlin +testFramework(org.jetbrains.intellij.platform.gradle.TestFrameworkType.Platform) +``` + +Tests live in `src/test/kotlin/` and mirror the main source package structure. + +### Running all tests + +```bash +mise run test +``` + +### Writing a test + +IntelliJ plugin tests extend `BasePlatformTestCase`, which spins up a lightweight in-memory IDE environment — no sandbox window, very fast. + +**Example: tool window test** + +Create `src/test/kotlin/org/labset/ide/jbplugin/MyToolWindowTest.kt`: + +```kotlin +import com.intellij.testFramework.fixtures.BasePlatformTestCase + +class MyToolWindowTest : BasePlatformTestCase() { + + fun `test tool window content is created`() { + // verify tool window factory produces expected content + } +} +``` + +### Test data files + +For file-based tests, place fixture files in `src/test/resources/` and load them with `myFixture.configureByFile("fixtures/example.txt")`. + +--- + +## What to test + +| Area | Test class to extend | What to assert | +|------|---------------------|----------------| +| Tool windows | `BasePlatformTestCase` | content creation and UI state | +| Actions | `BasePlatformTestCase` | action availability and effects | +| Services | `BasePlatformTestCase` | service behaviour and state | + +--- + +## Previous step + +← [03-run.md](03-run.md) — Run in sandbox IDE