GhcCompat plugin

Eases support for multiple GHC versions

Controls various GHC options and extensions to make compilation across multiple versions easier, and to alert you to incompatibilities.

Often GHC will add warnings to encourage users to make use of newer language features. However, if you’re like me, you use -Weverything and also support a large number of GHC versions. This can lead to a bunch of fragile conditionalization as you need to disable certain warnings but not before those warnings were added to GHC.

This plugin does three things:

1. reports if you use any language extensions that aren’t supported by your minimum GHC version,
2. automatically disables any warnings where addressing them requires features that aren’t part of your minimum GHC version, and
3. reports any warnings from no. 2 that were introduced before GHC 8.10.1¹.

So, currently, if you enable this plugin,

Note that there are often versions between the oldest one you support and the one where the plugin disables the warning. This is because the flag warning about a feature can be added long after the feature (for example, role annotations were added in GHC 7.8.1, but the warning to use them wasn’t added until GHC 9.8.1).

usage

Add the following to any stanzas² in your Cabal package files.

library
  build-depends: ghc-compat-plugin >=0.0.1 && <0.1,
  ghc-options:
    -fplugin=GhcCompat
    -fplugin-opt=GhcCompat:minVersion=8.8.1

Note that in the last line, you must provide the oldest GHC version you support to the plugin, so it knows which flags to disable.

You can also add

    -fplugin-opt GhcCompat:reportIncompatibleExtensions=error

(where error can also be warn (the default) or no) in order to control how the plugin informs you of enabled extensions that aren’t compatible with all of your supported GHC versions.

NB: This plugin should load from GHC 7.2 (the first version of GHC to support plugins³). However, it currently won’t do anything before GHC 7.10.1. If you do need to support a GHC prior to 7.2, you can use the plugin conditionally, like

library
  if impl(ghc >= 7.2.1)
    build-depends: ghc-compat-plugin >=0.0.1 && <0.1,
    ghc-options:
      -fplugin=GhcCompat
      -fplugin-opt=GhcCompat:minVersion=6.8.1

versioning

This project largely follows the Haskell Package Versioning Policy (PVP), but is more strict in some ways.

The version always has four components, A.B.C.D. The first three correspond to those required by PVP, while the fourth matches the “patch” component from Semantic Versioning.

Here is a breakdown of some of the constraints:

sensitivity to additions to the API

PVP recommends that clients follow these import guidelines in order that they may be considered insensitive to additions to the API. However, this isn’t sufficient. We expect clients to follow these additional recommendations for API insensitivity

If you don’t follow these recommendations (in addition to the ones made by PVP), you should ensure your dependencies don’t allow a range of C values. That is, your dependencies should look like

yaya >=1.2.3 && <1.2.4

rather than

yaya >=1.2.3 && <1.3

use package-qualified imports everywhere

If your imports are package-qualified, then a dependency adding new modules can’t cause a conflict with modules you already import.

avoid orphans

Because of the transitivity of instances, orphans make you sensitive to your dependencies’ instances. If you have an orphan instance, you are sensitive to the APIs of the packages that define the class and the types of the instance.

One way to minimize this sensitivity is to have a separate package (or packages) dedicated to any orphans you have. Those packages can be sensitive to their dependencies’ APIs, while the primary package remains insensitive, relying on the tighter ranges of the orphan packages to constrain the solver.

transitively breaking changes (increments A)

removing a type class instance

Type class instances are imported transitively, and thus changing them can impact packages that only have your package as a transitive dependency.

widening a dependency range with new major versions

This is a consequence of instances being transitively imported. A new major version of a dependency can remove instances, and that can break downstream clients that unwittingly depended on those instances.

A library may declare that it always bumps the A component when it removes an instance (as this policy dictates). In that case, only A widenings need to induce A bumps. B widenings can be D bumps like other widenings, Alternatively, one may compare the APIs when widening a dependency range, and if no instances have been removed, make it a D bump.

breaking changes (increments B)

restricting an existing dependency’s version range in any way

Consumers have to contend not only with our version bounds, but also with those of other libraries. It’s possible that some dependency overlapped in a very narrow way, and even just restricting a particular patch version of a dependency could make it impossible to find a dependency solution.

restricting the license in any way

Making a license more restrictive may prevent clients from being able to continue using the package.

adding a dependency

A new dependency may make it impossible to find a solution in the face of other packages dependency ranges.

non-breaking changes (increments C)

adding a module

This is also what PVP recommends. However, unlike in PVP, this is because we recommend that package-qualified imports be used on all imports.

other changes (increments D)

widening a dependency range for non-major versions

This is fairly uncommon, in the face of ^>=-style ranges, but it can happen in a few situations.

deprecation

NB: This case is weaker than PVP, which indicates that packages should bump their major version when adding deprecation pragmas.

We disagree with this because packages shouldn’t be publishing with -Werror. The intent of deprecation is to indicate that some API will change. To make that signal a major change itself defeats the purpose. You want people to start seeing that warning as soon as possible. The major change occurs when you actually remove the old API.

Yes, in development, -Werror is often (and should be) used. However, that just helps developers be aware of deprecations more immediately. They can always add -Wwarn=deprecation in some scope if they need to avoid updating it for the time being.

licensing

This package is licensed under The GNU AGPL 3.0 only. If you need a license for usage that isn’t covered under the AGPL, please contact Greg Pfeil.

You should review the license report for details about dependency licenses.

comparisons

This was inspired by compatibility flags in other language implementations, like -Wc++11-compat in GCC and Clang.