typelevel / typelevel/cats

Decide how public-facing instance traits should be

Open
#3,008 4 comments 0 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

Right now we have AllInstances and AllSyntax traits that are in the public API and are sometimes used outside of Cats itself—for example in Circe we have a CirceSuite helper class that extends these traits so that we don't have to import cats.implicits._ in every test file.

The problem with this kind of usage is that AllInstances and AllSyntax don't actually include all of anything, ever since we started stacking on BinCompatN layers to maintain binary compatibility on Scala 2.11. For example, want a Defer for Function0? You won't get it from AllInstances—you also need AllInstancesBinCompat0.

This means anyone using AllInstances or AllSyntax has to be careful to add the latest AllSyntaxBinCompat37 or whatever traits included in each new Cats release if they actually want everything.

This is something we haven't managed to stay on track on even within Cats itself—e.g. see #3007, which is due to the fact that cats.implicits is lagging two AllSyntaxBinCompats behind, or SyntaxSuite, which is four AllInstanceBinCompats out of date (but happens to still be working), etc.

To make things even more confusing, there's a AllSyntaxBinCompat (note the missing number) abstract class that bundles up all the syntax bin-compat traits, but no equivalent AllInstancesBinCompat.

I've also recently proposed (and merged) making the bin-compat traits package-private (#3003), which on second thoughts I think we'll have to undo, at least until 2.1.

So there's a lot of miscellaneous little brokenness and inconsistency and mildly bad UX here, some of which I'm about to open a PR to address, but there's also a bigger question of whether we actually intend the AllInstances and AllSyntax traits to be used outside of the implementation of Cats itself.

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 reading the public AllInstances and AllSyntax traits, their numbered BinCompat layers, and the unnumbered AllSyntaxBinCompat class mentioned in the issue. Compare their use in cats.implicits and SyntaxSuite, then review #3003 and #3007. Done requires a decided and consistent policy for external use and an agreed scope for the related compatibility changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
scala
Domain
api, developer-experience
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.