Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

merge wiki contents into README.md and CONTRIBUTING.md #213

Merged
merged 2 commits into from
May 21, 2018
Merged

merge wiki contents into README.md and CONTRIBUTING.md #213

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f3e7f6b
merge wiki contents into README.md and CONTRIBUTING.md
SethTisue May 21, 2018
b788998
Link @experimental
dwijnand May 21, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 110 additions & 4 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,59 @@
# Contributing to Migration Manager

## CLA

If you'd like to contribute to the MiMa project, please sign the [contributor's licensing agreement](http://www.lightbend.com/contribute/cla).

## Modules

MiMa is split into Several modules:

- Core: classes that are used for detection.
- Reporter: reporting classes.
- SBT Plugin: the sbt plugin for usage inside sbt builds.

## Building

Using [sbt][sbt]:

$ sbt compile

[sbt]: http://www.scala-sbt.org/

This will recompile all MiMa's modules.

If you'd like to create distributable jar files for the CLI, run:

$ sbt assembly

This will create `reporter/target/mima-reporter-assembly-....jar` jar file that can be used to launch the command line version of MiMa.


## Functional tests

The directory containing the MiMa Reporter module ('reporter') there is a 'functional-tests' folder that contains several functional tests exercising the system. All tests are executed as part of the build, therefore when running

$ sbt testFunctional

if one (or more) test fails the build is stop and no jar will not be produced.

To add a new functional test to the suite, create a new folder within 'functional-tests' directory with the following structure:

functional-tests
|
| --> <your-new-test-folder> (folder for your new test)
|
|-----> problems.txt (the expected list of reported errors - 1 line per error)
|-----> v1 (folder containing sources @ version 1)
|-----> v2 (folder containing sources @ version 2)

After doing that, `reload` if you are in a `sbt` console session (if that makes no sense to you, it means you are fine and you can run the test as usual).

Tests within the `functional-tests` folder should always pass.

Note: The `problems.txt` is the test oracle. Expected errors are declared using the MiMa's reporting output (i.e., the output of the tool and the expected errors should match perfectly). Admittedly, this coupling is an issue since the testing framework is highly coupled with the tool output used to report errors to the user. We should improve this and make the two independent. Until then, mind that by changing the output of the tool you will likely have to update some of the test oracles (i.e., problems.txt file). When running tests against Scala 2.12 or higher, `problems-2.12.txt` is preferred over `problems.txt` if the former exists.


## General Workflow

This is the process for committing code into master. There are of course exceptions to these rules, for example minor changes to comments and documentation, fixing a broken build etc.
Expand Down Expand Up @@ -58,8 +112,60 @@ Example:

Fix #2731, Fix #2732, Re #2733

## Resources
## Releasing

this section is out of date

see https://github.com/lightbend/migration-manager/issues/165 for a more complete set of steps, though by now they might not be completely up-to-date either?

### Prerequisites

**You are using sbt 0.13**.

Then, make sure that you have:

* push rights to this project,

* credentials to deploy artifacts on both ``oss.sonatype.org`` and ``bintray.com/typesafe/sbt-plugins``. This usually means that in your local ``~/.sbt`` folder you have a ``.sbt`` file (e.g., ``user.sbt``, ``credentials.sbt``) that contains something like the following:
```bash
credentials += Credentials("Sonatype Nexus Repository Manager", "oss.sonatype.org", <username>, <password>)

credentials += Credentials("Bintray API Realm", "api.bintray.com", <username>, <password>)
```

(Make sure you're not using an ancient version of sbt-pgp in `~/.sbt/0.13/plugins`.)

### Preparation

Before starting, make sure that:

* A milestone exists for the release you are about to perform. If it doesn't create one.
* The milestone due date is the day of the release.
* All tickets fixed in the current development cycle are associated to the current milestone.

Now, you are all ready and set to cut a MiMa release!

### Cutting a release

1. Run `clean`. (particularly if you've recently bumped `scalaVersion` - see [#191](https://github.com/typesafehub/migration-manager/issues/191))

2. Create a tag and push it. The name of the tag should follow the format of previous tags. Verify that `show version` in sbt picks up the version number from the tag.

3. Now enter sbt command-line, and type `^publishSigned`

```bash
$ sbt
> ^publishSigned
[info] ... (and after a while, you should start seeing thing like the one below)
[info] published mima-reporter_2.10 to https://oss.sonatype.org/service/local/staging/deploy/maven2/com/typesafe/mima-reporter_2.10/0.1.6/mima-reporter_2.10-0.1.6.jar
[info] ...
[success] Total time: 113 s, completed Sep 24, 2013 11:19:48 AM
```

4. Login on [Sonatype](https://oss.sonatype.org/) and follow [this guide](https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide#SonatypeOSSMavenRepositoryUsageGuide-8a.ReleaseIt) to release the staged MiMa artifacts.

5. Login to [Bintray](https://bintray.com/typesafe/sbt-plugins/sbt-mima-plugin/view) and publish sbt plugin artifacts.

6. Announce the release in the [Announce category of Scala Users](https://users.scala-lang.org/c/announce) and update the version number in this wiki.

* [Contributor License Agreement](http://www.typesafe.com/contribute/cla)
* [Issue Tracker](https://github.com/lightbend/migration-manager/issues?page=1&state=open)
* [User Documentation](https://github.com/lightbend/migration-manager/wiki)
7. You are done!
141 changes: 69 additions & 72 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,97 +1,94 @@
Migration Manager for Scala
===========================
# Migration Manager for Scala

The Migration Manager for Scala (MiMa in short) is a tool for diagnosing binary incompatibilities for Scala libraries.
The Migration Manager for Scala (MiMa in short) is a tool for
diagnosing binary incompatibilities for Scala libraries.

If you don't know how to use MiMa, please [read the user documentation](https://github.com/lightbend/migration-manager/wiki).
## What it is

MiMa's Modules
--------------
The Migration Manager (MiMa in short) can report binary modifications that may
lead the JVM throwing a ``java.lang.LinkageError`` (or one of its subtypes,
like ``AbstractMethodError``) at runtime. Linkage errors are usually the
consequence of modifications in classes/members signature.

MiMa is split into Several modules:
MiMa compares all classfiles of two released libraries and reports all source
of incompatibilities that may lead to a linkage error. MiMa provides you, the
library maintainer, with a tool that can greatly automates and simplifies the
process of ensuring the release-to-release binary compatibility of your
libraries.

- Core: classes that are used for detection.
- Reporter: reporting classes.
- SBT Plugin: the sbt plugin for usage inside sbt builds.
A key aspect of MiMa to be aware of is that it only looks for *syntactic binary
incompatibilities*. The semantic binary incompatibilities (such as adding or
removing a method invocation) are not considered. This is a pragmatic approach
as it is up to you, the library maintainer, to make sure that no semantic
changes have occurred between two binary compatible releases. If a semantic
change occurred, then you should make sure to provide this information as part
of the new release's change list.

Usage
-----
In addition, it is worth mentioning that *binary compatibility does not imply
source compatibility*, i.e., some of the changes that are considered compatible
at the bytecode level may still break a codebase that depends on it.
Interestingly, this is not an issue intrinsic to the Scala language. In the
Java language binary compatibility does not imply source compatibility as well.
MiMa focuses on binary compatibility and currently provides no insight into
source compatibility.

To use MiMa as an sbt plugin, see the [sbt plugin wiki page](https://github.com/lightbend/migration-manager/wiki/Sbt-plugin).
The current version of MiMa provides an aggressive reporting module for finding
all potential binary incompatibilties.

## Usage

Build
-----
The sbt plugin is released for sbt versions 0.13.x and 1.x. To try it, do the following:

Using [sbt][sbt]:
Add the following to your `project/plugins.sbt` file:

$ sbt compile
```
addSbtPlugin("com.typesafe" % "sbt-mima-plugin" % "0.2.0")
```

[sbt]: http://www.scala-sbt.org/
Add the following to your `build.sbt` file:

This will recompile all MiMa's modules.
```
mimaPreviousArtifacts := Set("com.jsuereth" % "scala-arm_2.9.1" % "1.2") // replace with your old artifact id
```

If you'd like to create distributable jar files for the CLI, run:
Run `mimaReportBinaryIssues`. You should see something like the following:

$ sbt assembly
```
[info] Found 4 potential binary incompatibilities
[error] * method rollbackTransactionResource()resource.Resource in object resource.Resource does not have a correspondent in new version
[error] * method now()scala.util.continuations.ControlContext in trait resource.ManagedResourceOperations does not have a correspondent in old version
[error] * abstract method now()scala.util.continuations.ControlContext in interface resource.ManagedResource does not have a correspondent in old version
[error] * method rollbackTransactionResource()resource.Resource in trait resource.MediumPriorityResourceImplicits does not have a correspondent in new version
[error] {file:/home/jsuereth/project/personal/scala-arm/}scala-arm/*:mima-report-binary-issues: Binary compatibility check failed!
[error] Total time: 15 s, completed May 18, 2012 11:32:29 AM
```

This will create `reporter/target/mima-reporter-assembly-....jar` jar file that can be used to launch the command line version of MiMa.
## Advanced Usage (Filtering Binary Incompatibilities)

Sometimes you may want to filter out some binary incompatibility. For instance, because you warn your users to never use a class or method marked with a particular annotation (e.g., [`@experimental`](https://github.com/lightbend/migration-manager/issues/160) - note, this annotation is **not** part of the Scala standard library), you may want to exclude all classes/methods that use such annotation. In MiMa you can do this by _explicitly list each binary incompatibility_ that you want to ignore (unfortunately, it doesn't yet support annotation-based filtering - PR is welcomed! :)).

MiMa Reporter: Functional Tests
-------------------------------
Open your `build.sbt` file, and

The directory containing the MiMa Reporter module ('reporter') there is a 'functional-tests' folder that contains several functional tests exercising the system. All tests are executed as part of the build, therefore when running
1. List the binary incompatibilities you would like to ignore

$ sbt testFunctional
```
val ignoredABIProblems = {
import com.typesafe.tools.mima.core._
import com.typesafe.tools.mima.core.ProblemFilters._
Seq(
exclude[MissingClassProblem]("akka.dispatch.SharingMailbox"),
exclude[IncompatibleMethTypeProblem]("akka.dispatch.DefaultPromise.<<")
)
}
```

if one (or more) test fails the build is stop and no jar will not be produced.
2. Configure MiMa to include the defined binary incompatibility ignores

To add a new functional test to the suite, create a new folder within 'functional-tests' directory with the following structure:
```
mimaPreviousArtifacts := Set("com.jsuereth" % "scala-arm_2.9.1" % "1.2") // replace with your old artifact id
mimaBinaryIssueFilters ++= ignoredABIProblems
```

functional-tests
|
| --> <your-new-test-folder> (folder for your new test)
|
|-----> problems.txt (the expected list of reported errors - 1 line per error)
|-----> v1 (folder containing sources @ version 1)
|-----> v2 (folder containing sources @ version 2)

After doing that, `reload` if you are in a `sbt` console session (if that makes no sense to you, it means you are fine and you can run the test as usual).

Tests within the `functional-tests` folder should always pass.

Note: The `problems.txt` is the test oracle. Expected errors are declared using the MiMa's reporting output (i.e., the output of the tool and the expected errors should match perfectly). Admittedly, this coupling is an issue since the testing framework is highly coupled with the tool output used to report errors to the user. We should improve this and make the two independent. Until then, mind that by changing the output of the tool you will likely have to update some of the test oracles (i.e., problems.txt file). When running tests against Scala 2.12 or higher, `problems-2.12.txt` is preferred over `problems.txt` if the former exists.

FAQ
---
## FAQ

`java.lang.OutOfMemoryError - Java heap space:` If you are experiencing out of memory exception you may need to increase the VM arguments for the initial heap size and the maximum heap size. The default values are `-Xms64m` for for the initial heap size and `-Xmx256m` for the maximum heap size.

Bugs and Feature requests
-------------------------

Use the [GitHub project page][mima-github] for filing new tickets.

[mima-github]: https://github.com/lightbend/migration-manager/issues


Contributing
------------
If you'd like to contribute to the MiMa project, please sign the [contributor's licensing agreement](http://www.lightbend.com/contribute/cla).

License
-------
Copyright 2012-2018 Lightbend, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.