Hypermedia Branching Revamp


We want to support more fine-grained branching capabilities
Suggested Changes & Merges
Duplicate Documents
Specific Roles for Documents
Group-Owned Documents
Explicit Branching


This solution is a WIP, it does not cover all of the problems and use cases


This is a "space-centric" proposal, which means that groups and accounts will both be considered "Spaces". All permissions and branch definitions will be located on the space.
Side Note: The app currently makes a distinction between "Account" and "Profile", but I don't really understand the purpose of the distinction. Hopefully we can either clarify the meaning of these names, or merge them and just call everything an account, like I do in this document
Home document of Spaces are located directly on the entity, rather than the current model of linking to the home document, which causes several issues.
We would bring the Content Index feature of groups to accounts, so accounts can specify named documents/(branches).
For more details, see the starter project for spaces: Project: Group and Account Spaces

Address Documents through "Spaces"

We will migrate to the following URL format for documents:
Group namespace: hm://g/GROUP_ID/DOC_PATHNAME (technically we already support this format)
Account space: hm://a/ACCOUNT_ID/DOC_PATHNAME
This has the following advantages:
The permission and version is defined by the space and can change over time
The pathname results in a more readable URL
As with all hm:// URLs, they will be replicated under the https://hyper.media namespace.
We will continue to allow versions on these URLs, which refer to the version of the space.

Backwards Compatibility

We will deprecate the account variant URL format (these links may become slightly broken if a version is not specified) hm://d/DOC_ID?b=a/ACCT_ID
We will migrate the group variant URLs from hm://d/DOC_ID?b=g/GROUP_ID/PATH to hm://g/GROUP_ID/PATH
When referring to a raw document URL such as hm://d/ID, the document is implicitly in the owner space
Document URLs with a specific version are still allowed and are not considered deprecated.

Duplicates and Branching

With spaces, we can duplicate documents by referring to the same document ID from different path names
hm://g/GROUP_ID/my-doc => hm://d/DOC_ID?v=1
hm://g/GROUP_ID/my-duplicated-doc => hm://d/DOC_ID?v=2
We can branch documents with labeled branches using the @ symbol in the path name
hm://g/GROUP_ID/my-doc => hm://d/DOC_ID?v=1
hm://g/GROUP_ID/my-doc@fixing-typos => hm://d/DOC_ID?v=2
Now the UI can present this to the user as a main branch of my-doc and a named branch of fixing-typos. Both are in the same group space.

Space Permissions

On a group and an account, we can store additional permissions for the documents within them
docRoles: {
  pathName: {
    accountId1: Role.EDITOR,
    accountId2: Role.CONTRIBUTOR,
This will assign additional permissions to specific other accounts for specific group documents.
These roles include:
Editor: Account may write to the document and merge selected changes
Contributor: Comments and suggested changes from this account will be distributed alongside the branch
The docRoles in an account are only editable by the account owner. The docRoles in a group is only editable by the group owner and for any group members with the "admin" role
Note: the docRoles do not allow additional people to edit the home document of a space. This means the home document of an account may only be modified by that account. And the home document of a group may only be modified by the editors, admins, and owner of that group.

Group Roles

Groups already have an "owner" and an "editor" role. Owners can make any change to the group, and editors may make changes to any group content. We could revise these roles:
Editor: allowed to modify the home document, add and remove indexed documents, and modify the docRoles
Note: the docRoles edit could theoretically be limited to another role, but the editor already has permission to merge suggested changes from people for any group content, so they basically have this role already but this allows them to allow collaboration without having to manually merge every suggested change.
Administrator: allowed to add and remove editors
Contributor: Comments and suggested changes from this account will be distributed alongside the group

Unsolved Problems

Suggested Changes and Merging

Not sure how this will work with the new branching model. There are a few options I could come up with, but maybe @z6Mkg...A7cgt has some ideas.


When we have the version of the document specified in the group, we have an issue where two people may concurrently update the group index and one person will squash the changes from the other.
I have some ideas on how this could be addressed, but there are significant tradeoffs that we must consider.


One potential solution to these unsolved problems is to annotate changes with the branch they are intended for (which is the space ID and path name). If the person is allowed to modify that branch, the change will be automatically merged. The owner will be responsible for committing that change, and it could happen automatically. If the change author is not allowed to edit, the change is considered a suggested change.