Skip to content

update readme for library name change #328

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

Closed
wants to merge 1 commit into from
Closed

update readme for library name change #328

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
36 changes: 22 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,20 @@
[![Build Status](https://travis-ci.org/scala/scala-collection-compat.svg?branch=master)](https://travis-ci.org/scala/scala-collection-compat)
[![Build Status](https://travis-ci.org/scala/scala-library-compat.svg?branch=master)](https://travis-ci.org/scala/scala-library-compat)

# Scala 2.13 Collection Compatibility Library And Migration Tool

## Compatibility Library
# Scala 2.13 standard library compatibility library and migration tool

This library provides some of the new APIs from Scala 2.13 to Scala 2.11 and 2.12. It can be used to cross-build projects.

To use this library, add the following to your build.sbt:

```
libraryDependencies += "org.scala-lang.modules" %% "scala-collection-compat" % "2.1.4"
libraryDependencies += "org.scala-lang.modules" %% "scala-library-compat" % "3.0.0"
```

Version 2.0.0+ is compatible with Scala 2.13, 2.12, and 2.11.

Note that there are multiple ways to cross-build projects, see https://github.com/scala/collection-strawman/wiki/FAQ#how-do-i-cross-build-my-project-against-scala-212-and-scala-213.

**Note**: Please do not release any artifacts against version 1.0.0, due to [#195](https://github.com/scala/scala-collection-compat/issues/195).
Backwards binary compatibility will be enforced within each major version (i.e. all 3.x.y releases will be binary compatible).

Backwards binary compatibility will be enforced within each major version (i.e. all 1.x.y releases will be binary compatible).
## Scala 2.13: Collections

The 2.13 collections are mostly backwards source-compatible, but there are some exceptions. For example, the `to` method is used with a type parameter in 2.12:

Expand All @@ -37,7 +34,18 @@ The 2.11/2.12 version has the compatibility extensions in this package.

The library also adds backported versions of new collection types, currently `scala.collection.compat.immutable.ArraySeq`. In 2.11/2.12, this type is a new collection implementation. In 2.13, it is an alias for `scala.collection.immutable.ArraySeq`.

## Migration Tool
## Scala 2.13: Other standard library classes

scala-library-compat also provides 2.11 and 2.12 versions of some of the other new APIs in Scala 2.13. At present, that includes:

* `scala.util.chaining`
* `scala.util.Using`
* `scala.annotation.nowarn`
* does nothing on 2.11 and 2.12 (except allow crossbuilding)

Contributions that expand this list are welcome.

## Migration tool

The migration rules use scalafix. Please see the [official installation instruction](https://scalacenter.github.io/scalafix/docs/users/installation.html) and, in particular, check that your full Scala version is supported (ex 2.12.11).

Expand All @@ -52,7 +60,7 @@ The `Collection213Upgrade` rewrite upgrades to the 2.13 collections without the

```scala
// build.sbt
scalafixDependencies in ThisBuild += "org.scala-lang.modules" %% "scala-collection-migrations" % "2.1.4"
scalafixDependencies in ThisBuild += "org.scala-lang.modules" %% "scala-collection-migrations" % "3.0.0"
addCompilerPlugin(scalafixSemanticdb)
scalacOptions ++= List("-Yrangepos", "-P:semanticdb:synthetics:on")
```
Expand All @@ -67,12 +75,12 @@ scalacOptions ++= List("-Yrangepos", "-P:semanticdb:synthetics:on")

The `Collection213CrossCompat` rewrite upgrades to the 2.13 collections with the ability to compile the code-base with 2.12 or later. This rewrite is suitable for libraries that are cross-published for multiple Scala versions.

To cross-build for 2.12 and 2.11, the rewrite rule introduces a dependency on the scala-collection-compat module, which provides the syntax of 2.13 on 2.12 and 2.11. This enables you to write your library using the latest 2.13 collections API while still supporting users on an older Scala version.
To cross-build for 2.12 and 2.11, the rewrite rule introduces a dependency on the scala-library-compat module, which provides the syntax of 2.13 on 2.12 and 2.11. This enables you to write your library using the latest 2.13 collections API while still supporting users on an older Scala version.

```scala
// build.sbt
scalafixDependencies in ThisBuild += "org.scala-lang.modules" %% "scala-collection-migrations" % "2.1.4"
libraryDependencies += "org.scala-lang.modules" %% "scala-collection-compat" % "2.1.4"
scalafixDependencies in ThisBuild += "org.scala-lang.modules" %% "scala-collection-migrations" % "3.0.0"
libraryDependencies += "org.scala-lang.modules" %% "scala-library-compat" % "3.0.0"
addCompilerPlugin(scalafixSemanticdb)
scalacOptions ++= List("-Yrangepos", "-P:semanticdb:synthetics:on")
```
Expand Down