Type-safe system-independent file path library
See the READMEs associated with the individual packages:
- pathway – core path operations
- pathway-quickcheck - utilities for testing Pathway usage using QuickCheck (particularly useful for doctest usage)
- pathway-path - integration with the path library
- pathway-system - integration with the local filesystem (extremely similar to the directory package, but with changes to take advantage of the type safety provided by Pathway).
We recommend the following steps to make working in this repository as easy as possible.
This command ensures that any work you do within this repository is done within a consistent reproducible environment. That environment provides various debugging tools, etc. When you leave this directory, you will leave that environment behind, so it doesn’t impact anything else on your system.
This will apply our repository-specific Git configuration to git commands run against this repository. It’s lightweight (you should definitely look at it before applying this command) – it does things like telling git blame to ignore formatting-only commits.
Especially if you are unfamiliar with the haskell ecosystem, there is a Nix build (both with and without a flake). If you are unfamiliar with Nix, Nix adjacent can help you get things working in the shortest time and least effort possible.
nix build will build and test the project fully.
nix develop will put you into an environment where the traditional build tooling works. If you also have direnv installed, then you should automatically be in that environment when you're in a directory in this project.
This project is built with Cabal. Individual packages will work with older versions, but ./cabal.package requires Cabal 3.6+.
The Haskell Package Versioning Policy is a good starting point for versioning Haskell code, however, this project is generally more strictly versioned than described there.
In the absolute, almost every change is a breaking change. This section describes how we mitigate that to provide minor updates and revisions.
Here are some common changes that can have unintended effects:
- adding instances can conflict with downstream orphans,
- adding a module can conflict with a module from another package,
- adding a definition to an existing module can conflict if there are unqualified imports, and
- even small bugfixes can introduce breaking changes where downstream depended on the broken results.
To mitigate some of those issues for versioning, we assume the following usage:
- modules should be imported using
PackageImports, so that adding modules is a minor change; - modules should be imported qualified, so that adding definitions is a minor change;
- adding instances can't be mitigated in the same way, and it's not uncommon for downstream libraries to add orphans instances when they're omitted from upstream libraries. However, since these conflicts can only happen via direct dependencies, and represent an explicit downstream workaround, it’s reasonable to expect a quick downstream update to remove or conditionalize the workaround. So, this is considered a minor major change;
- deprecation is considered a revision change, however it will often be paired with minor changes.
-Werrorcan cause this to fail, but published libraries shouldn't be compiled with-Werror.
See the Pathway package documentation for comparisons with a large number of other libraries.