ethos

Overview

Friendshipper is designed to be a one-stop-shop for all nontechnical users’ source control needs. For Unreal projects, it essentially replaces workflows that UGS and P4V support.

Features

Repo Requirements

Feature branches

Limitations

Setup

You will need:

If using the editor/engine binary download features, you will also need:

Upon first launch of Friendshipper, you will be prompted to fill in this information. You can always update it in the Preferences page later.

Quick Submit

One of the main drawbacks of Git in a large team environment is the requirement to be on latest to submit changes. To overcome this limitation, Friendshipper submits changes through an alternate submission path that leverages Github’s Merge Queue feature. This means that Friendshipper is tightly integrated with GitHub’s feature set, but it achieves parity with traditional Perforce workflows in the sense that users can submit files at any given time, as long as it hasn’t changed upstream and other users haven’t locked it.

The way this works:

  1. The user initiates a submit
  2. A snapshot is saved in case anything goes wrong, the user won’t lose any work
  3. A new branch is created with all the changes
  4. The changes are commited to the new branch
  5. A temporary worktree branch is created, with all the same changes
  6. Latest is fetched from upstream trunk and merged into the worktree branch
  7. The worktree branch is pushed up to the remote
  8. A new PR is opened to merge the change into the trunk branch
  9. The PR is added to the merge queue
  10. Once the PR passes all merge checks, it’s merged into trunk

Because the Quick Submit process leaves the user on a leaf branch, Friendshipper uses the Sync operation to switch the user back to the trunk branch if they’re not on it already.

Quick Submit always sends to the target branch set in Preferences. The submit button and the colored mode badge (one color per target branch) read “Quick Submit to ". The preview names the target and says whether it merges via the merge queue or directly. If you're on a different target branch (for example on `main` while the target is `content-main`), Quick Submit is blocked and a red banner offers "Switch to " (or "Sync to " when you're on a Quick Submit branch) and "Open Preferences".

It should be noted that this process is mainly intended to be used by nontechnical users, or for content-only submits. Engineers may want to have more control over their submission process and are empowered to do so.

Submit to branch

On a branch that is neither a target branch nor a Quick Submit branch, the submit page offers Submit to branch. A banner appears when the branch was not created by Friendshipper. Submit to branch commits the selected files, then fast-forward pushes to origin/<branch>, but only if origin has not changed since the up-to-date check. It never force-pushes, and a pre-submit snapshot is kept.

Unreal Plugin

Unreal requires tight integration with whatever source control provider you’re using for your repo, so Friendshipper has a plugin to facilitate this. See the plugin page for installation documentation.