In the next few weeks, we'll be releasing a new abstraction for organizing, packaging, and collaborating on code. We're calling it "projects." There will be some new UCM commands and Unison Share features to support them. This post is to give folks a heads up so you have some idea of what to expect.
Projects will be the basis for a lot of new functionality, such as pull requests, permissions (including private projects and multi-user collaboration), releases, and dependency management.
The primary unit for grouping Unison code has thus far been namespaces. Namespaces are a bit like versioned directories for Unison code; they can contain other namespaces or Unison definitions. Their granularity and simplicity has enabled a ton of great work, but arguably we've been shoehorning complicated ecosystem needs into the namespace concept. Does your library need a log of its releases? Persist it in a namespace! Adding a dependency to your code? Put it in a special lib namespace. Contributing a feature to a library? Fork the namespace and merge it! All these workflows are done with low-level namespace manipulation commands which are easy to mess up.
With projects, we're building more first-class support for these workflows, with thoughtfully designed dedicated commands that are easier to use. Namespaces aren't going away, they're just going to wear fewer hats.
That's a bit about why we're introducing projects, let's sketch out what they are at a high level. Projects will help segment your Unison code into logical repository-like units. A library you've authored, a service you maintain, or a company application you contribute to might each be defined as separate projects. You'll issue a UCM command to initialize them, and the created project will live at the top-level of your codebase.
Projects can be further segmented by having multiple branches. Each project will have a "main" branch, but you might also work in a "contributor branch" on a feature for another library. With branches, projects add a codebase primitive for supporting concurrent work streams. That's one step towards a fully-fledged PR process! You'll be able to switch between branches of a project, and when you push a branch to Unison Share, it will be linked to your Unison Share user.
With the first release of the projects feature you will be able to:
- Create a new project with the UCM
- View and switch between your projects in the UCM terminal
- Create a new branch or switch to an exiting branch in a project
- Push a project to Unison Share for others to browse and download
- Clone a project from Unison Share for contributing to it
- Pull a project from Unison Share for including it as a dependency
For now, nothing will change about your interactions with existing non-project Unison code. You can still jam on Unison code in namespaces without the formality of promoting them to projects because we think it's a great way to quickly break new ground for programming, and we don't want to get in the way of that. 😎 When the projects feature lands we'll be supporting contributors with a migration path for their existing libraries. A tutorial with the actual UCM commands is forthcoming.
To recap, the key things to remember before projects ship are:
- Projects are a codebase abstraction for defining libraries and services
- Projects enable a branch-based developer workflow
- Projects open the door for pull requests via "contributor branches"
So consider this is your notice: this is a big change! 🍾 We know it will entail some growing pains and have a few rough edges to start. After all, the team has basically been creating a code package manager, dependency system, changelog, code browsing, and collaboration workflow from the ground up. 🤘 Thanks for trying out new things with us!