šŸŽ“ā˜ļø Learn to Cloud by building and deploying apps!

How to update a dependency

This doc walks through the process of updating a dependency which has been released as a Unison project. The following workflow uses Unison's standard library, base, as an example.

ā±

Suggested workflow summary:

    • (Optionally) create a new branch for the update process so that you can easily revert if something goes wrong
      • myProject/main> branch myProject/upgradeBase
    • pull the latest version of the dependency into your codebase so that it is a sibling of your current library version.
      • myProject/upgradeBase> pull @unison/base/releases/X.Y.Z lib.newBase
    • Apply the patch from the new version of the library to the project
      • patch lib.newBase.patch
    • Check if there are todo items in your project as a result of applying the patch
      • myProject/upgradeBase> todo
    • Delete the old version of base from your codebase.
      • myProject/upgradeBase> delete.namespace lib.base
    • Rename the new version of base to base
      • myProject/upgradeBase> move.namespace lib.newBase lib.base

First, pull the new version of the library into the lib namespace of your project. It should not be pulled into the same namespace as your existing library version. Instead, give the new version a distinct name, like baseV2 or newBase. We can change the name later. The exact version number of library you want to install can be found by visiting the project's home page on Unison Share. Click the big green button called "Use Project" to get a copy of the command to run.

myProject/upgradeBase> pull @unison/base/releases/X.Y.Z lib.newBase

Then apply the the patch from the new library version to the project. Assuming your UCM console is located at the top of your project, you can use the patch command like so:

myProject/upgradeBase> patch lib.newBase.patch

Patches map old term references to new references in a namespace; they're part of what helps Unison automatically propagate changes when functions get updated. Patch entries are created automatically when the library author runs update.

Next you should check if there are todo items in your project as a result of applying the patch. At the root of your project, run todo:

myProject/upgradeBase> todo

Todo items can happen if a function in your project depends on a function in the library whose type signature has changed in the new version. If there are todo items after applying the patch, the UCM should supply a suggested order to tackle them in. You'll want to edit the terms into a scratch file, resolve the conflicts and then update the terms.

Once there are no todo items it's safe to delete the old library version from the lib namespace of the project. You may want to rename your new library version to base again so that it's easier to refer to in the future.

myProject/upgradeBase> delete.namespace lib.base
myProject/upgradeBase> rename.namespace lib.newBase lib.base

Finally, merge the upgradeBase branch into main and delete your upgrade branch.

myProject/upgradeBase> merge /upgradeBase /main
myProject/upgradeBase> delete.branch /upgradeBase

It's done! Your project is now using the latest version of the dependency!