diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6c402ef..8e8dfe3 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -46,8 +46,8 @@ jobs: - name: Trace requirements run: ./gradlew --warning-mode=all traceRequirements - - name: Build plugin distribution - run: ./gradlew --stacktrace --warning-mode=all clean check buildPlugin -x traceRequirements + - name: Build and verify plugin distribution + run: ./gradlew --stacktrace --warning-mode=all clean check buildPlugin verifyPlugin -x traceRequirements - name: Create GitHub release run: ./.github/workflows/github_release.sh diff --git a/README.md b/README.md index a87cec8..7a56fbb 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,8 @@ To understand product intent and implementation scope, start with: * [Design](doc/design.md) * [Change Log](doc/changes/changelog.md) -To run the automated checks for the trace action and the project trace itself: +To run the local pre-release checks, including automated tests and IntelliJ +Plugin Verifier compatibility checks: ```sh ./gradlew check verifyPlugin diff --git a/doc/changes/changes_0.8.1.md b/doc/changes/changes_0.8.1.md index 635da68..f612dcc 100644 --- a/doc/changes/changes_0.8.1.md +++ b/doc/changes/changes_0.8.1.md @@ -6,6 +6,8 @@ The plugin description now focuses on the everyday OpenFastTrace workflows in Je The packaged plugin descriptor also carries the project website, `itsallcode.org` vendor metadata, compatibility baseline, and change notes rendered from the active release notes. +The release workflow now verifies the packaged plugin with IntelliJ Plugin Verifier before creating the GitHub release artifact. + ## Bundled OpenFastTrace OpenFastTrace 4.5.0 @@ -13,3 +15,7 @@ OpenFastTrace 4.5.0 ## Documentation * #51: Complete Marketplace-facing plugin metadata + +## Build Maintenance + +* #49: Run plugin verification in the release workflow diff --git a/doc/changesets/49-run-plugin-verification-in-release-workflow.md b/doc/changesets/49-run-plugin-verification-in-release-workflow.md new file mode 100644 index 0000000..a3186a4 --- /dev/null +++ b/doc/changesets/49-run-plugin-verification-in-release-workflow.md @@ -0,0 +1,187 @@ +# GH-49 Run plugin verification in the release workflow + +## Goal + +Ensure that the manually dispatched release workflow verifies the packaged +plugin distribution with IntelliJ Plugin Verifier before it creates a GitHub +release or any future Marketplace publication can reuse that artifact. + +The protected `main` rules already require changes to enter `main` through a +pull request with the configured `build`, SonarCloud, and link-checker status +checks. GH-49 therefore does not replace merge validation. It closes the +remaining release-path gap: the artifact created by `.github/workflows/release.yml` +must not be released unless `verifyPlugin` accepts that same build output. + +## Scope + +In scope: + +* add `verifyPlugin` to the release workflow before the GitHub release step +* keep verifier failures build-breaking for the release workflow +* keep the release script publishing only the distribution archive generated by + the verified Gradle build +* keep existing verifier warnings visible in the GitHub Actions log without + masking new failures +* update developer or release documentation only if the existing local command + is not explicit enough for pre-release verification +* add the release-hardening entry to the active changelog + +Out of scope: + +* changing protected branch rules or required status checks +* changing the normal pull-request build workflow unless implementation reveals + that release verification cannot be kept isolated +* fixing unrelated verifier warnings +* changing the configured IDE compatibility range +* publishing to JetBrains Marketplace +* reworking the full release process +* changing plugin runtime behavior or user-visible OpenFastTrace features + +## Design References + +* [GitHub Issue #49](https://github.com/itsallcode/openfasttrace-intellij-plugin/issues/49) +* [System Requirements](../system_requirements.md) +* [Deployment View](../design/deployment_view.md) +* [Design Decisions](../design/architecture_decisions.md) +* [Quality Requirements](../design/quality_requirements.md) +* [Changeset Guidelines](README.md) +* [README Development Checks](../../README.md#development) +* [JetBrains Publishing Plugins](https://plugins.jetbrains.com/docs/intellij/publishing-plugin.html) +* [JetBrains Plugin Verifier](https://plugins.jetbrains.com/docs/intellij/verifying-plugin-compatibility.html) + +## Strategy + +Treat GH-49 as release workflow hardening and build maintenance. The active +repository ruleset protects `main` with required pull requests, squash merges, +strict required status checks, and no bypass. That means ordinary tests, +coverage, tracing, packaging, SonarCloud analysis, and link checking are already +guarded before a release workflow can run on changed source. + +Keep that separation intact. The release workflow should still refuse +non-`main` refs, build the release distribution from `main`, run `verifyPlugin` +against the resulting plugin distribution, and only then call +`.github/workflows/github_release.sh`. Prefer adding `verifyPlugin` to the +existing Gradle release command or renaming the existing step to make the +verification explicit. + +Do not add broad verifier suppression. Previous changesets record that the +current verifier run can pass while still printing known experimental API +warnings. If the verifier fails during implementation, first distinguish new +release-blocking failures from already documented warnings. Add a narrow, +documented verifier acceptance only if the current tooling requires it to keep +known warnings from hiding real failures. + +The existing build-tool design decision for using the IntelliJ Platform Gradle +Plugin already covers Gradle-based Plugin Verifier integration. The quality +requirements already require plugin-specific CI verification in addition to +ordinary automated tests. No system requirement change is expected because this +does not affect plugin behavior visible to end users. + +## Task List + +- [x] Create and checkout a new Git branch `build/49-run-plugin-verification-in-release-workflow` + +### Requirements And Design + +- [x] Confirm that GH-49 does not require changes to `doc/system_requirements.md` + because it hardens release automation, not plugin runtime behavior or + user-visible OpenFastTrace workflows +- [x] Confirm that the existing architecture decision for the IntelliJ Platform + Gradle Plugin still covers the build-tool choice for invoking IntelliJ + Plugin Verifier through Gradle +- [x] Confirm that `doc/design/quality_requirements.md` already requires + plugin-specific CI verification and does not need semantic changes for + this release-workflow wiring +- [x] Record the active `main` ruleset context in this changeset: PR required, + squash merge only, strict required checks, and no bypass +- [x] No additional documentation-review stop is required because the + implementation does not change system requirements, design decisions, + quality requirements, or branch-rule assumptions + +### Release Workflow + +- [x] Update `.github/workflows/release.yml` so the release job runs + `verifyPlugin` after the plugin distribution is built and before + `.github/workflows/github_release.sh` creates the GitHub release +- [x] Keep `verifyPlugin` in the same release job so any verifier failure stops + release creation through the normal GitHub Actions failure behavior +- [x] Keep `traceRequirements` as a separate release step and keep the duplicate + Gradle trace execution excluded from the later release build command +- [x] Rename the release build step so the workflow visibly states + that it builds and verifies the plugin distribution +- [x] Keep `github_release.sh` publishing the archive from + `build/distributions` that was produced by the verified Gradle build +- [x] Avoid changes to `.github/workflows/build.yml` and protected branch rules + unless a concrete implementation finding shows that release verification + cannot be kept isolated +- [x] Avoid broad verifier warning suppression; no suppression was needed + +### Update Developer Documentation + +- [x] Review the README development command `./gradlew check verifyPlugin` + against GH-49 acceptance criterion 5 +- [x] Update README wording so `./gradlew check verifyPlugin` is explicitly + described as the local pre-release verification command + +### Verification + +- [x] Run `./gradlew --dry-run --stacktrace --warning-mode=all clean check buildPlugin verifyPlugin -x traceRequirements` + and confirm the release Gradle command includes `verifyPlugin` and still + builds the plugin distribution +- [x] Run `./gradlew --warning-mode=all traceRequirements` +- [x] Run `./gradlew --stacktrace --warning-mode=all clean check buildPlugin verifyPlugin -x traceRequirements` +- [x] Confirm `verifyPlugin` runs in the release Gradle command before release + creation and keeps existing non-failing warnings visible in the Gradle + output without adding suppressions +- [x] Inspect `build/distributions` after the release command and confirm the + distribution ZIP expected by `github_release.sh` is present +- [x] Keep path coverage at or above the documented 80 percent threshold through + the `check` lifecycle +- [x] Keep the OpenFastTrace trace clean for the requirement, design, build, and + implementation artifact types in scope +- [x] Keep the dependency policy unchanged; no new runtime, test, or build + dependency is expected +- [ ] Keep the required protected-branch checks green after the pull request: + `build`, SonarCloud Code Analysis, and `linkChecker` +- [ ] Optionally run or inspect a release-workflow dry run if GitHub Actions + supports validating the edited workflow without creating a release + +`./gradlew --dry-run --stacktrace --warning-mode=all clean check buildPlugin verifyPlugin -x traceRequirements` +passes and shows `buildPlugin` before `verifyPlugin` in the Gradle task graph. + +`./gradlew --warning-mode=all traceRequirements` passes. + +`./gradlew --stacktrace --warning-mode=all clean check buildPlugin verifyPlugin -x traceRequirements` +passes. The first sandboxed attempt failed because the Gradle wrapper could not +write its lock file under `~/.gradle` in the restricted filesystem; rerunning +the same command with approval passed. + +The verifier checks `build/distributions/OpenFastTrace-0.8.1.zip` against +`IU-261.25134.95` and `IU-262.7132.23`. Both checks are compatible. The existing +two experimental API usages in `OftHighlightingPass` remain visible in the +verifier output and do not fail the build. + +`build/distributions/OpenFastTrace-0.8.1.zip` is present after the release +Gradle command. + +`git diff --check` passes. + +## Version And Changelog Update + +- [x] Re-check the current project version in `gradle.properties` against the + latest GitHub release before editing release notes +- [x] If the current project version is still unreleased, keep the version and + add GH-49 to that active changelog as build or release maintenance +- [x] No patch version bump is required because `0.8.1` is still unreleased +- [x] Determine the bundled OpenFastTrace library version from the resolved + Gradle dependency metadata +- [x] Keep or add the `## Bundled OpenFastTrace` section in the active changelog + immediately after the release summary and before issue-category sections +- [x] Ensure the changelog issue list contains `#49: Run plugin verification in + the release workflow` +- [x] Update the release date to the implementation date + +Current context at planning time: `gradle.properties` contains `0.8.1`, and the +latest GitHub release is `0.8.0`, published on 2026-06-09. If `0.8.1` is still +unreleased during implementation, GH-49 can be included in `0.8.1` without a +version bump. diff --git a/doc/images/intellij-window-with-plugin.png b/doc/images/intellij-window-with-plugin.png new file mode 100644 index 0000000..5087c4a Binary files /dev/null and b/doc/images/intellij-window-with-plugin.png differ