add transcript that demonstrates old undesirable behavior

unison-cli/src/Unison/Codebase/Editor/HandleInput/Upgrade.hs

@@ -18,7 +18,6 @@ import Unison.Cli.Monad qualified as Cli
 import Unison.Cli.MonadUtils qualified as Cli
 import Unison.Cli.ProjectUtils qualified as Cli
 import Unison.Codebase qualified as Codebase
-import Unison.Codebase.Branch (Branch0)
 import Unison.Codebase.Branch qualified as Branch
 import Unison.Codebase.Branch.Names qualified as Branch
 import Unison.Codebase.Editor.HandleInput.Branch qualified as HandleInput.Branch

unison-src/transcripts/dont-upgrade-refs-that-exist-in-old.md

@@ -0,0 +1,21 @@
+If `foo#old` exists in old, and `foo#new` exists in new, you might think `upgrade old new` would rewrite references to
+`#old` with references to `#new`. And it will... !!unless!! `#old` still exists in new.
+
+```ucm:hide
+.> project.create-empty foo
+foo/main> builtins.merge
+foo/main> move.namespace builtin lib.builtin
+```
+
+```unison
+lib.old.foo = 18
+lib.new.other = 18
+lib.new.foo = 19
+mything = lib.old.foo + lib.old.foo
+```
+
+```ucm
+foo/main> add
+foo/main> upgrade old new
+foo/main> view mything
+```

unison-src/transcripts/dont-upgrade-refs-that-exist-in-old.output.md

@@ -0,0 +1,48 @@
+If `foo#old` exists in old, and `foo#new` exists in new, you might think `upgrade old new` would rewrite references to
+`#old` with references to `#new`. And it will... !!unless!! `#old` still exists in new.
+
+```unison
+lib.old.foo = 18
+lib.new.other = 18
+lib.new.foo = 19
+mything = lib.old.foo + lib.old.foo
+```
+
+```ucm
+
+  Loading changes detected in scratch.u.
+
+  I found and typechecked these definitions in scratch.u. If you
+  do an `add` or `update`, here's how your codebase would
+  change:
+  
+    ⍟ These new definitions are ok to `add`:
+    
+      lib.new.foo   : Nat
+      lib.new.other : Nat
+      lib.old.foo   : Nat
+      mything       : Nat
+
+```
+```ucm
+foo/main> add
+
+  ⍟ I've added these definitions:
+  
+    lib.new.foo   : Nat
+    lib.new.other : Nat
+    lib.old.foo   : Nat
+    mything       : Nat
+
+foo/main> upgrade old new
+
+  I upgraded old to new, and removed old.
+
+foo/main> view mything
+
+  mything : Nat
+  mything =
+    use Nat +
+    foo + foo
+
+```