An API diffing tool (similar to what Elm and Haskell have ) would be a great addition to our ecosystem. I also see it playing a key role in making upgrades easier.
Here’s a proposed sequence of developer conveniences we can enable once we have the API diffing tool.
Stage 1 - Verbose upgrade report
spago --upgrade-set (or a wrapper around it) runs an API diff for all packages in the package set (between the versions you’re upgrading from and to) and logs all changes to a single text file. This file will contain the before-and-after type signatures. There will be a lot of irrelevant changes listed in this file, such as the functions that you’re not even using, but at least this will be a reference to search through as you’re fixing compilation issues.
Stage 2 - Concise upgrade report
This is the same as the Stage 1 report, but only includes relevant differences. This likely requires comparing the report to the CST/AST/corefn representation of your project.
Stage 3 - Local upgrade annotations
fix-me comments into
.purs files wherever a modified API is called. This might be more convenient than having to constantly jump between your code and the upgrade report. These instructions could alternatively be summarized at the top of each
Stage 4 - Automated renames
Automatically apply simple upgrades directly to
.purs files when possible. I think the only realistic opportunities for this are renames and moves. Everything else likely requires some manual intervention to resolve.
Stage B - Changelog integration
We could leverage API diffs to enforce SemVer and good changelogs, or even help write the changelogs. This work doesn’t depend on any of the numbered stages, but will improve those stages. For example, the reports or fix-me comments could include the relevant changelog entries. We could also allow special changelog syntax to help identify renames and moves that are otherwise not detected by the diffing tool, which would make Stage 4 more effective. Many projects already follow the keep a changelog guidelines. Another tool (based on the API diff tool) could identify changelog gaps and offer to write some entries for you.
Is there a tool that will allow me to discover if I have made breaking changes to a module?
The tools section of the PVP spec lists a few options:
ghc-pkg-apidump: A tool for comparing the exported API of different version of the same GHC library package.
precis: Summarizes API differences between revisions of Cabal packages.
There’s also hackage-diff, which compares the public API of different versions of a Hackage library.
And for what it’s worth, Elm’s package manager (
elm-package) has a
diff subcommand that does exactly this: https://github.com/elm-lang/elm-package/blob/1a364bc/README.md#publishing-updates