{"id":47281672,"url":"https://github.com/alien-tools/roseau","last_synced_at":"2026-04-18T10:14:38.751Z","repository":{"id":175337299,"uuid":"648949016","full_name":"alien-tools/roseau","owner":"alien-tools","description":"Fast and accurate API breaking change and compatibility analysis of Java libraries.","archived":false,"fork":false,"pushed_at":"2026-03-27T13:25:35.000Z","size":18368,"stargazers_count":30,"open_issues_count":1,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-03-27T19:32:21.269Z","etag":null,"topics":["api","backward-compatibility","breaking-changes","diff","java"],"latest_commit_sha":null,"homepage":"https://alien-tools.github.io/roseau/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alien-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","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":"2023-06-03T09:50:57.000Z","updated_at":"2026-03-27T07:27:38.000Z","dependencies_parsed_at":"2024-02-28T15:45:09.055Z","dependency_job_id":"57059541-6b8c-436c-a2e4-41980a21d340","html_url":"https://github.com/alien-tools/roseau","commit_stats":null,"previous_names":["labri-progress/roseau","alien-tools/roseau"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/alien-tools/roseau","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Froseau","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Froseau/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Froseau/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Froseau/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alien-tools","download_url":"https://codeload.github.com/alien-tools/roseau/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Froseau/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31964775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["api","backward-compatibility","breaking-changes","diff","java"],"created_at":"2026-03-16T01:23:57.405Z","updated_at":"2026-04-18T10:14:38.734Z","avatar_url":"https://github.com/alien-tools.png","language":"Java","readme":"# Roseau: Breaking Change Analysis for Java Libraries\n\nRoseau (/ʁozo/) is a **fast** and **accurate** tool for detecting breaking changes between library versions, similar to tools like [japicmp](https://github.com/siom79/japicmp/) or [Revapi](https://github.com/revapi/revapi/).\nWhether you're a library maintainer or upgrading dependencies in your projects, Roseau helps ensure backward compatibility across versions.\nRoseau analyzes both JAR files and source code, is highly configurable, and includes a dedicated Maven plug-in.\n\nThe official user documentation is available at [https://alien-tools.github.io/roseau/](https://alien-tools.github.io/roseau/).\n\n## Key Features\n\n  - Detects both binary-level and source-level breaking changes\n  - Accurate and customizable definition of the API surface (using visibilities, modules, annotations, naming conventions, etc.) \n  - Indifferently analyzes JAR files (using [ASM](https://asm.ow2.io/)) or Java source code (using [JDT](https://github.com/eclipse-jdt/eclipse.jdt.core))\n  - Excellent accuracy and performance\n  - Supports Java up to version 25 (including records, sealed types, modules, etc.)\n  - Outputs reports in CSV, HTML, JSON, and Markdown formats\n  - Highly configurable, CLI-first, and scriptable\n  - Maven plug-in\n\nLike other JAR-based tools, Roseau integrates smoothly into CI pipelines and can analyze artifacts from remote repositories such as Maven Central.\nUnlike others, Roseau can also analyze source code directly, making it ideal for checking commits, pull requests, or local changes in an IDE, as well as libraries hosted on platforms like GitHub for which compiled JARs are not readily available.\n\n## In a nutshell\n\n  1. Roseau infers the exact API of each version of the library to analyze\n  2. It performs side-by-side comparison of the two APIs to detect any breaking changes\n\nRoseau builds lightweight, technology-agnostic API models that list all the exported symbols in a library—including types, methods, and fields—along with their properties. These models can be easily serialized and stored as JSON for further analysis or archival.\nRoseau relies on either [JDT](https://github.com/eclipse-jdt/eclipse.jdt.core) to extract API models from source code, and on [ASM](https://asm.ow2.io/) to extract API models from bytecode.\n\n\nThe breaking change detection algorithm is efficient, agnostic of the underlying parsing technology, and is [extensively tested](core/src/test/java/io/github/alien/roseau/diff).\nThe list of source-level and binary-level breaking changes considered in Roseau is specified [here](core/src/main/java/io/github/alien/roseau/diff/changes/BreakingChangeKind.java) and matches the [Java Language Specification](https://docs.oracle.com/javase/specs/).\n\n## Usage\n\n### As a standalone CLI tool\n\nDownload the latest stable version of the CLI JAR from the [releases page](https://github.com/alien-tools/roseau/releases) or build the latest version locally (Java 25 required): \n\n```bash\n$ git clone https://github.com/alien-tools/roseau.git\n$ cd roseau \u0026\u0026 ./mvnw package -DskipTests\n$ alias roseau='java -jar $PWD/cli/target/roseau-\u003cversion\u003e.jar --help' \n```\n\nIdentify breaking changes between two versions, passed as local JARs or source trees, or fetched remotely:\n\n```\n$ roseau --diff --v1 /path/to/v1.jar --v2 /path/to/v2.jar\nBreaking changes found: 3 (2 binary-breaking, 2 source-breaking)\n✗ com.pkg.A TYPE_REMOVED\n  ✗ binary-breaking ✗ source-breaking\n  → com/pkg/A.java:4\n⚠ com.pkg.B.f FIELD_NOW_STATIC\n  ✗ binary-breaking ✓ source-compatible\n  → com/pkg/B.java:18\n★ com.pkg.C TYPE_NEW_ABSTRACT_METHOD [toOverride()]\n  ✓ binary-compatible ✗ source-breaking\n  → com/pkg/C.java:210\n$ roseau --diff --v1 com.example:lib:1.0.0 --v2 /path/to/v2/src/main/java\n[...]\n```\n\nRoseau supports different modes, output formats, and options:\n\n```\n$ roseau --help\nUsage: roseau [-hVv] [--binary-only] [--fail-on-bc] [--plain] [--source-only]\n              [--api-json=\u003cpath\u003e] [--classpath=\u003cpath\u003e[,\u003cpath\u003e...]]\n              [--config=\u003cpath\u003e] [--ignored=\u003cpath\u003e] [--pom=\u003cpath\u003e] [--v1=\u003cpath\u003e]\n              [--v1-classpath=\u003cpath\u003e[,\u003cpath\u003e...]] [--v1-pom=\u003cpath\u003e]\n              [--v2=\u003cpath\u003e] [--v2-classpath=\u003cpath\u003e[,\u003cpath\u003e...]]\n              [--v2-pom=\u003cpath\u003e] [--report=\u003cformat=path\u003e]... (--api | --diff)\n      --api               Serialize the API model of --v1; see --api-json\n      --diff              Compute breaking changes between versions --v1 and --v2\n      --v1=\u003cpath|coordinates\u003e First version of the library: a JAR file, source directory (e.g., src/main/java), or Maven coordinates (e.g., com.example:lib:1.0.0)\n      --v2=\u003cpath|coordinates\u003e Second version of the library: a JAR file, source directory (e.g., src/main/java), or Maven coordinates (e.g., com.example:lib:2.0.0)\n      --api-json=\u003cpath\u003e   Where to serialize the Json API model of --v1 in --api mode\n      --report=\u003cformat=path\u003e Write a breaking changes report in the given format to the given path; repeatable (formats: CLI, CSV, HTML, JSON, MD)\n      --classpath=\u003cpath\u003e[,\u003cpath\u003e...] A colon-separated list of JARs to include in the classpath (Windows: semi-colon), shared by --v1 and --v2\n      --pom=\u003cpath\u003e        A pom.xml file to extract the classpath from, shared by --v1 and --v2\n      --v1-classpath=\u003cpath\u003e[,\u003cpath\u003e...] A --classpath for --v1\n      --v2-classpath=\u003cpath\u003e[,\u003cpath\u003e...] A --classpath for --v2\n      --v1-pom=\u003cpath\u003e     A --pom for --v1\n      --v2-pom=\u003cpath\u003e     A --pom for --v2\n      --binary-only       Only report binary-breaking changes\n      --source-only       Only report source-breaking changes\n      --ignored=\u003cpath\u003e    Do not report the breaking changes listed in the given CSV file; this CSV file shares the same structure as a CSV report\n      --config=\u003cpath\u003e     A roseau.yaml config file; CLI options take precedence over these options\n      --fail-on-bc        Return with exit code 1 if breaking changes are detected\n      --plain             Disable ANSI colors, output plain text\n  -v, --verbose           Increase verbosity (-v, -vv).\n  -h, --help              Show this help message and exit.\n  -V, --version           Print version information and exit.\n```\n\n### As a Java library\n\nThe main programmatic entry points live in `Roseau`. In most cases, you configure two `Library` instances, build their APIs, and diff them:\n\n```java\nLibrary v1 = Library.of(Path.of(\"/path/to/library-v1.jar\"));\nLibrary v2 = Library.builder()\n  .location(Path.of(\"/path/to/library-v2.jar\"))\n  .classpath(List.of(Path.of(\"/path/to/dependency.jar\")))\n  .pom(Path.of(\"/path/to/pom.xml\"))\n  .build();\n\nAPI apiV1 = Roseau.buildAPI(v1);\nAPI apiV2 = Roseau.buildAPI(v2);\nRoseauReport report = Roseau.diff(apiV1, apiV2);\nreport.getBreakingChanges().forEach(System.out::println);\n```\n\n### As a Maven plug-in\n\nRoseau also provides a Maven plug-in that compares the current artifact against a baseline during the `verify` phase.\nThe minimal setup is to bind the `check` goal and provide a baseline:\n\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eio.github.alien-tools\u003c/groupId\u003e\n  \u003cartifactId\u003eroseau-maven-plugin\u003c/artifactId\u003e\n  \u003cversion\u003e${roseau.version}\u003c/version\u003e\n  \u003cexecutions\u003e\n    \u003cexecution\u003e\n      \u003cgoals\u003e\n        \u003cgoal\u003echeck\u003c/goal\u003e\n      \u003c/goals\u003e\n    \u003c/execution\u003e\n  \u003c/executions\u003e\n  \u003cconfiguration\u003e\n    \u003c!-- Compare against a baseline JAR --\u003e\n    \u003cbaselineJar\u003e${project.basedir}/old.jar\u003c/baselineJar\u003e\n    \u003c!-- Compare against a previous version --\u003e\n    \u003cbaselineDependency\u003e\n      \u003cgroupId\u003ecom.group\u003c/groupId\u003e\n      \u003cartifactId\u003emy-artifact\u003c/artifactId\u003e\n      \u003cversion\u003e1.0.1\u003c/version\u003e\n    \u003c/baselineDependency\u003e\n    \u003cfailOnIncompatibility\u003etrue\u003c/failOnIncompatibility\u003e\n  \u003c/configuration\u003e\n\u003c/plugin\u003e\n```\n\n## Configuration\nRoseau accepts a YAML configuration file supplied using the `--config` option. If an option is specified both on the CLI and in the configuration file, the CLI option takes precedence. Example:\n\n```yaml\ncommon:\n  classpath:\n    pom: /path/to/pom.xml\n    jars: [ /path/to/dependency.jar ]\nv1:\n  apiReport: ./reports/v1.json\nv2:\n  apiReport: ./reports/v2.json\ndiff:\n  ignore: ignored-breaking-changes.csv\n  binaryOnly: true\nreports:\n  - file: ./reports/guava.html\n    format: HTML\n  - file: ./reports/guava.csv\n    format: CSV\n```\n\n### Ignoring breaking changes on specific types and symbols\nRoseau can be configured to ignore breaking changes on symbols matching a given regular expression or annotated with a specific annotation:\n\n```yaml\ncommon:\n  excludes:\n    names: [ com\\.google\\.common\\..* ]\n    annotations:\n      - name: com.google.common.annotations.Beta\n      - name: org.apiguardian.api.API\n        args: { status: org.apiguardian.api.API$Status.INTERNAL }\n```\n\n### Ignoring specific breaking changes\nBreaking changes are sometimes necessary and intended. To avoid reporting the same breaking changes over and over against a given baseline, Roseau can be configured to ignore/accept specific breaking changes and stop reporting them using a dedicated CSV file supplied using the `--ignored` option:\n\n```csv\ntype;symbol;kind\npkg.T;pkg.T.m();EXECUTABLE_REMOVED\n```\n\n## Citing Roseau\nIf you use Roseau for academic purposes, please cite: [Roseau: Fast, Accurate, Source-based Breaking Change Analysis in Java](https://hal.science/hal-05176866/document). Corentin Latappy, Thomas Degueule, Jean-Rémy Falleri, Romain Robbes, Lina Ochoa. In _IEEE International Conference on Software Maintenance and Evolution_ (ICSME 2025).\n\n```bibtex\n@inproceedings{roseau,\n    author    = {Corentin Latappy and Thomas Degueule and Jean-Rémy Falleri and Romain Robbes and Lina Ochoa},\n    title     = {{Roseau}: Fast, Accurate, Source-based Breaking Change Analysis in {Java}},\n    booktitle = {{IEEE} International Conference on Software Maintenance and Evolution, {ICSME} 2025, Auckland, New Zealand, September 7-12, 2025},\n    pages     = {517--528},\n    doi       = {10.1109/ICSME64153.2025.00053},\n    year      = {2025}\n}\n```\n\n## License\nThis repository—and all its content—is licensed under the [MIT License](https://choosealicense.com/licenses/mit/).  („• ‿ •„) \n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falien-tools%2Froseau","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falien-tools%2Froseau","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falien-tools%2Froseau/lists"}