Organizing your codebase (deprecated)

Upgrading libraries to the latest version

There's no problem with having multiple versions of a library installed at once, though sometimes you want to upgrade to the latest version of a library and delete any references to the old version. There are a couple cases you can encounter here. Ifalice.mylib.v6is a superset ofalice.mylib.v5,this is as simple as just deleting thev5afterv6is installed.

😎 Since references to definitions are by hash, not by name, any renaming of definitions done betweenv5andv6of a library won't break any of your code. Though we recommend reading the release notes to discover these sorts of changes, or usingdiff.namespace somelib.v5 somelib.v6for an overview.

Ifv6replaced any definitions with new ones (using theupdatecommand orreplace.termorreplace.type),these are recorded in apatchwhich can be applied locally.

As a norm,alice.mylib.v6.releaseNoteswill cover how to apply patches to your local namespace. It will typically be commands like:

.myProject> branch main upgradeAliceLib
.myProject> patch external.mylib.v6.patches.v5_v6 upgradeAliceLib
.myProject> merge /upgradeAliceLib /main

Day-to-day development: creating and merging pull requests

Here's the basic workflow for drafting changes tomaininyour own project.It's not much different than a typical Git workflow, where you create branches, hack on them, then merge them tomainwhen done:

1. myProject/main> branch main myCoolPR
2. myProject/myCoolPR>Now hack away. Usemerge.preview main myCoolPRat any time to see what you've changed.
3. myProject/myCoolPR> merge /myCoolPR /mainwhen you're done

To propose changes to another Unison codebase works similarly. We'll usethe Unison base libraryas an example:

