Update readme

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,24 @@
+<!--
+
+** Please read the guidelines below. **
+
+GitHub issues are reserved for bug reports and feature requests.
+The best place to ask general questions or ask for community support is
+[on our Discourse](https://discourse.snowplowanalytics.com/).
+
+-->
+
+**Library version**:
+
+**Expected behavior**:
+
+**Actual behavior**:
+
+**Steps to reproduce**:
+
+Please try to be as detailed as possible so that we can reproduce and fix the issue
+as quickly as possible.
+
+ 1.
+ 2.
+

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+<!--
+Thank you for contributing to the Scala Maxmind IpLookups library!
+
+You'll find a small checklist below which should help speed up the
+review processs:
+
+- [ ] Have you signed the [contributor license agreement](https://github.com/snowplow/snowplow/wiki/CLA)?
+- [ ] Have you read the [contributing guide](https://github.com/snowplow/scala-maxmind-iplookups/blob/develop/CONTRIBUTING.md)?
+- [ ] Have you added the appropriate unit tests?
+- [ ] Have you run the tests through `sbt test`?
+- [ ] Is your pull request against the `develop` branch?
+-->

.gitignore

@@ -1,17 +1 @@
-*.class
-*.log
-
-# sbt specific
-dist/*
-target/
-lib_managed/
-src_managed/
-project/boot/
-project/plugins/project/
-
-# Scala-IDE specific
-.scala_dependencies
-
-# Vagrant
-.vagrant
-
+target/

.scalafmt.conf

@@ -0,0 +1,30 @@
+style = defaultWithAlign
+maxColumn = 100
+
+docstrings = JavaDoc
+optIn.breakChainOnFirstMethodDot = true
+spaces.afterKeywordBeforeParen = true
+continuationIndent.defnSite = 2
+continuationIndent.callSite = 2
+importSelectors = noBinPack
+
+newlines {
+  sometimesBeforeColonInMethodReturnType = false
+}
+
+align {
+  arrowEnumeratorGenerator = false
+  ifWhileOpenParen = false
+  openParenCallSite = false
+  openParenDefnSite = false
+}
+
+rewrite {
+  rules = [
+    AsciiSortImports,
+    RedundantBraces,
+    RedundantParens,
+    PreferCurlyFors
+  ]
+  redundantBraces.maxLines = 1
+}

.travis.yml

@@ -1,18 +1,20 @@
 language: scala
 scala:
 - 2.11.12
-- 2.12.5
+- 2.12.6
 jdk:
 - oraclejdk8
-cript:
-- sbt test
+script:
+- sbt coverage test coverageReport
 deploy:
   skip_cleanup: true
   provider: script
   script: "./.travis/deploy.sh $TRAVIS_TAG"
   on:
-    condition: '"${TRAVIS_SCALA_VERSION}" == "2.12.5"'
+    condition: '"${TRAVIS_SCALA_VERSION}" == "2.12.6"'
     tags: true
+after_success:
+- bash <(curl -s https://codecov.io/bash)
 env:
   global:
   - secure: S3rLmHxmFxGS5G7XgaGck8Wi6QnIlFPaJMO5t6BDg8ggrsTseEB0CJPxBRHy+Xrg6J7N3AjmhOyz+ed3Z4rPHTxdF+20c6sGGvgTZCs6ngM7m+cqcJ7CczrEs0ZBJ9q5nUhBwb4nCYSqZ1UcE2JxZeKkfjhwYEFkRgZ0BL6f6Gw=

CHANGELOG

@@ -1,3 +1,21 @@
+Version 0.5.0 (2018-06-29)
+--------------------------
+Add Gitter badge (#57)
+Fix typo in .travis.yml (#59)
+Remove vagrant setup (#60)
+Integrate scalafmt (#66)
+Publish scaladoc to gh-pages (#40)
+Integrate code coverage reports (#65)
+Remove cruft from .gitignore (#75)
+Switch from scalaz to cats (#61)
+Add issue template (#64)
+Add pull request template (#80)
+Add CONTRIBUTING.md (#76)
+Fix travis badge url (#83)
+Encapsulate side-effects into cats-effect IO (#63)
+Refactor test suite (#17)
+Move away from Twitter's util-collection (#42)
+
 Version 0.4.0 (2018-04-04)
 --------------------------
 Upgrade to Maxmind's GeoIP2 databases (#35)

CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributor guide
+
+The Scala Maxmind IpLookups library is maintained by the pipeline team at Snowplow Analytics and improved on by
+external contributors for which we are extremely grateful.
+
+## Getting in touch
+
+### Community support requests
+
+First and foremost, please do not log an issue if you are asking a general question, all of our community support requests
+go through our Discourse forum: https://discourse.snowplowanalytics.com/.
+
+Posting your problem there ensures more people will see it and you should get support faster than creating a new issue on
+GitHub. Please do create a new issue on GitHub if you think you've found a bug or if you would like to submit a feature
+request though!
+
+### Gitter
+
+If you want to discuss already created issues, potential bugs, new features you would like to work on or any kind of developer
+chat, you can head over to our [Gitter room](https://gitter.im/snowplow/scala-maxmind-iplookups).
+
+## Issues
+
+### Creating an issue
+
+The project contains an issue template which should help guiding you through the process. However, please keep in mind
+that support requests should go to our Discourse forum: https://discourse.snowplowanalytics.com/ and not GitHub issues.
+
+It's also a good idea to log an issue before starting to work on a pull request to discuss it with the maintainers.
+
+### Working on an issue
+
+If you see an issue you would like to work on, please let us know in the issue! That will help us in terms of scheduling and
+not doubling the amount of work.
+
+If you don't know where to start contributing, you can look at
+[the issues labeled `good first issue`](https://github.com/snowplow/scala-maxmind-iplookups/labels/good%20first%20issue).
+
+## Pull requests
+
+These are a few guidelines to keep in mind when opening pull requests, there is a GitHub template that reiterates most of the
+points described here.
+
+### Commit hygiene
+
+We keep a strict 1-to-1 correspondance between commits and issues, as such our commit messages are formatted in the following
+fashion:
+
+`Add issues description (closes #1234)`
+
+for example:
+
+`Introduce an error ADT (closes #1234)`
+
+### Writing tests and running tests
+
+Whenever necessary, it's good practice to add the corresponding unit tests to whichever feature you are working on.
+
+Then you can run `sbt test` to check they are working properly.
+
+### Feedback cycle
+
+Reviews should happen fairly quickly during weekdays. If you feel your pull request has been forgotten, please ping one
+or more maintainers in the pull request.
+
+### Getting your pull request merged
+
+If your pull request is fairly chunky, there might be a non-trivial delay between the moment the pull request is approved and
+the moment it gets merged. This is because your pull request will have been scheduled for a specific milestone which might or
+might not be actively worked on by a maintainer at the moment.
+
+### Contributor license agreement
+
+We require outside contributors to sign a Contributor license agreement (or CLA) before we can merge their pull requests.
+You can find more information on the topic in [the dedicated wiki page](https://github.com/snowplow/snowplow/wiki/CLA).
+The @snowplowcla bot will guide you through the process.

README.md

@@ -1,7 +1,9 @@
 # Scala MaxMind IP Lookups
 
-[![Build Status](https://travis-ci.org/snowplow/scala-maxmind-iplookups.png)](https://travis-ci.org/snowplow/scala-maxmind-iplookups)
+[![Build Status](https://api.travis-ci.org/snowplow/scala-maxmind-iplookups.svg?branch=develop)](https://travis-ci.org/snowplow/scala-maxmind-iplookups)
 [![Maven Central](https://img.shields.io/maven-central/v/com.snowplowanalytics/scala-maxmind-iplookups_2.12.svg)](https://maven-badges.herokuapp.com/maven-central/com.snowplowanalytics/scala-maxmind-iplookups_2.12)
+[![codecov](https://codecov.io/gh/snowplow/scala-maxmind-iplookups/branch/master/graph/badge.svg)](https://codecov.io/gh/snowplow/scala-maxmind-iplookups)
+[![Join the chat at https://gitter.im/snowplow/scala-maxmind-iplookups](https://badges.gitter.im/snowplow/scala-maxmind-iplookups.svg)](https://gitter.im/snowplow/scala-maxmind-iplookups?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 ## Introduction
 
@@ -17,13 +19,13 @@ can also configure an LRU (Least Recently Used) cache of variable size
 
 ## Installation
 
-The latest version of scala-maxmind-iplookups is **0.4.0** and is compatible with Scala 2.11 and
+The latest version of scala-maxmind-iplookups is **0.5.0** and is compatible with Scala 2.11 and
 2.12.
 
 Add this to your SBT config:
 
 ```scala
-val maxmindIpLookups = "com.snowplowanalytics" %% "scala-maxmind-iplookups" % "0.4.0"
+val maxmindIpLookups = "com.snowplowanalytics" %% "scala-maxmind-iplookups" % "0.5.0"
 ```
 
 Retrieve the `GeoLite2-City.mmdb` file from the [MaxMind downloads page][maxmind-downloads]
@@ -39,17 +41,28 @@ Here is a simple usage example, performing just a geographic lookup and not the
 connection type lookups:
 
 ```scala
+import cats.effect.IO
 import com.snowplowanalytics.maxmind.iplookups.IpLookups
 
-val ipLookups = IpLookups(geoFile = Some("/opt/maxmind/GeoLite2-City.mmdb"), ispFile = None,
-                  domainFile = None, connectionTypeFile = None, memCache = false, lruCache = 20000)
-
-ipLookups.performLookups("213.52.50.8").ipLocation match {
-  case Success(loc) =>
-    println(loc.countryCode)   // => "NO"
-    println(loc.countryName)   // => "Norway"
-  case Failure(f) =>
-    println(f)
+val result = (for {
+  ipLookups <- IpLookups.createFromFilenames[IO](
+    geoFile = Some("/opt/maxmind/GeoLite2-City.mmdb"),
+    ispFile = None,
+    domainFile = None,
+    connectionTypeFile = None,
+    memCache = false,
+    lruCacheSize = 20000
+  )
+
+  lookup <- ipLookups.performLookups("175.16.199.0")
+} yield lookup).unsafeRunSync()
+
+result.ipLocation match {
+  case Some(Right(loc)) =>
+    println(loc.countryCode)   // => "CN"
+    println(loc.countryName)   // => "China"
+  case _ =>
+    println("Lookup failed")
 }
 ```
 
@@ -109,11 +122,11 @@ The `performLookups(ip)` method returns a:
 
 ```scala
 case class IpLookupResult(
-  ipLocation: Option[Validation[Throwable, IpLocation]],
-  isp: Option[Validation[Throwable, String]],
-  organization: Option[Validation[Throwable, String]],
-  domain: Option[Validation[Throwable, String]],
-  connectionType: Option[Validation[Throwable, String]]
+  ipLocation: Option[Either[Throwable, IpLocation]],
+  isp: Option[Either[Throwable, String]],
+  organization: Option[Either[Throwable, String]],
+  domain: Option[Either[Throwable, String]],
+  connectionType: Option[Either[Throwable, String]]
 )
 ```
 
@@ -140,7 +153,10 @@ case class IpLocation(
   timezone: Option[String],
   postalCode: Option[String],
   metroCode: Option[Int],
-  regionName: Option[String]
+  regionName: Option[String],
+  isInEuropeanUnion: Boolean,
+  continent: String,
+  accuracyRadius: Int
 )
 ```
 
@@ -163,30 +179,26 @@ val ipLookups = IpLookups(
 val lookupResult = ipLookups.performLookups("70.46.123.145")
 
 // Geographic lookup
-println(lookupResult.ipLocation).map(_.countryName) // => Some(Success("United States"))
-println(lookupResult.ipLocation).map(_.regionName)  // => Some(Success("Florida"))
+println(lookupResult.ipLocation).map(_.countryName) // => Some(Right("United States"))
+println(lookupResult.ipLocation).map(_.regionName)  // => Some(Right("Florida"))
 
 // ISP lookup
-println(lookupResult.isp) // => Some(Success("FDN Communications"))
+println(lookupResult.isp) // => Some(Right("FDN Communications"))
 
 // Organization lookup
-println(lookupResult.organization) // => Some(Success("DSLAM WAN Allocation"))
+println(lookupResult.organization) // => Some(Right("DSLAM WAN Allocation"))
 
 // Domain lookup
-println(lookupResult.domain) // => Some(Success("nuvox.net"))
+println(lookupResult.domain) // => Some(Right("nuvox.net"))
 
 // Connection type lookup
-println(lookupResult.connectionType) // => Some(Success("Dialup"))
+println(lookupResult.connectionType) // => Some(Right("Dialup"))
 ```
 
 ### LRU cache
 
 We recommend trying different LRU cache sizes to see what works best for you.
 
-Please note that the LRU cache is **not** thread-safe ([see this note][twitter-lru-cache]). Switch
-it off if you are thinking about performing ip lookups with the same `IpLookups` instance across
-threads.
-
 ## Building etc
 
 Assuming you already have SBT installed: