javachanges Development Guide

English | 简体中文

1. Overview

javachanges is a Java CLI for Maven monorepos and single-module Maven repositories.

This repository is not currently distributed as:

• an npm install package
• a brew install formula
• a ready-made global javachanges executable

Instead, the current workflow is:

• install local prerequisites: JDK + Maven
• clone the source repository
• compile and run the CLI directly with Maven

Note: the repository does not include mvnw, so you need a local Maven installation.

2. Requirements

2.1 Minimum requirements

According to pom.xml, the current project expects:

Item	Requirement
JDK	Java 8+
Maven	3.8+
Git	Required
Target repository	Must have a root pom.xml, and either <modules> or a single root artifact

2.2 Recommended development environment

The repository currently develops and validates against Java 8:

Scenario	Recommendation
Day-to-day development	JDK 8 + Maven 3.9.x
Local default environment	Match the Java 8 compiler target in pom.xml
Command execution	Use a system-installed mvn

Tip: since the repository targets Java 8, using Java 8 locally reduces environment drift.

3. Install local dependencies

3.1 macOS

With Homebrew:

# Install Java 8 (Corretto 8 is recommended)
brew install --cask corretto@8

# Install Maven
brew install maven

Then verify:

java -version
mvn -v

If you want new terminals to default to Java 8:

export JAVA_HOME="/Library/Java/JavaVirtualMachines/amazon-corretto-8.jdk/Contents/Home"
export PATH="$JAVA_HOME/bin:$PATH"

Then reopen the terminal or run:

source ~/.zshrc

3.2 Linux

Examples:

# Debian / Ubuntu
sudo apt install openjdk-8-jdk maven

# Fedora
sudo dnf install java-1.8.0-openjdk-devel maven

3.3 Windows

You can use:

• JDK: Amazon Corretto 8 / Temurin 8 / Oracle JDK 8
• Maven: official binary, Scoop, or Chocolatey

Verify with:

java -version
mvn -v

4. Get the source and build it

4.1 Clone the repository

git clone https://github.com/sonofmagic/javachanges.git
cd javachanges

4.2 Verify the build

Run:

mvn -q test

This mainly does two things:

Action	Purpose
Download dependencies	Prime the local Maven cache
Compile the project	Confirm the source builds cleanly

Note: the repository currently has no visible src/test/java, so mvn test mainly serves as a full Maven build check.

4.3 Install into the local Maven repository (optional)

mvn install

This writes artifacts to ~/.m2/repository, but it does not create a global javachanges command.

5. What “development mode” means here

This is a CLI project, not a web server. There is no typical:

• hot reload dev server
• npm run dev
• long-running background process

For this repository, “development mode” usually means:

1. edit files under src/main/java
2. recompile with Maven
3. run the CLI entrypoint through exec:java
4. inspect command output and iterate

5.2 Most common development command

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

Segment	Meaning
compile	Compile the current source
exec:java	Run the main entrypoint directly
-DskipTests	Skip tests for faster iteration
-Dexec.args="..."	Pass CLI arguments

5.3 Entry class

The current CLI entry class is:

• src/main/java/io/github/sonofmagic/javachanges/JavaChangesCli.java

You can also run or debug this class directly in IntelliJ IDEA or VS Code.

6. Common development commands

6.1 Show status

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

6.2 Add a changeset

mvn -q -DskipTests compile exec:java -Dexec.args="add --directory /path/to/your/repo --summary 'add release notes command' --release minor"

6.3 Generate a release plan

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

6.4 Apply a release plan

mvn -q -DskipTests compile exec:java -Dexec.args="plan --directory /path/to/your/repo --apply true"

6.5 Print help

mvn -q -DskipTests compile exec:java -Dexec.args="help"

High-value commands include:

Command	Purpose
add	Create a changeset
status	Show pending release state
plan	Generate or apply a release plan
write-settings	Generate Maven settings
init-env	Initialize release env templates
render-vars	Render platform variables
doctor-local	Check local environment
doctor-platform	Check platform variables
sync-vars	Sync platform variables
audit-vars	Audit platform variables
preflight	Run pre-publish checks
publish	Assist publishing
release-notes	Generate release notes

7. Recommended local workflow

7.1 Iteration loop

1. Install JDK and Maven
2. Run mvn -q test
3. Prepare a Maven repository for testing
4. Edit src/main/java
5. Validate behavior with mvn -q -DskipTests compile exec:java -Dexec.args="..."
6. Run mvn test or mvn package before finalizing

7.2 Debugging options

Method	Best for
mvn ... exec:java	Closest to real CLI usage
Run JavaChangesCli in an IDE	Breakpoint debugging
mvn package then verify	Packaging validation

8. FAQ

8.1 mvn: command not found

Cause: Maven is not installed or not in PATH.

Fix:

1. install Maven
2. reopen the terminal
3. run mvn -v

8.2 Unable to locate a Java Runtime

Cause: no JDK is installed, or JAVA_HOME / PATH is wrong.

Fix:

1. install a JDK
2. run java -version
3. run mvn -v

8.3 Target repository structure errors

The target repository must have at least:

Requirement	Meaning
Git repository	Must be initialized
Root pom.xml	Must exist
<modules> or a single root artifact	Either is acceptable
<revision>	Required for version calculation
.changesets/	Stores changesets

8.4 Why there is no hot reload

Because this is a Java CLI project, not a long-running frontend or backend service. The normal flow is to rerun commands after editing:

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

9. Summary

You can think of this repository as “the source repository of a Java CLI that is run through Maven.”

Shortest path:

Goal	Command
Install local dependencies	brew install --cask corretto@8 && brew install maven
Verify environment	java -version && mvn -v
Clone the project	git clone https://github.com/sonofmagic/javachanges.git
Initial build	mvn -q test
Enter development mode	mvn -q -DskipTests compile exec:java -Dexec.args="status --directory /path/to/your/repo"

10. References

Resource	Link
Maven install docs	https://maven.apache.org/install.html
Maven run docs	https://maven.apache.org/run.html
Amazon Corretto 8 downloads	https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/downloads-list.html
Amazon Corretto 8 macOS install	https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/macos-install.html
Project overview	README.md
Getting started	getting-started.md