Handle possible merge conflicts during parallel work on same data repo

[strogonoff]

Currently, the app pushes directly to master. It doesn’t yet handle failed merges. If there are conflicting changes upstream, it will fail and will require the user to merge changes locally, inside app’s data repo (requiring Git CLI installation & familiarity with).

We could keep operating on master and help recover from merge errors with some fallback mechanism and good error reporting. E.g., if there is a conflict, we could do one of the following:

• Fail with an error and provide instructions on how to recover (downside: merge conflicts may be tricky to recover from, and data will remain on user’s machine only until the situation is resolved).
• Start a branch with a unique name and push changes there. Then, provide instructions, possibly have an IT-type role handle the merge (with or without the use of GitHub PRs).

In both cases, we should block user’s work until the conflict is resolved, to avoid piling up divergent changes.

We could also minimize the chance of merge conflicts:

• We could always operate in a unique branch for each editor.
• We could operate on personal forks instead of branches.
  • We could create forks automatically, but that ties us to GitHub, and GitHub API integration doesn’t go smooth at the moment (primarily due to OAuth issues).
  • We could require each editor to have personal fork which only they commit to. This approach is explored below.

Both cases require someone higher up (editor manager?) to handle merges into upstream. This could be a feature, offering a review workflow.

Using private forks

Users would work on private forks, reducing the chance of merge conflicts when user syncs up their changes.

Creating forks and handling merges into upstream could be the responsibility of whoever manages site editors. That person could also limit direct commit access for upstream repository.

In simplest version, the app could simply offer an option to specify repo URL. The app could also allow specifying two URLs, one for read-only upstream and one for private fork. Every editor would configure the app with their private fork.

In a more complex implementation, we could have optional YAML configuration (bundled with the app or fetched from somewhere) that specifies usernames and private fork URLs (supervisor-type role could have access to upstream URL). Depending on username entered by the editor in their app installation, the app would pick fork URL implicitly, providing smoother UX without an extra dialog.

[strogonoff]

Always-online algorithm

Pre-requisites:

• Give master push access to every author, but no force push access (GitHub’s protected branches feature?)

In Electron’s main, in background:

• Fetch origin/master frequently
• If failed due to network, send offline connection message to renderer
• If succeeded after previous network failure, send online connection message to renderer
• Commit frequently while the user makes changes in the app. Try to describe each commit descriptively
• Push local master to origin/master frequently
  • The app can self-regulate the frequency of commits & pushes, e.g. ramping it up if someone else appears to be working and pushing commits at the same time to reduce the probability of failed merge
• If push fails, fetch fresh origin/master and merge it in local master
• If merge succeeds, send data update message to renderer
• ⚠️ If merge fails, discard local changes. Reset to latest origin commit using this approach. Send data update message to renderer, have a flag indicating changes were lost

In Electron’s renderer, in GUI:

• Listen to offline connection message and lock GUI with a modal
• Listen to online connection message and unlock GUI if it’s locked
• Listen to data update message with each window’s ipcRenderer
• Make React components refetch data if new changes were fetched without merge conflict
  • Tricky: Text editing. Current implementation of text editor loses cursor position and undo history on rerender. If user is in the middle of text editing, and latest merge shows that another user changed the same text data field without merge conflict, we will have to notify the user and rerender, otherwise continued editing may cause subsequent merge conflicts and lost changes.
  • Tricky: Dialogs. If user A adds an object while user B has dialog open for adding or editing the same object, user B will not see the addition. (Case in point: Telephone Service, Service Restriction messages, etc.) Try to get rid of dialogs in favour of inline editing widgets.
• ⚠️ Show blocking modal with overlay in cases when local changes had to be discarded

Offline, with repository:

• Squash commits every couple of weeks, align with OB edition publication date

CC @ronaldtse:

I’m considering switching to the mode of collaboration described above. Feel free to ignore some implementation notes, but I hope it’s conceptually clear how it’d work.

Cost 1 is this will create a lot of commits right in the mainline branch, so someone would have to squash and rewrite history every now and then. it’s easier than constantly dealing with PRs, though.

Cost 2 is editors will have a chance of having some of their changes lost while editing, in case someone else changes the same field(s) as in yet-unpushed commits. The amount of changes lost would depend on how frequently the app commits and pushes, and how soon we lock the app if connection to Git repo goes down. Ideally we’d lock it soon, so it’ll be more or less an always-online app, similar to Google Docs.

Cost 3 is push access, which theoretically can create a DoS-like situation if a bad actor gains push access, but since force push will be tightly controlled this should be recoverable.

Cost 4 is performance hit, uncertain how well this would work on slower machines…

On plus side, this would avoid the need for pull request maintenance and make for a very smooth and natural collaboration feel. Curious what you think.