{"id":26075996,"url":"https://github.com/lightbend-labs/mima","last_synced_at":"2025-05-15T06:02:18.773Z","repository":{"id":3385209,"uuid":"4433540","full_name":"lightbend-labs/mima","owner":"lightbend-labs","description":"A tool for catching binary incompatibility in Scala","archived":false,"fork":false,"pushed_at":"2025-03-17T20:18:45.000Z","size":2444,"stargazers_count":469,"open_issues_count":32,"forks_count":72,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-13T10:58:24.104Z","etag":null,"topics":["compatibility-testing","sbt-plugin","scala","supported"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"watson-developer-cloud/concept-insights-nodejs","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lightbend-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2012-05-24T14:08:57.000Z","updated_at":"2025-03-25T12:13:52.000Z","dependencies_parsed_at":"2023-09-22T17:56:08.680Z","dependency_job_id":"223d3f36-cc65-4d18-9a4d-02548fab808c","html_url":"https://github.com/lightbend-labs/mima","commit_stats":{"total_commits":951,"total_committers":49,"mean_commits":"19.408163265306122","dds":0.6025236593059937,"last_synced_commit":"56cca477bacf2bc1ce3915e8197ead08a00a7ea3"},"previous_names":["typesafehub/migration-manager","lightbend/migration-manager","lightbend-labs/mima","lightbend/mima"],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightbend-labs%2Fmima","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightbend-labs%2Fmima/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightbend-labs%2Fmima/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightbend-labs%2Fmima/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lightbend-labs","download_url":"https://codeload.github.com/lightbend-labs/mima/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254283336,"owners_count":22045140,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["compatibility-testing","sbt-plugin","scala","supported"],"created_at":"2025-03-09T01:41:35.639Z","updated_at":"2025-05-15T06:02:18.710Z","avatar_url":"https://github.com/lightbend-labs.png","language":"Scala","funding_links":[],"categories":["Table of Contents"],"sub_categories":["Sbt plugins"],"readme":"# MiMa\n\nMiMa (for \"Migration Manager\") is a tool for identifying [binary incompatibilities][] in Scala libraries.\n\n[binary incompatibilities]: https://docs.scala-lang.org/overviews/core/binary-compatibility-for-library-authors.html\n\nIt's pronounced _MEE-ma_.\n\n## What it is?\n\nMiMa can report binary modifications that may\ncause the JVM to throw a `java.lang.LinkageError` (or one of its subtypes,\nlike `AbstractMethodError`) at runtime. Linkage errors are usually the\nconsequence of modifications in classes/members signature.\n\nMiMa compares all classfiles of two released libraries and reports all source\nof incompatibilities that may lead to a linkage error. MiMa provides you, the\nlibrary maintainer, with a tool that can greatly automate and simplify the\nprocess of ensuring the release-to-release binary compatibility of your\nlibraries.\n\nA key aspect of MiMa to be aware of is that it only looks for *syntactic binary\nincompatibilities*. The semantic binary incompatibilities (such as adding or\nremoving a method invocation) are not considered. This is a pragmatic approach\nas it is up to you, the library maintainer, to make sure that no semantic\nchanges have occurred between two binary compatible releases. If a semantic\nchange occurred, then you should make sure to provide this information as part\nof the new release's change list.\n\nIn addition, it is worth mentioning that *binary compatibility does not imply\nsource compatibility*, i.e., some of the changes that are considered compatible\nat the bytecode level may still break a codebase that depends on it.\nInterestingly, this is not an issue intrinsic to the Scala language. In the\nJava language binary compatibility does not imply source compatibility as well.\nMiMa focuses on binary compatibility and currently provides no insight into\nsource compatibility.\n\n### See also: TASTy-MiMa\n\nFor Scala 3, in addition to binary compatible, TASTy compatibility becomes\nincreasingly important. Another tool,\n[TASTy-MiMa](https://github.com/scalacenter/tasty-mima), is designed to\nautomatically check TASTy compatibility in much the same way that MiMa checks\nbinary compatibility.\n\nKeep in mind that TASTy-MiMa is still young, as of early 2023. It is likely to\ncontain bugs.\n\n## Usage\n\n### SBT\n\nMiMa's sbt plugin supports sbt 1.x only.  (Use v0.3.0 for sbt 0.13.x.)\n\nTo use it add the following to your `project/plugins.sbt` file:\n\n```\naddSbtPlugin(\"com.typesafe\" % \"sbt-mima-plugin\" % \"\u003cversion\u003e\")\n```\n\nAdd the following to your `build.sbt` file:\n\n```\nmimaPreviousArtifacts := Set(\"com.example\" %% \"my-library\" % \"\u003cversion\u003e\")\n```\n\nand run `mimaReportBinaryIssues` to see something like the following:\n\n```\n[info] Found 4 potential binary incompatibilities\n[error]  * method rollbackTransactionResource()resource.Resource in object resource.Resource does not have a   correspondent in new version\n[error]  * method now()scala.util.continuations.ControlContext in trait resource.ManagedResourceOperations does not    have a correspondent in old version\n[error]  * abstract method now()scala.util.continuations.ControlContext in interface resource.ManagedResource does not have a correspondent in old version\n[error]  * method rollbackTransactionResource()resource.Resource in trait resource.MediumPriorityResourceImplicits does not have a correspondent in new version\n[error] {file:/home/jsuereth/project/personal/scala-arm/}scala-arm/*:mima-report-binary-issues: Binary compatibility check failed!\n[error] Total time: 15 s, completed May 18, 2012 11:32:29 AM\n```\n\n### Mill\n\nA MiMa plugin for Mill is maintained at [lolgab/mill-mima](https://github.com/lolgab/mill-mima).\n\nTo use it add the following to your `build.sc`:\n\n```scala\nimport $ivy.`com.github.lolgab::mill-mima::x.y.z`\nimport com.github.lolgab.mill.mima._\n```\n\nPlease check [this page](https://github.com/lolgab/mill-mima) for further information.\n\n## Filtering binary incompatibilities\n\nWhen MiMa reports a binary incompatibility that you consider acceptable, such as a change in an internal package,\nyou need to use the `mimaBinaryIssueFilters` setting to filter it out and get `mimaReportBinaryIssues` to\npass, like so:\n\n```scala\nimport com.typesafe.tools.mima.core._\n\nmimaBinaryIssueFilters ++= Seq(\n  ProblemFilters.exclude[MissingClassProblem](\"com.example.mylibrary.internal.Foo\"),\n)\n```\n\nYou may also use wildcards in the package and/or the top `Problem` parent type for such situations:\n\n```scala\nmimaBinaryIssueFilters ++= Seq(\n  ProblemFilters.exclude[Problem](\"com.example.mylibrary.internal.*\"),\n)\n```\n\n### IncompatibleSignatureProblem\n\nMost MiMa checks (`DirectMissingMethod`, `IncompatibleResultType`,\n`IncompatibleMethType`, etc) are against the \"method descriptor\", which\nis the \"raw\" type signature, without any information about generic parameters.\n\nThe `IncompatibleSignature` check compares the `Signature`, which includes the\nfull signature including generic parameters. This can catch real\nincompatibilities, but also sometimes triggers for a change in generics that\nwould not in fact cause problems at run time. Notably, it will warn when\nupdating your project to scala 2.12.9+ or 2.13.1+,\nsee [this issue](https://github.com/lightbend-labs/mima/issues/423) for details.\n\nYou can opt-in to this check by setting:\n\n```scala\nimport com.typesafe.tools.mima.plugin.MimaKeys._\n\nThisBuild / mimaReportSignatureProblems := true\n```\n\n### Annotation-based exclusions\n\nThe `mimaExcludeAnnotations` setting can be used to tell MiMa to\nignore classes, objects, and methods that have a particular\nannotation.  Such an annotation might typically have \"experimental\" or\n\"internal\" in the name.\n\nThe setting is a `Seq[String]` containing fully qualified annotation\nnames.\n\nExample:\n\n```scala\nmimaExcludeAnnotations += \"scala.annotation.experimental\"\n```\n\nCaveat: `mimaExcludeAnnotations` is only implemented on Scala 3.\n\n## Setting different mimaPreviousArtifacts\n\nFrom time to time you may need to set `mimaPreviousArtifacts` according to some conditions.  For\ninstance, if you have already ported your project to Scala 2.13 and set it up for cross-building to Scala 2.13,\nbut still haven't cut a release, you may want to define `mimaPreviousArtifacts` according to the Scala version,\nwith something like:\n\n```scala\nmimaPreviousArtifacts := {\n  if (CrossVersion.partialVersion(scalaVersion.value) == Some((2, 13)))\n    Set.empty\n  else\n    Set(\"com.example\" %% \"my-library\" % \"1.2.3\")\n}\n```\n\nor perhaps using some of sbt 1.2's new API:\n\n```scala\nimport sbt.librarymanagement.{ SemanticSelector, VersionNumber }\n\nmimaPreviousArtifacts := {\n  if (VersionNumber(scalaVersion.value).matchesSemVer(SemanticSelector(\"\u003e=2.13\")))\n    Set.empty\n  else\n    Set(\"com.example\" %% \"my-library\" % \"1.2.3\")\n}\n```\n\n## Make mimaReportBinaryIssues not fail\n\nThe setting `mimaFailOnNoPrevious` defaults to `true` and will make\n`mimaReportBinaryIssues` fail if `mimaPreviousArtifacts` hasn't been set.\n\nTo make `mimaReportBinaryIssues` not fail you may want to do one of the following:\n\n* set `mimaPreviousArtifacts` on all the projects that should be checking their binary compatibility\n* avoid calling `mimaPreviousArtifacts` when binary compatibility checking isn't needed\n* set `mimaFailOnNoPrevious := false` on specific projects that want to opt-out (alternatively `disablePlugins(MimaPlugin)`)\n* set `ThisBuild / mimaFailOnNoPrevious := false`, which disables it build-wide, effectively reverting back to the previous behaviour\n\n## Setting mimaPreviousArtifacts when name contains a \".\"\n\nTo refer to the project name in `mimaPreviousArtifacts`, use `moduleName` rather\nthan `name`, like\n\n```scala\nmimaPreviousArtifacts := Set(organization.value %% moduleName.value % \"0.1.0\")\n```\n\nUnlike `name`, `moduleName` escapes characters like `.`, and is the name\nactually used by `publish` and `publishLocal` to publish your project. It's\nalso the value your users should use when adding your project to their\ndependencies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightbend-labs%2Fmima","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flightbend-labs%2Fmima","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightbend-labs%2Fmima/lists"}