Unison Share code hosting

Unison Shareis Unison's own code hosting service. Unison's unique code format and tooling enables different strategies for remote repositories. We created Unison Share to support code hosting, library discovery, collaboration, source code viewing, and documentation rendering.

The concept for code repositories in Unison is called projects. Projects help organize your codebase into applications, libraries, and other shareable, packageable work.Learn more about projects here.Projects are futher subdivided into branches, Unison Share can also warehouse publicnamespacesunattached from a project. Yourpublicnamespace is typically for unstructured work.

🏗️This document describes how to perform common interactions with Unison Share. We'll add more here as more functionality gets added to the platform.

Pushing and pulling code

First, You'll want to make sure you're logged in to the Unison Share platform. Runauth.loginin the UCM locally.

.> auth.login

This will open your default web browser and prompt you to log into Unison Share.

To push a project, use thepushcommand from inside the project and branch you're hoping to share. This pushes themainbranch to @username/myProject/main.

myProject/main> push

To push a namespace, use thepushcommand from inside the namespace you're hoping to share, or use a fully qualified name (one which starts with a dot,.)as the second argument to the command.

.> push myUser.public.myCode .myCode

To bring a remote namespace into your local codebase, issue thepullcommand in the UCM.

myProject> pull myUser.public.myProject.main .myProject
If you're pulling a library dependency into your code, the convention is to put the dependencies in a namespace calledlibunder your project. For example, if I'm working on a project called.foo,I'd put all of its dependencies underfoo.lib.

Library structure conventions

For the best experience hosting a library on Unison Share, we recommendcreating a projectwhere themainbranch represents the latest work in progress, feature branches are used for concurrent workstreams, and release branches or release drafts are snapshots of themainbranch at a given point in time.

     -- fork of main
     -- snapshots of main

Inside themainbranch of your project, located just under the project root, you should have alibnamespace to contain your library's dependencies. Optionally you can include aREADMEdocumentat the root of your project code. If present, Unison Share will automatically render the README as the landing page of the project.

Another special document you can include at the root of your project isReleaseNotes,which will be rendered as the release notes for the latest release of your library. This is a good place to include information about how to upgrade from previous versions, or any other information you'd like to convey to users of your library. If Unison Share detects aReleaseNotesterm in your project, it will automatically render it as the release notes for the latest release of your library.

Consumers of your library hoping to obtain the most recent released version of the library would pull@user/project/releases/X.Y.Z,whereas fellow maintainers would likely choose toclonethemainbranch to keep in sync with active development. Once a new release is ready, you can hit the "release" button in the Unison Share UI to create a release frommain.Read more about creating library releases here.

Once your library is ready to go public, you should consider featuring your work on the Unison Share front-page catalog! Head to the#libraries channel in the Unison slackand ping@hojbergwith a link to your project.