{"id":49542647,"url":"https://github.com/sonofmagic/javachanges","last_synced_at":"2026-05-02T16:01:10.364Z","repository":{"id":352269843,"uuid":"1214422136","full_name":"sonofmagic/javachanges","owner":"sonofmagic","description":"Java Changesets for Maven monorepos and release-plan workflows","archived":false,"fork":false,"pushed_at":"2026-04-28T05:03:16.000Z","size":646,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T05:08:55.047Z","etag":null,"topics":["changesets","cli","github-actions","gitlab-ci","java","maven","monorepo","release-automation"],"latest_commit_sha":null,"homepage":"https://javachanges.icebreaker.top","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sonofmagic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T14:57:25.000Z","updated_at":"2026-04-28T05:03:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sonofmagic/javachanges","commit_stats":null,"previous_names":["sonofmagic/javachanges"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sonofmagic/javachanges","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonofmagic%2Fjavachanges","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonofmagic%2Fjavachanges/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonofmagic%2Fjavachanges/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonofmagic%2Fjavachanges/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sonofmagic","download_url":"https://codeload.github.com/sonofmagic/javachanges/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonofmagic%2Fjavachanges/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32540120,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["changesets","cli","github-actions","gitlab-ci","java","maven","monorepo","release-automation"],"created_at":"2026-05-02T16:00:37.951Z","updated_at":"2026-05-02T16:01:10.355Z","avatar_url":"https://github.com/sonofmagic.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# javachanges\n\n[English](./README.md) | [简体中文](./README.zh-CN.md)\n\n`javachanges` is a small Java CLI that brings a Changesets-like release planning workflow to Maven and Gradle repositories.\n\nDocumentation site: `https://javachanges.icebreaker.top`\n\nIt is designed for repositories that want:\n\n- file-based release intents in `.changesets/*.md`\n- reviewed release plans before version bumps land\n- generated changelog and release notes\n- CI-friendly publish checks and release helpers\n- optional GitHub and GitLab variable sync helpers\n\n## Status\n\nThis repository is the standalone source home for `javachanges`.\n\nThe current codebase focuses on:\n\n- adding and validating changesets\n- generating release plans\n- updating the root Maven `revision` or Gradle `gradle.properties` version\n- generating changelog and release notes\n- preparing Maven settings from environment variables\n- release preflight and publish helpers\n- GitHub and GitLab environment-variable auditing\n- GitHub and GitLab release PR / MR and tag automation helpers\n\n## Quick Start\n\nRequirements:\n\n- Java 8+\n- Maven 3.8+\n- a git repository\n- a Maven repository with a root `pom.xml`, or a Gradle repository with `gradle.properties`\n- either Maven `\u003cmodules\u003e`, Gradle `include(...)` entries in `settings.gradle(.kts)`, or a single root artifact/project\n\nRecommended for target repositories: declare the Maven plugin and run the short local goals:\n\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eio.github.sonofmagic\u003c/groupId\u003e\n  \u003cartifactId\u003ejavachanges\u003c/artifactId\u003e\n  \u003cversion\u003e\u003c!-- latest released version --\u003e\u003c/version\u003e\n\u003c/plugin\u003e\n```\n\nThen inside that repository:\n\n```bash\nmvn javachanges:setup\nmvn javachanges:init -Djavachanges.config=true\nmvn javachanges:next\nmvn javachanges:modules\nmvn javachanges:status\nmvn javachanges:validate\nmvn javachanges:plan -Djavachanges.apply=true\nmvn javachanges:add -Djavachanges.summary=\"add release notes command\" -Djavachanges.release=minor\nmvn javachanges:version\nmvn javachanges:write-settings -Djavachanges.settingsMode=release\nmvn javachanges:doctor-publish\nmvn javachanges:preflight -Djavachanges.tag=v1.2.3\nmvn javachanges:publish -Djavachanges.tag=v1.2.3\nmvn javachanges:manifest-field -Djavachanges.field=releaseVersion -Djavachanges.fresh=true\nmvn javachanges:release-notes -Djavachanges.tag=v1.2.3 -Djavachanges.output=target/release-notes.md\n```\n\nThe plugin defaults `--directory` to the current Maven project's `${project.basedir}`, so if you run it inside the target repository you usually do not need to pass `--directory` explicitly. The generic `run` goal still exists for commands that do not have a dedicated goal yet.\n\nIf you cannot modify the target repository `pom.xml`, or you are using Gradle, use the released CLI from Maven Central instead:\n\n```bash\nmvn -q dependency:copy -Dartifact=io.github.sonofmagic:javachanges:\u003creleased-version\u003e -DoutputDirectory=.javachanges\njava -jar .javachanges/javachanges-\u003creleased-version\u003e.jar --help\n```\n\nOn the current `main` branch, after installing the snapshot locally, you can also run `javachanges` as a Maven plugin:\n\n```bash\n./mvnw -q -DskipTests install\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:setup\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:init -Djavachanges.config=true\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:next\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:modules\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:status\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:validate\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:plan -Djavachanges.apply=true\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:add -Djavachanges.summary=\"add release notes command\" -Djavachanges.release=minor\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:write-settings -Djavachanges.settingsMode=release\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:doctor-publish\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:manifest-field -Djavachanges.field=releaseVersion\nmvn io.github.sonofmagic:javachanges:1.12.0-SNAPSHOT:release-notes -Djavachanges.tag=v1.2.3 -Djavachanges.output=target/release-notes.md\n```\n\nRepository-local shortcuts for working on `javachanges` itself:\n\n```bash\npnpm ci:local\npnpm ci:local:build\npnpm ci:local:docs\npnpm ci:local:release\n./mvnw -B test\n./mvnw -B -Pcoverage -Dmaven.repo.local=.m2/repository test\npnpm snapshot:install\npnpm snapshot:preflight\npnpm snapshot:publish:local\npnpm docs:deploy:local\n```\n\nThese map to the same phases used elsewhere in the docs:\n\n- `ci:local` runs the local CI simulation: Java build checks, docs build, and release automation dry-runs\n- `ci:local:build` mirrors the Java build steps from `.github/workflows/ci.yml`\n- `ci:local:docs` installs docs dependencies and runs the VitePress build\n- `ci:local:release` validates release PR/MR planning, publish readiness, and snapshot publish preflight in dry-run mode only\n- `./mvnw -B test` runs the default test suite with build prerequisite checks\n- `./mvnw -B -Pcoverage -Dmaven.repo.local=.m2/repository test` also generates a JaCoCo HTML report under `target/site/jacoco/`\n- `snapshot:install` installs the current `1.12.0-SNAPSHOT` into local Maven\n- `snapshot:preflight` previews a local snapshot publish with `local.dev.001`\n- `snapshot:publish:local` publishes a unique snapshot through `central-publishing-maven-plugin`\n- `docs:deploy:local` rebuilds `website/dist` and serves it through Wrangler locally\n\nThe snapshot shortcuts pin Maven's local repository to `.m2/repository` inside this repository so local bootstrap does not depend on a writable global `~/.m2`.\n\nSnapshot verification:\n\n- Snapshot repository: `https://central.sonatype.com/repository/maven-snapshots/`\n- Snapshot metadata pattern: `https://central.sonatype.com/repository/maven-snapshots/io/github/sonofmagic/javachanges/\u003cresolved-snapshot-version\u003e/maven-metadata.xml`\n- Snapshot artifact pattern: `https://central.sonatype.com/repository/maven-snapshots/io/github/sonofmagic/javachanges/\u003cresolved-snapshot-version\u003e/javachanges-\u003ctimestamped-version\u003e.jar`\n\nSonatype currently does not provide a working browse UI for hosted snapshots, so the practical verification path is to open `maven-metadata.xml`, open the exact artifact URL, or resolve the dependency from Maven/Gradle.\n\nPublished package:\n\n- Maven Central page: `https://central.sonatype.com/artifact/io.github.sonofmagic/javachanges`\n- CLI jar URL pattern: `https://repo1.maven.org/maven2/io/github/sonofmagic/javachanges/\u003creleased-version\u003e/javachanges-\u003creleased-version\u003e.jar`\n\nReleased CLI examples against a target repository:\n\n```bash\njava -jar .javachanges/javachanges-\u003creleased-version\u003e.jar status --directory /path/to/your/repo\njava -jar .javachanges/javachanges-\u003creleased-version\u003e.jar add --directory /path/to/your/repo\njava -jar .javachanges/javachanges-\u003creleased-version\u003e.jar plan --directory /path/to/your/repo\n```\n\nIf you want to work on this repository itself from source, see [Development Guide](docs/development-guide.md).\n\nFor Maven repositories, see [Maven Usage Guide](docs/maven-guide.md). The short version is: keep the root version in a `\u003crevision\u003e` property, use the Maven plugin for day-to-day commands, and use the released CLI jar when you cannot change the target `pom.xml`.\n\nFor Gradle repositories, see [Gradle Usage Guide](docs/gradle-guide.md). The short version is: keep `version=...-SNAPSHOT` in `gradle.properties`, define projects in `settings.gradle(.kts)`, and run the released CLI jar directly.\n\n## Changeset Format\n\n`javachanges` now defaults to the same core markdown shape used by Node.js Changesets:\n\n```md\n---\n\"javachanges\": minor\n---\n\nAdd GitHub Actions release automation.\n```\n\nMonorepo example:\n\n```md\n---\n\"core\": minor\n\"cli\": patch\n---\n\nImprove CLI parsing and release planning.\n```\n\nHow to read it:\n\n- each frontmatter key is a Maven artifactId or Gradle project name\n- each value is the semver bump for that artifact: `patch`, `minor`, `major`\n- the markdown body is the user-facing summary and notes\n\nDefaults and behavior:\n\n- `javachanges add` writes the official package-map style by default\n- if you use `--modules all`, `javachanges` writes all detected Maven artifactIds or Gradle project names\n- the first non-empty body line becomes the summary shown in `status`, release PRs, changelogs, and release notes\n- changelog sections are grouped by the aggregated release level: `major`, `minor`, `patch`\n\nThe shortest hand-written form for a single-module repository is:\n\n```md\n---\n\"javachanges\": patch\n---\n\nFix Windows path handling in release-notes generation.\n```\n\nCompatibility:\n\n- the old `release` / `modules` / `summary` / `type` frontmatter format is still accepted when reading existing files\n- new files should use the official package-map style above\n\nLegacy format example:\n\n```md\n---\nrelease: minor\ntype: ci\nmodules: javachanges\nsummary: automate javachanges self-release publishing via GitHub Actions\n---\n```\n\nField reference:\n\n- `\"artifactId\"` / `\"projectName\"`\n  Required in the new format.\n  Each frontmatter key is a Maven artifactId or Gradle project name, usually quoted to match official Changesets style.\n  For single-module repositories, this is typically the root artifactId or root project name.\n  For monorepos, add one entry per affected module.\n- `patch` / `minor` / `major`\n  Required value for each artifactId entry.\n  Controls the semver bump contributed by that module.\n  Allowed values: `patch`, `minor`, `major`.\n  Typical guidance:\n  `patch` for backwards-compatible fixes, docs, chores, CI, or small improvements.\n  `minor` for backwards-compatible features.\n  `major` for breaking changes.\n- body\n  Recommended markdown body below the frontmatter.\n  The first non-empty line is reused as the summary.\n  Additional paragraphs or bullets can hold rollout notes, migration details, or context.\n- `type`\n  Legacy optional metadata field, only for backwards compatibility with older `javachanges` files.\n  New files should generally omit it.\n- `release`, `modules`, `summary`\n  Legacy fields from the older `javachanges` format.\n  Still accepted for parsing existing files, but no longer recommended for new changesets.\n\n## Repository Layout\n\n- `src/main/java`: the CLI source code\n- `docs/`: public documentation pages\n- `examples/basic-monorepo/`: a minimal Maven example repository with CI templates and generated release-plan snapshots\n- `examples/basic-gradle-monorepo/`: a minimal Gradle example repository with CI templates and generated release-plan snapshots\n- `website/`: the VitePress site published as static assets with Workers + Wrangler\n- Cloudflare can connect this repository directly through Workers Builds, so GitHub does not need a dedicated docs deploy workflow\n- `env/release.env.example`: a generic env template for release automation\n\n## Commands\n\nHigh-value commands:\n\n- `init`\n- `setup`\n- `add`\n- `next`\n- `modules`\n- `status`\n- `validate`\n- `plan`\n- `manifest-field`\n- `version`\n- `write-settings`\n- `init-gradle-tasks`\n- `init-env`\n- `auth-help`\n- `render-vars`\n- `doctor-local`\n- `doctor-platform`\n- `sync-vars`\n- `audit-vars`\n- `doctor-publish`\n- `preflight`\n- `publish`\n- `gradle-publish`\n- `release-notes`\n- `ensure-gpg-public-key`\n- `release-version-from-tag`\n- `release-module-from-tag`\n- `assert-module`\n- `assert-snapshot`\n- `assert-release-tag`\n- `module-selector-args`\n\nGitHub-specific helpers:\n\n- `github-release-plan`\n- `github-tag-from-plan`\n- `github-release-publish-state`\n- `github-release-from-plan`\n- `init-github-actions`\n\nGitLab-specific helpers:\n\n- `gitlab-release-plan`\n- `gitlab-tag-from-plan`\n- `gitlab-release`\n- `init-gitlab-ci`\n\n## Docs\n\n- [Overview](docs/index.md)\n- [Overview (zh-CN)](docs/index.zh-CN.md)\n- [Getting Started](docs/getting-started.md)\n- [Getting Started (zh-CN)](docs/getting-started.zh-CN.md)\n- [Maven Usage Guide](docs/maven-guide.md)\n- [Maven Usage Guide (zh-CN)](docs/maven-guide.zh-CN.md)\n- [Gradle Usage Guide](docs/gradle-guide.md)\n- [Gradle Usage Guide (zh-CN)](docs/gradle-guide.zh-CN.md)\n- [Examples Guide](docs/examples-guide.md)\n- [Examples Guide (zh-CN)](docs/examples-guide.zh-CN.md)\n- [Command Cookbook](docs/command-cookbook.md)\n- [Command Cookbook (zh-CN)](docs/command-cookbook.zh-CN.md)\n- [Configuration Reference](docs/configuration-reference.md)\n- [Configuration Reference (zh-CN)](docs/configuration-reference.zh-CN.md)\n- [CLI Reference](docs/cli-reference.md)\n- [CLI Reference (zh-CN)](docs/cli-reference.zh-CN.md)\n- [Output Contracts](docs/output-contracts.md)\n- [Output Contracts (zh-CN)](docs/output-contracts.zh-CN.md)\n- [Development Guide](docs/development-guide.md)\n- [Development Guide (zh-CN)](docs/development-guide.zh-CN.md)\n- [Release Plan Manifest](docs/release-plan-manifest.md)\n- [Release Plan Manifest (zh-CN)](docs/release-plan-manifest.zh-CN.md)\n- [Troubleshooting Guide](docs/troubleshooting-guide.md)\n- [Troubleshooting Guide (zh-CN)](docs/troubleshooting-guide.zh-CN.md)\n- [Cloudflare Workers Builds](docs/cloudflare-workers-builds.md)\n- [Cloudflare Workers Builds (zh-CN)](docs/cloudflare-workers-builds.zh-CN.md)\n- [GitHub Actions Release Flow](docs/github-actions-release.md)\n- [GitHub Actions Release Flow (zh-CN)](docs/github-actions-release.zh-CN.md)\n- [GitHub Actions Usage Guide](docs/github-actions-guide.md)\n- [GitHub Actions Usage Guide (zh-CN)](docs/github-actions-guide.zh-CN.md)\n- [GitLab CI/CD Usage Guide](docs/gitlab-ci-guide.md)\n- [GitLab CI/CD Usage Guide (zh-CN)](docs/gitlab-ci-guide.zh-CN.md)\n- [Publish To Maven Central](docs/publish-to-maven-central.md)\n- [Publish To Maven Central (zh-CN)](docs/publish-to-maven-central.zh-CN.md)\n- [Use Cases](docs/use-cases.md)\n- [Use Cases (zh-CN)](docs/use-cases.zh-CN.md)\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonofmagic%2Fjavachanges","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsonofmagic%2Fjavachanges","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonofmagic%2Fjavachanges/lists"}