# base-compat-migrate [![Hackage](https://img.shields.io/hackage/v/base-compat-migrate.svg)](https://hackage.haskell.org/package/base-compat-migrate) [![Build Status](https://travis-ci.org/bergmark/base-compat-migrate.svg)](https://travis-ci.org/bergmark/base-compat-migrate)

This library is meant as a temporary migration library when moving a
library to
[base-compat](http://hackage.haskell.org/package/base-compat) or
upgrading it. Replace `base-compat` with
[base-compat-batteries](https://hackage.haskell.org/package/base-compat-batteries)
in the rest of the README if you want to use that library instead.

`base-compat` defines backwards compatible versions of some base
modules; If you for example want to make sure `import Prelude` does
the same thing on all GHC versions you can instead `import
Prelude.Compat`. If a Compat module exists it means it has some
backwards compatibility fix, it also re-exports everything that is
unchanged from the corresponding base module.

base-compat notably does not have Compat modules for every base module
so you often need to depend on both base and base-compat. The standard
recommended work-flow is to build your project with the oldest GHC you
want to support and add Compat imports accordingly.

If you don't have quick access to old GHCs it can be error-prone to
migrate to upgrade base-compat since you need to look through all base
imports to see if you should be using Compat versions instead.

## Workflow

This library offers a different work flow:

1. Make sure you are using a GHC version compatible with this project
   (At the time of writing it is GHC 8.4.1)
1. Replace any `base` and `base-compat` dependencies in your project
   with `base-compat-migrate`.
1. Add `default-extensions: NoImplicitPrelude` to each build component
   (libraries, executables, test suites, benchmarks).
1. Compile your project and fix issues:
  * Add any needed `Prelude.Compat` imports
  * If a `base` module can't be found change the import to the
    `Compat` version instead.
1. Finally, replace the `base-compat-migrate` dependency with `base`
   and `base-compat`.

Whenever you wish to support newer versions of `base` or `base-compat`
you can repeat these steps.

### Common Issues with Solutions

* If your package declares Paths modules it won't compile without
  access to base. You can drop the Paths module until the affected
  component builds, and then add it again along with the base
  dependency.

## Dependencies

Since `base-compat-migrate` re-exports modules, we depend on minor
versions of `base` and `base-compat`. A new minor version of either
may require a new release of this library. This project's cabal file
is generated by running `generate-library/Main.hs`.