Hypermedia Branching Revamp

Problem

We want to support more fine-grained branching capabilities

Suggested Changes & Merges

Duplicate Documents

Specific Roles for Documents

Group-Owned Documents

Explicit Branching

Solution

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

Spaces

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:

Owner

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.

Conflicts

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.

Idea

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.

Containing:Problem

Solution

Spaces

Address Documents through "Spaces"

Backwards Compatibility

Duplicates and Branching

Space Permissions

Group Roles

Unsolved Problems

Suggested Changes and Merging

Conflicts

Idea

Published:6 mo. ago Sunday, June 2nd, 2024

Author:

z6MkqVqE...wS2RcgWp

First Version

Open in Mintter app