1. .> pull unison.public.base.main _baseyou can do this both for initial fetch and for subsequent updates
2. .> fork _base .prs.base._mythingto create a copy of_base.You can create multiple forks in.prs.base,if you have multiple things you're working on.
3. If you haven't already done so, set your default license for.prs.baseto match the license of the codebase you're contributing to. Forbaseit's the MIT license.
4. Nowcd .prs.base._mythingand hack away as before. At any time review what's changed between your namespace and_basewithdiff.namespace ._base .prs. base._mything.
5. Push your forked version somewhere public with yourUnison Share account.prs.base._mything> push myUser.public.prs.base._mything.No need to maintain a separate Git repo for every Unison library you want to contribute to.
6. .prs.base._mything> pull-request.create unison.public.base.latest myUser.public.prs.base._mythingand this will create some output. Copy that output to your clipboard. We don't literally use the GitHub pull request mechanism for Unison repositories, we use GitHub issues instead.
7. Use the GitHub issue comments for coordinating the review. Once merged, the maintainer will close the issue.
8. Next, create a GitHub issue in the repo you're submitting the code to (that's right, anissue,nota GitHub PR). Many Unison repositories will havea GitHub issue templatefor this purpose. Make the issue title something descriptive, and for the issue body, paste in the output generated by

   pull-request.create` as well as some text describing the change, just like you would for any other pull request.
   
                                                                                                                                                                                                                                                                                               This workflow also works fine even if the source and destination repository are the same, so you might use the above PR process when suggesting changes to a library  that you maintain with other people.
   
                                                                                                                                                                                                                                                                                               ### Reviewing pull requests
   
                                                                                                                                                                                                                                                                                               We'll use [this issue as an example](https://github.com/unisonweb/base/issues/12). The issue created for the PR will have a

   pull-request.load''command to review the PR locally. We'll run that command in any empty namespace:

.review.pr12> pull-request.load unison.public.base.main pchiusano.public.unisoncode.prs.random2

If you.review.pr12> lsyou'll see three or four sub-namespaces:base(the original namespace),head(the new namespace),merged(the result ofmerge head base)and potentiallysquashed(the same content asmergedbut without intermediate history). The following commands can be performed against either themergedorsquashednamespace, depending on if preserving history is important to you:

1. .review.pr12> diff.namespace base mergedto see what's changed. The numbered entries in the diff can be referenced by subsequent commands, sodiff.namespace base mergedmight be followed byview 1-7to view the first 7 definitions listed there.
2. You can use comments on the GitHub issue to coordinate if there's any changes you'd like the contributor to make before accepting the PR. You can also make changes directly inmerged.
3. .review.pr12> push unison.public.base.main mergedto pushmergedtomain
4. .review.pr12> history mergedand copy the top namespace hash. That's the Unison namespace hash as of the merged PR. Then close the GitHub issue with a comment like "Merged to main in hash #pjdnqduc38" and thank the contributor. 😀 If you ever want to go back in time, you can say.> fork #pjdnqduc38 .pr12to give the#pjdnqduc38namespace hash the name.pr12in your tree.
5. If you like,.> delete.namespace .review.pr12to tidy up afterwards.

.> pull git(https://gitub.com/unisonorama/myproject) main

Using unreleased library versions

Sometimes, you want to use some code that's only inmainof a library but hasn't made its way into a release. No problem. The install process looks the same, just do apull:

.> pull https://github.com/bob/mylib:.main .external.bob.mylib.main

As often as you like, you can re-issue the above command to fetch the latest version of the library. After doing so, you should then apply patches from the library to your local namespace. Check the project's README for information on how to do this, but typically, for a namespace,bob.mylib.main,there will just be a patch calledbob.mylib.main.patchwhich can be applied with:

.> fork main prs.upgradeBob
.> patch external.bob.mylib.main.patch prs.upgradeAliceLib

Assuming all is well after thatpatch,you can.> merge prs.upgradeBob main(and then sync that with any other PRs being drafted, as discussed in the previous section).

If you are feeling adventurous it's also possible to directly apply the patch to your in-progress PRs or evenmain.

How to create a release

Suppose you are creatingv12of a library. The process is basically toforka copy ofmain:

0. Before getting started, we suggest reviewing the current patch inmainwith.> view.patch main.patch.The term and type replacements listed here should generally be bugfixes or critical upgrades that you expect users of your library to make as well. You can usedelete.term-replacementanddelete.type-replacementto remove any entries you don't want to force on library users. See below for more.
1. Fork a copy ofmain:.> fork main series._v12
2. The current dependencies in the release should be included in the library'slibnamespace. This convention ensures that anyone who obtains the library also receives its dependencies and the naming for those definitions at the time.
3. Create or updateseries._v12.releaseNotes : Doc.You can include the current namespace hash ofseries._v12,a link to previous release notes, likereleases. _v11 releaseNotes,and if the release has a non-emptypatch,give some guidance on upgrading. Are all the edits type-preserving? If no, what sort of refactoring will users have to do?
4. squash series._v12 releases._v12to create the release. This squashedreleases._v12will have no history and is more efficient for users topullinto their codebase.
5. • Reset the patch and release notes inmain:.main> delete.patch patchand.main> delete.term releaseNotes.Anyone can upgrade from a past releasev3,by applying the patchesreleases._v4.patch,releases._v5.patchup throughreleases._v12.patch.
   • • If desired, you can also produce cumulative patches for skipping multiple versions. These can be published on an ad hoc basis. If publishing these, just include them inreleases._v12.patches.v4_to_v12.
6. Optional: you can add updated instructions for fetching the release to the the README on the repo's Unison Share page. You can also let folks know about the release via any other communication channels (Twitter, Slack, etc).

We don't recommend any fancy numbering scheme for versioning, just increment the version number. Use thereleaseNotesto convey metadata and additional nuance about each release.

.mylib.trunk> view.patch patch

  Edited Terms: List.frobnicate#92jajfh197 -> List.frobnicate
  Edited Terms: CinnamonRoll#93jg10ba -> SugarCookie

  Tip: To remove entries from a patch, use delete.term-replacement or
       delete.type-replacement, as appropriate.