# Names for projects

## Question

Idea: contributor branches are just branches with names of the form `@unison/base:@tstat:feat`. Nothing special as UCM is concerned but on `push`, Share will pick apart the `@tstat:feature` branch name, recognize that this is a push to travis' contributor branch, and store that branch in Travis' codebase.

Does that require revisiting a whole bunch of stuff in the UCM schema that was worked out, or does it just work?

Concern: needing to stash the username in this stringy branch name.
Concern: do we intend that users will have to put a `@tstat:` in front of all their branch names?

Idea: contributor branches are unprefixed with your username, but when you push to Share, if you don't have access, it will add `@tstat:` to the front of the branch name. And this is also set up as the default push target so it'll just happen once and then just work after that.

Limitation is you might have feature branch name that collides with the maintainers. But this probably isn't a big deal.

Idea: all branches on Share are prefixed with contributor name. (Don't like this for long-lived feature branches with multiple contributors)
Idea: @maintainer:main

Thought: existing schema works perfectly fine if we just name contributor project forks. Really no issues with this. Maybe it's even a feature since it's more like the GitHub model.

Right now, contributor branches have a parent project which has a name.

**Proposal**: Project name can be anything as far as UCM is concerned. No structure is assumed, except that `@` at the start indicates a project on Share (rather than local only). Of course, UCM can enfore whatever regex to prevent nonsense like `#$/` as a project name.

When `@tstat` creates a contributor branch of `@unison/base`, its project name is still just `@unison/base`, both locally, and on Share when pushed.

If someone else wants to check out that contributor branch, they'll do:

project.switch @tstat/@unison/base:main

What does this do?

1. No local branch called `@tstat/@unison/base:main`
2. Ask Share for branch `@tstat/@unison/base:main`
3. Download it and cd to it

@tstat/@unison/base:main> project.create-branch topic
@tstat/@unison/base:topic> ... hack hack hack
@tstat/@unison/base:topic> project.push @me/mybasefork:topic
@tstat/@unison/base:topic> project.push 
  # <implied to be @me/@tstat/@unison/base:topic>

Another example:

project.switch @unison/base:main

1. No local project called `@unison/base:main`
2. Ask Share for project `@unison/base:main`
3. Download it and cd to it

@unison/base:main> project.create-branch topic
@unison/base:topic> ... hack hack hack
@unison/base:topic> project.push @tstat/mybasefork:topic
@unison/base:topic> project.push 
  # <implied to be @tstat/@unison/base:topic>

This all seems fine. UCM doesn't care what projects are called (except that it assumes project names starting with `@` are references to projects on Share instead of a local-only project).

**Concern:** does this prevent us from having pretty urls for contributor branches, such as:

share.unison-lang.org/@unison/base/contrib/@tstat/feat1

or maybe

share.unison-lang.org/@tstat/contrib/@unison/base/feat1

Issue is: if project name and branch name are both variable length, having multiple segments, how does Share tell where the project name ends and the branch name begins? This isn't really an issue for UCM, since it uses `:` to separate branch name from project name. But it will be an issue for URLs on Share.

Missing info from Simon: what URLs on Share are affected by this? Is it just the contributor branches URL?

**Possible solutions:**

1. The branch name is always the last `/`-separated segment, and branch names can't have slashes. Easy to enforce in Share and in UCM.
* Seems ok, easy to do for now. Though people often do `topics.blah` as a feature branch name.
2. We escape slashes in the project name, so that the first slash marks the end of the project name and the beginning of the branch name.
* Alternately, you can escape slashes in the branch name
* Downside is we get ugly urls, but it's just for contributor branches.
* User can give a better name, but having to name your contrib branch fork is an annoying and often pointless decision (which must then be communicated to collaborators)
3. We use `/;/` to separate the project name from the branch name.
* This seems ok too
* `share.unison-lang.org/@tstat/@unison/base/;/feature1`
4. Contributor branches belong to a nameless project - their name is null, and they are displayed as having the same name as their merge target.
* Also seems okay, but would require some reworking of schema in Share and possibly UCM.
* Could this just be a thing on Share? It ignores project names for contributor branches (merge target has a different project id than self)?
5. On Share database, there's an index from (project name ++ branch name) to a branch hash. And we require that their concatenation be unique when creating or renaming branches.
* Now we don't care where the project ends and the branch begins, there's just and endpoint that takes their concatenation and resolves it.
* In practice, probably not much of a limitation.

**Proposal 1:**

**Proposal 2:** escape slashes in project name, so that contributor branches get an ugly url unless the user picks a nicer name by doing a `project.push @pchiusano/mybase`. The downside of

share.unison-lang.org/@unison/base

**Proposal 3:** In URLs, we put a `/;/` in between the project name and the branch name.

share.unison-lang.org/@tstat/@unison/base/;/main

share.unison-lang.org/@unison/base/contrib/@tstat/;/feat1

**Proposal 4:** contributor branches belong to a nameless project on share (with a null project name)

This means that all your contributor branches with the same upstream project will be part of the same nameless project and will need to have distinct branch names. This doesn't seem like a limitation.

It does mean the UCM schema may have to change to follow suit.

---

Incoherent notes

On Share, contributor branches are identified not by project name, but by merge target, user, and branch. They could literally have a null project name (it’s implied to inherit the project name from the default merge target). This view is consistent with the url scheme, which will put contributor branches for @unison/base somewhere like

(this is Travis’ fork of the main branch of @unison/base)

... @unison/base/contrib/@tstat/@unison/@blah/feat1

In UCM, the project name for a contributor branch could literally be @tstat/@unison/base. Can be nullable. When pushing, Share will be ignoring this name anyway.

So you could still support the syntax

project.switch @tstat/@unison/base:feature1