typelevel / typelevel/cats

Make instance packages more consistent

Open
#2,790 4 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Scala
Stars
5.5k
Forks
1.2k
Avg merge
2d 10h
Merged PRs (30d)
5

Description

There's currently a lot of inconsistency in the way cats.instance and cats.kernel.instances are implemented, which can be extremely frustrating, especially for people trying to work with Cats from Java), or for contributors who want to know where to add something (e.g. me, in the past), or for anyone thinking of pointing to Cats as an example of a thoughtfully-structured Scala library (e.g. me, now).

For example, all cats.instances.xyz are defined as objects inside a cats.instances package object (which seems completely unnecessary and messy for Java users), except for cats.instances.symbol, which for some reason is defined as a package object in its own file. The cats-kernel instance packages follow the same approach, with each cats.kernel.instances.xyz being a package object.

Whether or not BinCompat and prioritizations traits are package private are also inconsistent across the instances packages.

In my view Cats should follow the cats-kernel approach consistently across both kernel and core, and all compat and prioritization traits should be made as private as possible without breaking the build. I'm happy to do this myself if people agree it should happen, but since these changes will break binary compatibility I guess they have to wait for 3.0? It's a shame to have to tell users who need Java compatibility that they have to roll a bunch of their own awful boilerplate because some bad decisions that made it into 1.0 will necessarily live 2+ years or whatever.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the cats.instances and cats.kernel.instances package objects, including the separate cats.instances.symbol file, and inspect how BinCompat and prioritization traits are scoped. Confirm the build and binary-compatibility constraints before changing the structure. Done means the instance packages follow one consistent approach across core and kernel, with compatibility and prioritization traits as private as possible without breaking the build.

Written by the indexing model from the issue text.

Assessment

Tech stack
scala
Domain
developer-experience
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.