How should one determine whether to release a Haskell library as one package or many?

Question

Sometimes a project can be organized either as a single package or as several packages. When one is in such a situation, how should one decide which option is better?

Answer 1

There are some immediate drawbacks of distributing a project over multiple packages:

• the build process is more complicated than just cabal build
• releases and version numbers have to be coordinated
• users have to install and depend on multiple packages
• API documentation is scattered on hackage

But there are also potential benefits for users that would only depend on a subset of the packages:

• they don't have to download, compile, link, install, trust and license code in packages they don't need
• they don't have to download, ..., and license dependencies of packages they don't need
• they can discover packages more easily if their name and metadata is specific to the individual package, not the whole project

And there are some benefits even if users end up depending on all packages:

• different packages can have different maintainers and/or release schedules

I think the decision should be based on whether you think that there are users that can actually realize the potential benefits. So I would say that the decision depends mostly on the answers to the following questions:

• Is there a part of the project that changes much more often than the other parts?
• Is there a part of the project that is more or less trusted than the other parts?
  (for example, a core package and a contrib package)
• Is there a part of the project that has many additional dependencies but is not needed by all users?
  (for example, an interface to another project)
• Is there a part of the project that can be reused independently of the purpose of the overall project?
  (for example, a combinator library used in the main project)
• Is there a part of the project that forces users to use a specific license (directly or via dependencies) but is not needed by all users?

Finally, with cabal there is a middle ground between "one package" and "many packages", because one cabal package can contain both one library and any number of executables, test-suites and benchmarks. This covers one important reason that would otherwise lead to split packages: Users should not have to depend on the testing libraries just to use the package.