---
name: release
description: Release a new version of the DevoxxGenie IntelliJ plugin — prompt for the target version, bump it in the build files, write a curated CHANGELOG.md entry and plugin.xml change-notes from the git/PR history since the last tag, build to verify, then commit, tag, and publish a matching GitHub release. Use this whenever the user wants to cut, ship, publish, or tag a new plugin release, bump the version for a release, or asks to "release vX.Y.Z" / "do a release" / "make a new version".
---

# Release a new DevoxxGenie plugin version

This skill cuts a complete plugin release: version bump → curated changelog → plugin
change-notes → build → commit → tag → GitHub release. The goal is a release whose
CHANGELOG.md, plugin.xml change-notes, and GitHub release body all tell the same story,
written from the actual work done — not a raw dump of PR titles.

The release commit lands on the current default branch (`master`), matching how prior
releases were cut here. Do **not** create a feature branch for a release.

## Step 1 — Ask for the target version

Never assume the next version. Show the current version and ask the user what to release.

```bash
grep -E '^version\s*=' build.gradle.kts | head -n1   # e.g. version = "1.7.4"
```

Offer patch / minor / major as a guide (e.g. current `1.7.4` → patch `1.7.5`, minor
`1.8.0`, major `2.0.0`) but let the user state the exact number. Use it verbatim as
`X.Y.Z` (tags are `vX.Y.Z`).

## Step 2 — Gather the history since the last release

Find the previous tag, then read what actually changed. You need the *substance* of each
change, so look at PR titles **and** bodies/commits, not just subject lines.

```bash
git describe --tags --abbrev=0                 # previous tag, e.g. v1.7.4
git log <prev-tag>..HEAD --oneline             # commits to summarise
gh pr list --state merged --base master --limit 30 \
  --json number,title,author,mergedAt,body     # PR detail + authors
```

Group changes into the sections the CHANGELOG already uses, by conventional-commit prefix:

| Prefix                          | CHANGELOG section |
|---------------------------------|-------------------|
| `feat` / `add`                  | Added             |
| `fix`                           | Fixed             |
| `refactor` / `build` / `perf` / `style` / `chore` (non-dep) | Changed |
| `docs`                          | Documentation     |
| `test`                          | Tests             |
| `chore(deps)` / `bump` / `upgrade` | Dependencies   |

Collect the unique PR authors for a **Contributors** section (`@login`).

Write **descriptive** entries: explain what changed and why it matters for a user or
maintainer, drawing on the PR body/diff — not just the raw commit subject. Keep the
`feat(scope):` / `fix(scope):` lead so entries scan consistently, and append issue/PR/task
references like `(#1097)` or `(task-229, #1093)`. Omit empty sections.

## Step 3 — Bump the version

- `build.gradle.kts`: update the top-level `version = "X.Y.Z"` line (around line 18).
- `src/main/resources/application.properties` is **auto-regenerated by the build** from
  the Gradle project version — do not hand-edit it; Step 6's build updates it.
- `plugin.xml` has **no** `<version>` tag (it's injected by the Gradle IntelliJ plugin), so
  only its change-notes need editing — see Step 5.

## Step 4 — Write the CHANGELOG.md entry

Insert a new section at the **top** of `CHANGELOG.md`, directly under the `# Changelog`
header and above the previous version. Match the existing house style exactly:

```markdown
## vX.Y.Z - YYYY-MM-DD

### Added
- feat(tips): rotating tip line under the prompt placeholder, fetched from a 24h-cached
  tips.json with a built-in fallback list (#1099)

### Fixed
- fix(scope): concise but complete description of the fix and its user-visible effect (#NNNN)

### Changed
- refactor(scope): what was restructured and why it's cleaner (#NNNN)

### Dependencies
- chore: upgrade <lib> A.B.C → X.Y.Z

### Contributors
- @stephanj
```

Use today's date (the current date is available in your context). Keep entries information-
dense; a single fix can warrant a long sentence if the behaviour change is subtle (see the
v1.7.4 credentials entry for the level of detail that's welcome).

## Step 5 — Update plugin.xml change-notes

The Marketplace change-notes are a **condensed** view — the user-relevant highlights, one
concise `<LI>` each. Insert a new block immediately after `<change-notes><![CDATA[`, above
the existing `<h2>` for the prior version:

```html
        <h2>vX.Y.Z</h2>
        <UL>
                    <LI>feat(tips): rotating tip line under the prompt input, fetched from a cached tips.json (#1099)</LI>
                    <LI>fix(scope): short user-facing summary (#NNNN)</LI>
                </UL>
```

Skip internal-only churn (test-only, pure-refactor, doc) here unless it matters to users.
Keep the indentation consistent with the surrounding blocks.

## Step 6 — Build to verify

The project requires **JDK 21** (JDK 25 breaks the Gradle build). Set `JAVA_HOME` first:

```bash
export JAVA_HOME=/Users/stephan/Library/Java/JavaVirtualMachines/azul-21.0.5/Contents/Home
./gradlew buildPlugin
```

This regenerates `application.properties` with the new version and produces
`build/distributions/DevoxxGenie-X.Y.Z.zip`. Confirm the zip name matches the new version
before continuing — a mismatch means the version bump didn't take.

## Step 7 — Commit, tag, and push (confirm first)

Pushing and tagging are hard to undo and are outward-facing, so **show the user the staged
diff and the planned tag, and get an explicit go-ahead** before running this step.

```bash
git add build.gradle.kts src/main/resources/application.properties \
        src/main/resources/META-INF/plugin.xml CHANGELOG.md
git commit -m "chore: bump version to vX.Y.Z"
git tag -a "vX.Y.Z" -m "Release vX.Y.Z"
git push origin HEAD
git push origin "vX.Y.Z"
```

## Step 8 — Create the GitHub release

The release body is the CHANGELOG section for this version. Prior releases bold the lead
clause of detailed entries (e.g. `- **fix(credentials): …** — …`) for scanability; apply
that lightly to the heaviest entries. Attach the built zip as the release asset.

Write the body to a temp file (avoids shell-escaping issues), then:

```bash
gh release create "vX.Y.Z" \
  --title "vX.Y.Z" \
  --notes-file /tmp/release-notes-X.Y.Z.md \
  build/distributions/DevoxxGenie-X.Y.Z.zip
```

Finish by printing the release URL `gh` returns so the user can review it.

## Notes

- This skill stops at the GitHub release. Publishing to the JetBrains Marketplace is a
  separate, explicit step (`PUBLISH_TOKEN=… ./gradlew publishPlugin`) — only do it if the
  user asks.
- If the working tree has unrelated uncommitted changes, surface that before staging so the
  release commit doesn't sweep them in.