Skip to content

development-guide.md

Latest commit

 

History

History
420 lines (288 loc) · 11.7 KB

development-guide.md

File metadata and controls

420 lines (288 loc) · 11.7 KB
Raw
description Set up a local Java and Maven environment, run javachanges from source, and validate Maven or Gradle target repositories.

javachanges Development Guide

1. Overview

javachanges is a Java CLI for Maven and Gradle 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 + Git
  • clone the source repository
  • compile and run the CLI directly with the Maven Wrapper

Note: the repository includes Maven Wrapper scripts, so most source-repository commands should use ./mvnw instead of a system Maven.

2. Requirements

2.1 Minimum requirements

According to pom.xml, the current project expects:

Item Requirement
JDK Java 8+
Maven Wrapper-provided 3.9.15, or system Maven 3.8+
Git Required
Target repository Maven root pom.xml, or Gradle gradle.properties plus Gradle settings/build files

2.2 Recommended development environment

The repository currently develops and validates against Java 8:

Scenario Recommendation
Day-to-day development JDK 8 + the repository Maven Wrapper
Local default environment Match the Java 8 compiler target in pom.xml
Command execution Use ./mvnw from the repository root

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

# Maven is provided by ./mvnw in this repository

Then verify:

java -version
./mvnw -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
./mvnw -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:

./mvnw -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 now includes CLI-focused unit tests, so ./mvnw test validates both compilation and command behavior.

4.3 Simulate CI locally

Use the repository-local CI helper when you want to check the same broad paths before pushing:

pnpm ci:local

Focused tasks are available when you only need one part of the pipeline:

pnpm ci:local:build
pnpm ci:local:docs
pnpm ci:local:release

The tasks map to local-safe checks:

Task What it validates
ci:local:build Maven verify, the Central publish profile with GPG skipped, and status from source
ci:local:docs pnpm install --frozen-lockfile and the VitePress docs build
ci:local:release GitHub/GitLab release-plan dry-runs, snapshot and release doctor-publish, plus snapshot and release preflight / publish JSON dry-runs

The release task never passes --execute true. It does not push branches, open PRs/MRs, create tags, create releases, or deploy artifacts. It seeds placeholder Maven release and snapshot repository variables so the local preflight can validate command rendering without requiring real credentials.

The helper pins Maven to .m2/repository inside this checkout, so the local simulation does not depend on a writable global ~/.m2.

4.4 Install into the local Maven repository (optional)

./mvnw 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, or install the snapshot and use Maven plugin goals
  4. inspect command output and iterate

5.2 Most common development command

./mvnw -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 Fastest plugin-style loop on the current branch

If you want to validate the developer-facing plugin UX itself, first install the current snapshot locally:

./mvnw -q -DskipTests install

Equivalent repository shortcut:

pnpm snapshot:install

Then run the dedicated plugin goals:

mvn io.github.sonofmagic:javachanges:__JAVACHANGES_CURRENT_SNAPSHOT_VERSION__:status
mvn io.github.sonofmagic:javachanges:__JAVACHANGES_CURRENT_SNAPSHOT_VERSION__:plan -Djavachanges.apply=true
mvn io.github.sonofmagic:javachanges:__JAVACHANGES_CURRENT_SNAPSHOT_VERSION__:add -Djavachanges.summary="add release notes command" -Djavachanges.release=minor

5.4 Entry class

The current CLI entry class is:

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

5.5 Local snapshot and docs deployment shortcuts

This repository also ships small local shortcuts so you do not need to keep retyping the longer commands:

pnpm snapshot:install
pnpm snapshot:preflight
pnpm snapshot:publish:local
pnpm docs:deploy:local

Use them like this:

Command Purpose
pnpm snapshot:install Install the current __JAVACHANGES_CURRENT_SNAPSHOT_VERSION__ into the repository-local .m2/repository
pnpm snapshot:preflight Run preflight --snapshot against the current repository with a local build stamp and the repository-local Maven cache
pnpm snapshot:publish:local Publish a unique snapshot revision from this repository through central-publishing-maven-plugin
pnpm docs:deploy:local Rebuild website/dist and serve it locally through Wrangler

6. Common development commands

6.1 Show status

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

6.2 Add a changeset

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

That command now writes an official Changesets-style file, for example:

```md
---
"your-artifact-id": minor
---

add release notes command
```

6.3 Generate a release plan

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

6.4 Apply a release plan

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

6.5 Print help

./mvnw -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
ensure-gpg-public-key Publish and verify the current signing public key on supported keyservers
release-notes Generate release notes

7. Recommended local workflow

7.1 Iteration loop

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

7.2 Debugging options

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

8. FAQ

8.1 ./mvnw: Permission denied

Cause: the Maven Wrapper script is not executable after checkout.

Fix:

  1. run chmod +x ./mvnw
  2. rerun ./mvnw -v
  3. commit the executable bit if your Git client removed it

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 ./mvnw -v

8.3 Target repository structure errors

The target repository must have at least:

Requirement Meaning
Git repository Must be initialized
Maven version model root pom.xml with <revision>
Gradle version model gradle.properties with version or revision
Module model Maven <modules>, Gradle include(...), or a single root artifact/project
.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:

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

8.5 Can I install javachanges as a global command today?

Not from this source repository directly.

Current supported workflows are:

  • run from source with ./mvnw ... exec:java
  • build the jar with Maven and run java -jar ...
  • consume a published jar from Maven Central in CI after a release exists

8.6 What is the safest way to test release behavior?

Use this order:

  1. status
  2. plan
  3. plan --apply true in a disposable test repository
  4. preflight
  5. publish without --execute true

That lets you inspect the release flow before any real deployment happens.

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
Verify environment java -version && ./mvnw -v
Clone the project git clone https://github.com/sonofmagic/javachanges.git
Initial build ./mvnw -q test
Enter development mode ./mvnw -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
Troubleshooting troubleshooting-guide.md