API breakage and compatibility resource

[Benjmhart]

API breakage is VERY common across the suite of tools being used to build Plutus Apps

it would be great if there was a common resource that at least made a record of API changes across dApps, and suggested common fixes for these. In an ideal case, we could produce scripts that will automatically perform code updates to fit API breakage.

This could dovetail nicely with reliable build solving - as it would allow a community API management team to document upgrades that would be ill-advised for individual developer teams.

This is work that could save a lot of companies piles of money, the amount of time spent on dependency upgrades can get pretty staggering.

[Benjmhart]

There are a few practices that help resolve these issues

1. a CI/CD job for tools that help identify which upstream libraries commit they build together with (including GHC versions)
2. an explicit roundup of recent API changes, and suggested fixes - perhaps in a single resource and including known fixes
3. maintaining deprecated functions within the API for a few versions to give developers time.
4. automating fixes where possible - using libGHC to automatically fix API breakage where possible within a CLI tool or similar.

[zliu41]

identify which upstream libraries commit they build together with (including GHC versions)

The situation will be much improved once we get rid of source-repository-packages and start using CHaP (which is basically IOG internal Hackage), something @michaelpj is actively working on.

IOG is also working on defining a process for upgrading GHC versions across multiple repositories, which will be documented in the Cardano engineering handbook (not yet public).

Suggestions in the change log on how to migrate to the new version when an API makes a breaking change is a good idea, which we should probably include as a policy in the engineering handbook.

[Benjmhart]

one other item that comes up routinely across the ecosystem is that builds on past commits on the master branch can be broken when that commit includes an upstream dependency on a feature branch - the upstream branch is then often deleted on merge or rebased out of existence.

Next steps for the working group include creating proposals detailing the practices we encourage, and looking for participant organizations to sponsor some action toward them.

[michaelpj]

one other item that comes up routinely across the ecosystem is that builds on past commits on the master branch can be broken when that commit includes an upstream dependency on a feature branch

Solution: never ever do this because it's crazy. Which is what CHaP gets us: people will be using properly released versions of packages, so we shouldn't have a situation where people are using upstream dependencies pinned to an ephemeral feature branch.