Common workflows for updating Unison code

Example walk-through

Let's say we have a simple type and a few functions that use it in our codebase:

type Box = Box Nat

Box.toText : Box -> Text
Box.toText box = match box with
  Box.Box nat -> Nat.toText nat

Box.print : Box -> {IO,Exception} ()
Box.print box =
  Box.toText box |> printLine

scratch/main> update

We add it to the codebase, but later, we realize its data constructor should be changed.

scratch/main> edit Box

type Box = Box Int

We've changed the type from taking a value of type Nat to Int. Upon saving the file and running update again, the UCM will open the impacted terms in your editor and create a -update branch for resolving the conflicts.

scratch/main> update

  Some definitions don't typecheck with your changes. I've updated the file
  scratch.u with the definitions that need fixing. Once the file is
  compiling, try `update` again.

  I've also switched you to a new branch update-main for this work. On `update`, it will be merged
  back into main.

scratch/update-main>

All impacted terms, including indirect dependents, will be opened in your scratch file. In our example, the function Box.print is opened in the editor even though the change we need to make is in Box.toText. This is because resolving larger, more complicated updates can involve propagating changes to many terms, all the way up the function call chain.

type Box = Box Int

-- The definitions below no longer typecheck with the changes above.
-- Please fix the errors and try `update` again.

Box.print : Box ->{IO, Exception} ()
Box.print box = Box.toText box |> printLine

Box.toText : Box -> Text
Box.toText = cases Box nat -> Nat.toText nat

Resolve the compilation errors with the help of the UCM.

The 1st argument to `Nat.toText`

        has type:  Int
  but I expected:  Nat

  5 | Box.toText = cases Box nat -> Nat.toText nat
  6 |
  7 | type Box = Box Int

Box.toText : Box -> Text
Box.toText = cases Box int -> Int.toText int

When the scratch file compiles, you'll see a message describing the change set.

scratch/update-main>

Loading changes detected in scratch.u.


~ type Box

~ Box.print  : Box ->{IO, Exception} ()
~ Box.toText : Box -> Text

+ (added), ~ (modified), - (deleted)

Run `update` to apply these changes to your codebase.

Run update again to apply the change and the UCM will finish the update by deleting the temporary branch.

Deleting terms in change sets

When you're resolving an update, you might realize that some functions are no longer needed. To handle this, UCM has a specific workflow for removing terms as part of a change set.

Here's how it works:

• During the update process, UCM creates a temporary update branch and opens the affected terms in a scratch file.
• If you remove a term from that file, UCM interprets it as a deletion — and removes it from the codebase in the resulting change set.

From our preceding update example, say we wanted to remove Box.print while resolving the type error.

 type Box = Box Int

 -- The definitions below no longer typecheck with the changes above.
 -- Please fix the errors and try `update` again.

 Box.toText : Box -> Text
 Box.toText = cases Box int -> Int.toText int

 Box.print : Box -> {IO,Exception} ()
 Box.print box =
   Box.toText box |> printLine

Removing it from the file causes Box.print to be listed as a deletion. It won't be present in the codebase after resolving the update.

   Loading changes detected in ~/Unison/website3/website/testTour.u.

   ~ type Box

   ~ Box.toText : Box -> Text
   - Box.print : Box ->{IO, Exception} ()

   + (added), ~ (modified), - (deleted)

   Run `update` to apply these changes to your codebase.