Getting Started

0. Quick flow

Loading diagram...

1. Recommended: use the Maven plugin inside the target repository

Published coordinates:

• GroupId: io.github.sonofmagic
• ArtifactId: javachanges
• Current release: 1.12.2
• Maven Central page: https://central.sonatype.com/artifact/io.github.sonofmagic/javachanges/overview
• CLI jar URL: https://repo1.maven.org/maven2/io/github/sonofmagic/javachanges/1.12.2/javachanges-1.12.2.jar

Add the plugin to the target repository pom.xml:

<plugin>
  <groupId>io.github.sonofmagic</groupId>
  <artifactId>javachanges</artifactId>
  <version>1.12.2</version>
</plugin>

Then inside that repository, use the shortest local form:

mvn javachanges:status
mvn javachanges:plan -Djavachanges.apply=true
mvn javachanges:add -Djavachanges.summary="add release notes command" -Djavachanges.release=minor
mvn javachanges:manifest-field -Djavachanges.field=releaseVersion -Djavachanges.fresh=true

Notes:

• this is the recommended day-to-day usage for target repositories
• the plugin defaults --directory to the current Maven project's ${project.basedir}
• the generic run goal still exists for commands that do not have a dedicated goal yet

For the complete Maven workflow, see Maven Usage Guide.

2. Use the released CLI for Gradle

Gradle repositories should call the CLI jar directly.

Minimum Gradle shape:

your-gradle-repo/
├── .changesets/
├── CHANGELOG.md
├── build.gradle.kts
├── gradle.properties
└── settings.gradle.kts

gradle.properties:

version=1.0.0-SNAPSHOT

settings.gradle.kts:

rootProject.name = "your-gradle-repo"
include(":core", ":api")

Download and run:

mvn -q dependency:copy -Dartifact=io.github.sonofmagic:javachanges:1.12.2 -DoutputDirectory=.javachanges
java -jar .javachanges/javachanges-1.12.2.jar status --directory .
java -jar .javachanges/javachanges-1.12.2.jar add --directory . --summary "add release notes command" --release minor --modules core
java -jar .javachanges/javachanges-1.12.2.jar plan --directory . --apply true

For the complete Gradle workflow, see Gradle Usage Guide.

3. Alternative: use the released CLI for temporary Maven usage

Download the released jar:

mvn -q dependency:copy -Dartifact=io.github.sonofmagic:javachanges:1.12.2 -DoutputDirectory=.javachanges

Run the CLI help:

java -jar .javachanges/javachanges-1.12.2.jar --help

Run it against a target repository:

java -jar .javachanges/javachanges-1.12.2.jar status --directory /path/to/repo
java -jar .javachanges/javachanges-1.12.2.jar add --directory /path/to/repo --summary "add release notes command" --release minor
java -jar .javachanges/javachanges-1.12.2.jar plan --directory /path/to/repo

Notes:

• prefer the Maven plugin for Maven repositories because it keeps commands short and auto-detects the current project directory
• use the released CLI for Gradle repositories or for temporary usage against Maven repositories where you cannot add the plugin yet

4. Working on the current main branch

mvn -q -DskipTests install
mvn io.github.sonofmagic:javachanges:1.12.2-SNAPSHOT:status
mvn io.github.sonofmagic:javachanges:1.12.2-SNAPSHOT:plan -Djavachanges.apply=true
mvn io.github.sonofmagic:javachanges:1.12.2-SNAPSHOT:add -Djavachanges.summary="add release notes command" -Djavachanges.release=minor
mvn io.github.sonofmagic:javachanges:1.12.2-SNAPSHOT:manifest-field -Djavachanges.field=releaseVersion

Notes:

• dedicated goals now exist for common local, setup, GitHub, GitLab, publish, and CI helper commands, including init, setup, add, next, modules, status, validate, plan, manifest-field, init-gradle-tasks, init-env, auth-help, render-vars, doctor-local, doctor-platform, sync-vars, audit-vars, write-settings, publish, gradle-publish, release-notes, ensure-gpg-public-key, release-version-from-tag, release-module-from-tag, assert-module, assert-snapshot, assert-release-tag, module-selector-args, github-release-plan, github-tag-from-plan, github-release-publish-state, github-release-from-plan, gitlab-release-plan, gitlab-tag-from-plan, gitlab-release, init-github-actions, and init-gitlab-ci
• javachanges:run is still available with -Djavachanges.args="..."

5. Prepare a target repository

Your target repository should have:

• git initialized
• a root pom.xml with a <revision> property, or a Gradle gradle.properties with version or revision
• a CHANGELOG.md file, or let javachanges create/update it during plan application
• either Maven <modules>, Gradle include(...) entries in settings.gradle(.kts), or a single root artifact/project

Initialize the changeset directory and optional release workflow config:

mvn javachanges:init -Djavachanges.config=true

The command creates .changesets/README.md with starter examples, writes .changesets/config.jsonc when requested, and prints the next commands to run. Run mvn javachanges:modules when you need the exact module names; its output includes add examples using the detected modules. Use mvn javachanges:init -Djavachanges.force=true to refresh an older generated README while preserving custom content by default.

6. Create a changeset

Monorepo example:

mvn javachanges:add -Djavachanges.summary="add release notes command" -Djavachanges.release=minor -Djavachanges.modules=core

Gradle CLI example:

java -jar .javachanges/javachanges-1.12.2.jar add --directory . --summary "add release notes command" --release minor --modules core

Single-module example:

mvn javachanges:add -Djavachanges.summary="add release notes command" -Djavachanges.release=minor

This writes a markdown file into .changesets/.

If you want repository-level release branch conventions, also add .changesets/config.jsonc:

{
  // Default branch that receives reviewed release changesets.
  "baseBranch": "main",

  // Default branch name used by release-plan automation.
  "releaseBranch": "changeset-release/main",

  // Dedicated branch used for publishing snapshots.
  "snapshotBranch": "snapshot"
}

Shortest hand-written format:

---
"your-artifact-id": patch
---

Fix release-notes rendering.

Monorepo example:

---
"core": minor
"cli": patch
---

Improve CLI parsing and release planning.

Notes:

• javachanges add writes this official Changesets-style package map by default
• after writing a changeset, javachanges add prints the status and next commands for the same repository
• it also echoes the resolved release level and affected packages so you can catch module mistakes before applying the plan
• the first non-empty body line becomes the summary used by status, changelogs, and release notes
• legacy release / modules / summary frontmatter is still read for compatibility, but new files should use the package-map form
• changelog sections are grouped by the aggregated release level: major, minor, patch

7. Inspect the plan

mvn javachanges:plan

The dry run prints the exact apply command to use after you review the plan.

Gradle CLI:

java -jar .javachanges/javachanges-1.12.2.jar plan --directory .

8. Apply the plan

mvn javachanges:plan -Djavachanges.apply=true

Gradle CLI:

java -jar .javachanges/javachanges-1.12.2.jar plan --directory . --apply true

That updates:

• the root Maven revision or Gradle gradle.properties version
• CHANGELOG.md
• .changesets/release-plan.json
• .changesets/release-plan.md

After applying the plan, javachanges prints the git status, git add, git commit, and javachanges next commands for the same repository. When changesets are pending, javachanges next also shows GitHub and GitLab release-plan automation commands.

9. Running from source during development

If you are working on the javachanges repository itself, use the source-driven development flow instead:

mvn -q test
mvn -q -DskipTests compile exec:java -Dexec.args="status --directory /path/to/your/repo"

For the full development workflow, see Development Guide.