Merge branch 'master' into add-reducible-docs

.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

.travis.yml

@@ -12,15 +12,15 @@ git:
 scala:
   - 2.10.6
   - 2.11.11
-  - 2.12.2
+  - 2.12.3
 
 jdk:
   - oraclejdk7
   - oraclejdk8
 
 matrix:
   exclude:
-  - scala: 2.12.2
+  - scala: 2.12.3
     jdk: oraclejdk7
   - scala: 2.10.6
     jdk: oraclejdk8

AUTHORS.md

@@ -33,6 +33,7 @@ possible:
  * Arya Irani
  * Ash Pook
  * Aλ
+ * Ben Fradet
  * Ben Hutchison
  * Benjamin Thuillier
  * Binh Nguyen
@@ -53,7 +54,9 @@ possible:
  * David Allsopp
  * David Gregory
  * Denis Mikhaylov
+ * Denis
  * Derek Wickern
+ * Diego Esteban Alonso Blas
  * Earl St Sauver
  * Edmund Noble
  * Eric Torreborre
@@ -62,28 +65,38 @@ possible:
  * Eugene Burmako
  * Eugene Yokota
  * Fabian Schmitthenner
+ * Fabio Labella
  * Feynman Liang
  * Frank S. Thomas
  * Giulio De Luise
+ * Greg Pfeil
  * Guillaume Massé
  * Hamish Dickson
  * Ian McIntosh
  * ImLiar
  * Israel Pérez González
+ * Itamar Ravid
  * Jan-Hendrik Zab
  * Jean-Rémi Desjardins
+ * Jens
  * Jisoo Park
+ * João Ferreira
+ * John Sullivan
  * Jon Hanson
  * Jose Emilio Labra Gayo
+ * Joseph Abrahamson
  * Josh Marcus
  * Juan Pedro Moreno
  * Julien Richard-Foy
  * Julien Truffaut
  * Kailuo Wang
  * Kenji Yoshida
+ * Leandro Bolivar
+ * Lars Hupel
  * Long Cao
  * Luis Angel Vicente Sanchez
  * Luis Sanchez
+ * LukaJCB
  * Luke Wyman
  * Madder
  * Marc Siegel
@@ -98,19 +111,23 @@ possible:
  * Michael Pilquist
  * Mike Curry
  * Miles Sabin
+ * n4to4
  * Olivier Blanvillain
  * Olli Helenius
  * Owen Parry
  * P. Oscar Boykin
+ * Paolo G. Giarrusso
  * Pascal Voitot
  * Paul Phillips
  * Pavkin Vladimir
  * Pepe García
  * Pere Villega
  * Peter Neyens
+ * Peter Perhac
  * Philip Wills
  * Rafa Paradela
  * Raúl Raja Martínez
+ * RawToast
  * Richard Miller
  * Rintcius Blok
  * Rob Norris
@@ -120,21 +137,24 @@ possible:
  * Ryan Case
  * Sam Ritchie
  * Sarunas Valaskevicius
+ * Shohei Kamimori
  * Shunsuke Otani
  * Simeon H. K. Fitch
  * Sinisa Louc
  * Stephen Carman
  * Stephen Judkins
  * Stew O'Connor
  * Sumedh Mungee
+ * Takayuki Sakai
  * Taylor Brown
  * Tom Switzer
  * Tomas Mikula
  * Travis Brown
+ * Vladimir Samoylov
  * Wedens
  * Xavier Fernández Salas
  * Yosef Fertel
- * yilinwei
+ * Yilin Wei
  * Zach Abbott
  * zainab-ali
 

CONTRIBUTING.md

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

README.md

