Merge branch 'master' into hash

.gitignore

@@ -19,4 +19,5 @@ TAGS
 *.sublime-workspace
 tests.iml
 # Auto-copied by sbt-microsites
-docs/src/main/tut/contributing.md
+docs/src/main/tut/contributing.md
+docs/src/main/tut/index.md

CHANGES.md

@@ -22,7 +22,7 @@ as many breaking changes as possible in this release before we lock down the API
  * All `Unapply` enabled methods, e.g. `sequenceU`, `traverseU`, etc. are removed. `Unapply`
    enabled syntax ops are also removed. Please use the partial unification SI-2712 fix
    instead. The easiest way might be this [sbt-plugin](https://github.com/fiadliel/sbt-partial-unification).
- *  `FunctorFilter`, `MonadCombine`, `MonadFilter`, `MonadReader`, `MonadState`, `MonadTrans`, `MonadWriter` and `TraverseFilter` are no longer in `cats`, the functionalities they provided are inherited by the new [cats-mtl](https://github.com/edmundnoble/cats-mtl) project. Please check [here](https://github.com/edmundnoble/cats-mtl#migration-guide) for migration guide.
+ *  `FunctorFilter`, `MonadCombine`, `MonadFilter`, `MonadReader`, `MonadState`, `MonadTrans`, `MonadWriter` and `TraverseFilter` are no longer in `cats`, the functionalities they provided are inherited by the new [cats-mtl](https://github.com/typelevel/cats-mtl) project. Please check [here](https://github.com/typelevel/cats-mtl#migration-guide) for migration guide.
  * `CartesianBuilder` (i.e. `|@|`) syntax is deprecated, use the apply syntax on tuples instead. E.g. `(x |@| y |@| z).map(...)` should be replaced by `(x, y, z).mapN(...)`. If you are getting "`mapN` not found" error message, it could be due to SI-2712, see the 3rd migration item above. 
  * Apply syntax on tuple (e.g. `(x, y, z).map3(...)`)  was moved from `cats.syntax.tuple._` to `cats.syntax.apply._` and renamed to `mapN`, `contramapN` and `imapN` respectively.
  * The creation methods (`left`, `right`, `apply`, `pure`, etc.) in `EitherT` were improved to take less

CONTRIBUTING.md

@@ -1,10 +1,3 @@
----
-layout: page
-title:  "Contributing"
-section: "contributing"
-position: 5
----
-
 # Contributor guide
 
 ## About this document

README.md

@@ -1,4 +1,5 @@
 ## Cats
+![cats image](http://plastic-idolatry.com/erik/cats2.png)
 
 [![Build Status](https://api.travis-ci.org/typelevel/cats.svg)](https://travis-ci.org/typelevel/cats)
 [![Workflow](https://badge.waffle.io/typelevel/cats.svg?label=ready&title=Ready)](https://waffle.io/typelevel/cats)
@@ -9,25 +10,35 @@
 
 ### Overview
 
-Cats is a library which provides abstractions for functional programming in Scala.
-
+Cats is a library which provides abstractions for functional programming in the [Scala programming language](https://scala-lang.org).
 The name is a playful shortening of the word *category*.
 
-![cats image](http://plastic-idolatry.com/erik/cats2.png)
+Scala supports both object-oriented and functional programming, and this is reflected in the hybrid approach of the
+standard library. Cats strives to provide functional programming abstractions that are core, [binary compatible](http://typelevel.org/cats/#binary-compatibility-and-versioning), [modular](http://typelevel.org/cats/motivations#modularity), [approachable](http://typelevel.org/cats/motivations#approachability) and [efficient](http://typelevel.org//cats/motivations#efficiency). A broader goal of Cats is to provide a foundation for an [ecosystem of pure, typeful libraries](https://typelevel.org/cats/#ecosystem) to support functional programming in Scala applications.
 
-#### Why?
+For more detail about Cats' motivations, go [here](http://typelevel.org/cats/motivations).
 
-Scala supports both object-oriented and functional programming, and this is reflected in the hybrid approach of the
-standard library. Cats augments the standard library with tools that further enable functional programming such as
-`Validated`, `Monad`, and `Traverse`. A broader goal of Cats is to provide a foundation for an
-[ecosystem of pure, typeful libraries](https://github.com/typelevel/cats#the-cats-ecosystem).
 
 ### Getting Started
 
 Cats is currently available for Scala 2.10, 2.11 and 2.12, and [Scala.js](http://www.scala-js.org/).
 
-To get started with SBT, simply add the following to your `build.sbt`
-file:
+
+Cats relies on improved type inference via the fix for [SI-2112](https://issues.scala-lang.org/browse/SI-2712), which is not enabled by default. For **Scala 2.11.9 or later** you should add the following to your `build.sbt`:
+
+```scala
+scalacOptions += "-Ypartial-unification"
+
+libraryDependencies += "org.typelevel" %% "cats-core" % "1.0.0-MF"
+```
+
+**Or**, if you need to support older versions of Scala you can use the [sbt-partial-unification](https://github.com/fiadliel/sbt-partial-unification#sbt-partial-unification) plugin which extends support back through **Scala 2.10.6 or later**, to add it, simply add this line to your `plugins.sbt`:
+
+```scala
+addSbtPlugin("org.lyranthe.sbt" % "partial-unification" % "1.1.0")
+```
+
+And then create the cats dependency, by adding the following to your `build.sbt`:
 
 ```scala
 libraryDependencies += "org.typelevel" %% "cats-core" % "1.0.0-MF"
@@ -51,76 +62,59 @@ functionality, you can pick-and-choose from amongst these modules
  * [`cats-mtl`](https://github.com/typelevel/cats-mtl): transformer typeclasses for cats' Monads, Applicatives and Functors.
  * [`alleycats`](https://github.com/non/alleycats): cats instances and classes which are not lawful.
  * [`mouse`](https://github.com/benhutchison/mouse): a small companion to cats that provides convenient syntax (aka extension methods) 
-
 
-Release notes for Cats are available in [CHANGES.md](CHANGES.md).
+
+Release notes for Cats are available in [CHANGES.md](https://github.com/typelevel/cats/blob/master/CHANGES.md).
 
 *Cats is still under active development. While we don't anticipate any
  major redesigns, changes that are neither source nor binary
- compatible are to be expected in upcoming cats releases. We will
- update the minor version of cats accordingly for such changes. Once
- cats 1.0 is released (ETA: Q4 2017), there will be an increased focus
- on making changes in compatible ways.*
-
-#### Enhancing type inference
-
-To use cats you'll need sometimes support for improved type inference. To enable it for any supported Scalac version, use this [sbt plugin](https://github.com/fiadliel/sbt-partial-unification#sbt-partial-unification).
+ compatible are to be expected in upcoming RC1 and 1.0 releases.*
 
-### Documentation
 
-Cats information and documentation is available on the
-[website](http://typelevel.org/cats).
+### <a name="ecosystem" href="#ecosystem"></a>The cats ecosystem
 
-We also have a Scaladoc [index](http://typelevel.org/cats/api/#package).
-
-Finally, we have a list of
-[frequently-asked questions](docs/src/main/tut/faq.md).
-
-Our goal is to have clear and comprehensive documentation. If you
-notice problems, omissions, or errors, please
-[let us know](CONTRIBUTING.md).
-
-### The cats ecosystem
-
-Many projects integrate with cats. By sharing the same set of
-type classes, instances and data types, projects can speak the same "cats
-language", and integrate with each other with ease.
+By sharing the same set of type classes, instances and data types provided by cats, projects can speak the same "cats language", and integrate with each other with ease.
 
 #### General purpose libraries to support pure functional programming
 
- * [Dogs](https://github.com/stew/dogs): pure functional collections and data structures.
+ * [Dogs](https://github.com/stew/dogs): pure functional collections and data structures
+ * [eff](https://github.com/atnos-org/eff): functional effects and effect handlers (alternative to monad transformers)
+ * [Freestyle](https://github.com/47deg/freestyle): pure functional framework for Free and Tagless Final apps & libs
+ * [iota](https://github.com/frees-io/iota): Fast [co]product types with a clean syntax
  * [Kittens](https://github.com/milessabin/kittens): automatic type class derivation for Cats and generic utility functions
- * [eff](https://github.com/atnos-org/eff): functional effects and effect handlers (alternative to monad transformers).
- * [Freestyle](https://github.com/47deg/freestyle): pure functional framework for Free and Tagless Final apps & libs.
  * [mainecoon](https://github.com/kailuowang/mainecoon): Transform and compose tagless final encoded algebras
- * [iota](https://github.com/frees-io/iota): Fast [co]product types with a clean syntax
+ * [Monocle](https://github.com/julien-truffaut/Monocle): an optics library for Scala (and Scala.js) strongly inspired by Haskell Lens.
+ * [newts](https://github.com/julien-truffaut/newts): Defines newtypes compatible with cats type classes
  * [origami](https://github.com/atnos-org/origami): monadic folds
+ * [refined](https://github.com/fthomas/refined): simple refinement types for Scala
 
 #### Libraries with more specific uses
 
- * [Circe](https://github.com/circe/circe): pure functional JSON library.
- * [Fetch](https://github.com/47deg/fetch): efficient data access to heterogeneous data sources.
- * [Frameless](https://github.com/typelevel/frameless): Expressive types for Spark.
- * [FS2](https://github.com/functional-streams-for-scala): compositional, streaming I/O library
- * [doobie](https://github.com/tpolecat/doobie): a pure functional JDBC layer for Scala
- * [Monix](https://github.com/monix/monix): high-performance library for composing asynchronous and event-based programs.
- * [http4s](https://github.com/http4s/http4s): A minimal, idiomatic Scala interface for HTTP
- * [hammock](https://github.com/pepegar/hammock): Purely functional HTTP client
  * [atto](https://github.com/tpolecat/atto): friendly little text parsers
+ * [circe](https://github.com/circe/circe): pure functional JSON library
  * [decline](https://github.com/bkirwi/decline): A composable command-line parser
- * [seals](https://github.com/durban/seals): tools for schema evolution and language-integrated schemata
+ * [doobie](https://github.com/tpolecat/doobie): a pure functional JDBC layer for Scala
+ * [Fetch](https://github.com/47deg/fetch): efficient data access to heterogeneous data sources
+ * [finch](https://github.com/finagle/finch): Scala combinator library for building Finagle HTTP services
+ * [Frameless](https://github.com/typelevel/frameless): Expressive types for Spark
+ * [FS2](https://github.com/functional-streams-for-scala): compositional, streaming I/O library
  * [grafter](https://github.com/zalando/grafter): dependency-injection library using the `Reader` pattern
- * [finch](https://github.com/finagle/finch): Scala combinator library for building Finagle HTTP services 
+ * [hammock](https://github.com/pepegar/hammock): Purely functional HTTP client
+ * [http4s](https://github.com/http4s/http4s): A minimal, idiomatic Scala interface for HTTP
+ * [monadic-html](https://github.com/OlivierBlanvillain/monadic-html): Tiny DOM binding library for Scala.js
+ * [Monix](https://github.com/monix/monix): high-performance library for composing asynchronous and event-based programs
  * [pureconfig](https://github.com/pureconfig/pureconfig): A boilerplate-free library for loading configuration files
-
-
+ * [scanamo](https://github.com/guardian/scanamo): simpler DynamoDB access for Scala
+ * [seals](https://github.com/durban/seals): tools for schema evolution and language-integrated schemata
+
 *Feel free to submit a PR if you want a project you maintain to be added to this list.*
 
+*The full-size [cats logo](https://typelevel.org/cats/img/cats-logo.png) is available for use for Cats related projects, contents, souvenirs, etc.*  
 
 ### How can I contribute to Cats?
 
 We welcome contributions to Cats and would love for you to help build
-Cats. See our [contributor guide](CONTRIBUTING.md) for more
+Cats. See our [contributor guide](https://typelevel.org/cats/contributing.html) for more
 information about how you can get involved.
 
 ### Community
@@ -154,6 +148,33 @@ into larger problems.
 If you are being harassed, please contact one of [us](#maintainers)
 immediately so that we can support you.
 
+### Binary compatibility and versioning
+
+After `1.0.0` release, we [decided](https://github.com/typelevel/cats/issues/1233) 
+to use *MAJOR.MINOR.PATCH* [Semantic Versioning 2.0.0](http://semver.org/)
+going forward, which is different from the *EPOCH.MAJOR.MINOR* scheme common among 
+Java and Scala libraries (including the Scala lang). 
+
+Cats strives to provide a solid and stable foundation for an ecosystem of
+FP libraries. Thus, we treat backward binary compatibility maintenance with a high priority. 
+In semantic versioning, backward breaking change is **ONLY** allowed between *MAJOR* versions.
+We will maintain backward binary compatibility between *PATCH* AND *MINOR* versions.
+For example, when we release cats `1.1.0`, it will be backward binary compatible 
+with the previous `1.0.x` versions. I.E. the new JAR will be a drop-in replacement for 
+the old one. This is critical when your application has a diamond
+dependency on Cats - depending on two or more libraries that all depend on Cats. 
+If one library upgrades to the new `1.1.0` Cats before the other one does, your 
+application still runs thanks to this backward binary compatibility.  
+
+Also worth noting is that according to semantic versioning, 
+*MINOR* version Y (x.Y.z | x > 0) MUST be incremented 
+if new, backwards compatible functionality is introduced to the public API. 
+It MUST be incremented if any public API functionality is marked as deprecated.
+
+Any binary breaking changes will require a *MAJOR* version bump, which we will be very
+cautious about. We will also consider using `organization` and package name for major 
+versioning in the future. But that decision is yet to be made. 
+
 ### Maintainers
 
 The current maintainers (people who can merge pull requests) are:
@@ -163,6 +184,7 @@ The current maintainers (people who can merge pull requests) are:
  * [johnynek](https://github.com/johnynek) P. Oscar Boykin
  * [travisbrown](https://github.com/travisbrown) Travis Brown
  * [adelbertc](https://github.com/adelbertc) Adelbert Chang
+ * [LukaJCB](https://github.com/LukaJCB) Luka Jacobowitz
  * [peterneyens](https://github.com/peterneyens) Peter Neyens
  * [edmundnoble](https://github.com/edmundnoble) Edmund Noble
  * [tpolecat](https://github.com/tpolecat) Rob Norris
@@ -188,4 +210,4 @@ http://opensource.org/licenses/mit-license.php and also in the
 [COPYING](COPYING) file. The design is informed by many other
 projects, in particular [Scalaz](https://github.com/scalaz/scalaz).
 
-Copyright the maintainers, 2015-2016.
+Copyright the maintainers, 2015-2017.

build.sbt

@@ -17,6 +17,8 @@ lazy val scoverageSettings = Seq(
 
 organization in ThisBuild := "org.typelevel"
 
+val CompileTime = config("compile-time").hide
+
 lazy val kernelSettings = Seq(
   // don't warn on value discarding because it's broken on 2.10 with @sp(Unit)
   scalacOptions ++= commonScalacOptions.filter(_ != "-Ywarn-value-discard"),
@@ -36,16 +38,16 @@ lazy val commonSettings = Seq(
     Resolver.sonatypeRepo("snapshots")
   ),
   libraryDependencies ++= Seq(
-    "com.github.mpilquist" %%% "simulacrum" % "0.11.0" % "compile-time",
+    "com.github.mpilquist" %%% "simulacrum" % "0.11.0" % CompileTime,
     "org.typelevel" %%% "machinist" % "0.6.2",
     compilerPlugin("org.scalamacros" %% "paradise" % "2.1.0" cross CrossVersion.patch),
     compilerPlugin("org.spire-math" %% "kind-projector" % "0.9.4")
   ),
   fork in test := true,
   parallelExecution in Test := false,
   scalacOptions in (Compile, doc) := (scalacOptions in (Compile, doc)).value.filter(_ != "-Xfatal-warnings"),
-  ivyConfigurations += config("compile-time").hide,
-  unmanagedClasspath in Compile ++= update.value.select(configurationFilter("compile-time")),
+  ivyConfigurations += CompileTime,
+  unmanagedClasspath in Compile ++= update.value.select(configurationFilter(CompileTime.name)),
   unmanagedSourceDirectories in Test ++= {
     val bd = baseDirectory.value
     if (CrossVersion.partialVersion(scalaVersion.value) exists (_._2 >= 11))
@@ -71,7 +73,6 @@ lazy val commonJsSettings = Seq(
   },
   scalaJSStage in Global := FastOptStage,
   parallelExecution := false,
-  requiresDOM := false,
   jsEnv := new org.scalajs.jsenv.nodejs.NodeJSEnv(),
   // batch mode decreases the amount of memory needed to compile scala.js code
   scalaJSOptimizerOptions := scalaJSOptimizerOptions.value.withBatchMode(isTravisBuild.value),
@@ -131,7 +132,12 @@ lazy val docsMappingsAPIDir = settingKey[String]("Name of subdirectory in site t
 lazy val docSettings = Seq(
   micrositeName := "Cats",
   micrositeDescription := "Lightweight, modular, and extensible library for functional programming",
-  micrositeAuthor := "Typelevel contributors",
+  micrositeAuthor := "Cats contributors",
+  micrositeFooterText := Some(
+    """
+      |<p>© 2017 <a href="https://github.com/typelevel/cats#maintainers">The Cats Maintainers</a></p>
+      |<p style="font-size: 80%; margin-top: 10px">Website built with <a href="https://47deg.github.io/sbt-microsites/">sbt-microsites © 2016 47 Degrees</a></p>
+      |""".stripMargin),
   micrositeHighlightTheme := "atom-one-light",
   micrositeHomepage := "http://typelevel.org/cats/",
   micrositeBaseUrl := "cats",
@@ -140,7 +146,13 @@ lazy val docSettings = Seq(
   micrositeExtraMdFiles := Map(
     file("CONTRIBUTING.md") -> ExtraMdFileConfig(
       "contributing.md",
-      "home"
+      "home",
+       Map("title" -> "Contributing", "section" -> "contributing", "position" -> "50")
+    ),
+    file("README.md") -> ExtraMdFileConfig(
+      "index.md",
+      "home",
+      Map("title" -> "Home", "section" -> "home", "position" -> "0")
     )
   ),
   micrositeGithubRepo := "cats",
@@ -181,7 +193,7 @@ lazy val docs = project
   .settings(noPublishSettings)
   .settings(docSettings)
   .settings(commonJvmSettings)
-  .dependsOn(coreJVM, freeJVM)
+  .dependsOn(coreJVM, freeJVM, kernelLawsJVM, lawsJVM, testkitJVM)
 
 lazy val cats = project.in(file("."))
   .settings(moduleName := "root")
@@ -339,7 +351,12 @@ val binaryCompatibleExceptions = {
     exclude[ReversedMissingMethodProblem]("cats.kernel.instances.FunctionInstances0.catsKernelHashForFunction0"),
     exclude[ReversedMissingMethodProblem]("cats.kernel.instances.EitherInstances0.catsStdHashForEither"),
     exclude[DirectMissingMethodProblem]("cats.kernel.instances.all.package.catsKernelStdPartialOrderForBitSet"),
-    exclude[DirectMissingMethodProblem]("cats.kernel.instances.bitSet.package.catsKernelStdPartialOrderForBitSet")
+    exclude[DirectMissingMethodProblem]("cats.kernel.instances.bitSet.package.catsKernelStdPartialOrderForBitSet"),
+    //todo: remove these once we release 1.0.0-RC1
+    exclude[InheritedNewAbstractMethodProblem]("cats.kernel.instances.QueueInstances.*"),
+    exclude[InheritedNewAbstractMethodProblem]("cats.kernel.instances.QueueInstances1.*"),
+    exclude[InheritedNewAbstractMethodProblem]("cats.kernel.instances.QueueInstances2.*"),
+    exclude[InheritedNewAbstractMethodProblem]("cats.kernel.instances.DurationInstances.*")
   )
 }
 

core/src/main/scala/cats/Alternative.scala

@@ -22,6 +22,10 @@ import simulacrum.typeclass
     (as, bs)
   }
 
+  /** Return ().pure[F] if `condition` is true, `empty` otherwise */
+  def guard(condition: Boolean): F[Unit] =
+    if (condition) pure(()) else empty
+
   override def compose[G[_]: Applicative]: Alternative[λ[α => F[G[α]]]] =
     new ComposedAlternative[F, G] {
       val F = self

core/src/main/scala/cats/functor/Bifunctor.scala → core/src/main/scala/cats/Bifunctor.scala

@@ -1,8 +1,5 @@
 package cats
-package functor
-
 import simulacrum.typeclass
-
 /**
  * A type class of types which give rise to two independent, covariant
  * functors.
@@ -58,7 +55,7 @@ import simulacrum.typeclass
 }
 
 private[cats] trait ComposedBifunctor[F[_, _], G[_, _]]
-    extends Bifunctor[λ[(A, B) => F[G[A, B], G[A, B]]]] {
+  extends Bifunctor[λ[(A, B) => F[G[A, B], G[A, B]]]] {
   def F: Bifunctor[F]
   def G: Bifunctor[G]
 

core/src/main/scala/cats/Bitraverse.scala

@@ -1,6 +1,6 @@
 package cats
 
-import cats.functor.{Bifunctor, ComposedBifunctor}
+
 
 import simulacrum.typeclass
 

core/src/main/scala/cats/Composed.scala

@@ -1,6 +1,5 @@
 package cats
 
-import cats.functor._
 
 private[cats] trait ComposedInvariant[F[_], G[_]] extends Invariant[λ[α => F[G[α]]]] { outer =>
   def F: Invariant[F]

core/src/main/scala/cats/functor/Contravariant.scala → core/src/main/scala/cats/Contravariant.scala

@@ -1,8 +1,5 @@
 package cats
-package functor
-
 import simulacrum.typeclass
-
 /**
  * Must obey the laws defined in cats.laws.ContravariantLaws.
  */