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.

🏗️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.

🧠
By convention, your Unison code is hosted in apublicnamespace under your username.

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.

.myProject> push myUser.public.myProject.main .myProject

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 recommend the following namespace structure:

public
  myProject
    latest
      README
    main
    releases
      v1
      v2

Under thepublicnamespace, you should list the name of your library, followed by three namespaces,latest,referring to the latest release of your library;main,which is the current head or working state of your library; andreleases,which contains a historical, versioned view of past releases.

📰
When you write your library, be sure to include aREADMEDocterm at the root of your library code. If present, Unison Share will automatically render the README as the landing page of the library.

Consumers of your library hoping to obtain the most recent released version of the library would pulllatest,whereas fellow maintainers would likely choose to pullmainto keep in sync with active development. Once a new release is ready, you canforkthe currentlatestto a properly versionedreleasenamespace and make the currentmainthelatestrelease.

Additionally, you can also define aDocterm calledREADMEunder yourpublicnamespace which will serve as your individual user landing page.

💡
Once your library conforms to the structure above, 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.