@@ -1,26 +1,23 @@
 ## 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)
 [![Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/typelevel/cats)
 [![codecov.io](http://codecov.io/github/typelevel/cats/coverage.svg?branch=master)](http://codecov.io/github/typelevel/cats?branch=master)
-[![Latest version](https://index.scala-lang.org/typelevel/cats/cats-core/latest.svg?color=orange)](https://index.scala-lang.org/typelevel/cats/cats-core)
+[![Latest version](https://index.scala-lang.org/typelevel/cats/cats-core/latest.svg?color=orange&v=1)](https://index.scala-lang.org/typelevel/cats/cats-core)
 [![Scala.js](http://scala-js.org/assets/badges/scalajs-0.6.14.svg)](http://scala-js.org)
 
 ### 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](http://typelevel.org/projects/).
 
 ### Getting Started
 
@@ -30,51 +27,84 @@ To get started with SBT, simply add the following to your `build.sbt`
 file:
 
 ```scala
-libraryDependencies += "org.typelevel" %% "cats" % "0.9.0"
+libraryDependencies += "org.typelevel" %% "cats-core" % "1.0.0-MF"
 ```
 
-This will pull in all of Cats' modules. If you only require some
+This will pull in the cats-core module. If you require some other
 functionality, you can pick-and-choose from amongst these modules
-(used in place of `"cats"`):
+(used in place of `"cats-core"`):
 
  * `cats-macros`: Macros used by Cats syntax (*required*).
  * `cats-kernel`: Small set of basic type classes (*required*).
  * `cats-core`: Most core type classes and functionality (*required*).
  * `cats-laws`: Laws for testing type class instances.
  * `cats-free`: Free structures such as the free monad, and supporting type classes.
+ * `cats-testkit`: lib for writing tests for type class instances using laws.
+
+ There are several other cats modules that are in separate repos so that they can 
+ maintain independent release cycles. 
+
+ * [`cats-effect`](https://github.com/typelevel/cats-effect): standard `IO` type together with `Sync`, `Async` and `Effect` type classes 
+ * [`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) 
+
+#### Enhancing type inference
 
-Release notes for Cats are available in [CHANGES.md](CHANGES.md).
+ 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).
+
+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.*
+ compatible are to be expected in upcoming RC1 and 1.0 releases.*
 
-#### 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).
+### <a name="ecosystem" href="#ecosystem"></a>The cats ecosystem
 
-### Documentation
+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.
 
-Cats information and documentation is available on the
-[website](http://typelevel.org/cats).
+#### General purpose libraries to support pure functional programming
 
-We also have a Scaladoc [index](http://typelevel.org/cats/api/#package).
+ * [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
+ * [mainecoon](https://github.com/kailuowang/mainecoon): Transform and compose tagless final encoded algebras
+ * [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
 
-Finally, we have a list of
-[frequently-asked questions](docs/src/main/tut/faq.md).
+#### Libraries with more specific uses
 
-Our goal is to have clear and comprehensive documentation. If you
-notice problems, omissions, or errors, please
-[let us know](CONTRIBUTING.md).
+ * [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
+ * [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
+ * [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
-information about how you can get involed.
+Cats. See our [contributor guide](https://typelevel.org/cats/contributing.html) for more
+information about how you can get involved.
 
 ### Community
 
@@ -107,6 +137,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 maintainence 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:
@@ -116,6 +173,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
@@ -133,19 +191,6 @@ sign-offs to merge PRs (and for large or contentious issues we may
 wait for more). For typos or other small fixes to documentation we
 relax this to a single sign-off.
 
-### Related Projects
-
-There are many projects that integrate with Cats:
-
- * [Circe](https://github.com/circe/circe): pure functional JSON library.
- * [Dogs](https://github.com/stew/dogs): pure functional collections and data structures.
- * [Fetch](https://github.com/47deg/fetch): efficient data access to heterogeneous data sources.
- * [Frameless](https://github.com/adelbertc/frameless): Expressive types for Spark.
- * [Freestyle](https://github.com/47deg/freestyle): pure functional framework for Free and Tagless Final apps & libs.
- * [FS2](https://github.com/functional-streams-for-scala): compositional, streaming I/O library
- * [Kittens](https://github.com/milessabin/kittens): automatically derived type class instances.
- * [Monix](https://github.com/monixio/monix): high-performance library for composing asynchronous and event-based programs.
- * [eff](https://github.com/atnos-org/eff): functional effects and effect handlers (alternative to monad transformers).
 
 ### Copyright and License
 
@@ -154,4 +199,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.