Skip to content

Use patch strategy instead of force pushing to main

Our current process is based on rebasing on VS Code main and then force pushing the result to our main. https://gitlab.com/gitlab-org/gitlab-web-ide-vscode-fork/-/blob/main/GL_FORK_PROCESS.md

This issue proposes using a "patch" approach instead when our repository only contains a list of patches that define our customizations to the VS Code repository.

I created a video comparing the two approaches https://youtu.be/KMMuDiqYezg (sorry for the quite voice, I was in a coworking space)

The quilt patch approach is stored in patch-main branch https://gitlab.com/gitlab-org/gitlab-web-ide-vscode-fork/-/tree/patch-main

The patch process is roughly described in https://gitlab.com/gitlab-org/gitlab-web-ide-vscode-fork/-/blob/patch-main/GL_CONTRIBUTING.md#patches

Main motivation for trying the different approach

  • After I updated the VS Code version from 1.69.1 to 1.71.1 (1900 commits) with the force push strategy, I saw an overwhelming space for human error during the update.

The benefits of using the patch strategy (compared to rebase):

  • After applying all patches, you can see all the changed files in VS Code repo by running git status
    • image
  • Changes like updating our build scripts and README are completely separated from patching the VS Code (it's in a different folder)
  • It's possible to create an MR for updating VS Code from one version to another. You can then review what diffs changed and how and comment on that change. This is not possible with the rebase. With the rebase we can't use GitLab for reviews
  • It's not necessary to rebase existing MRs after a version upgrade unless they are changing the same patch that has been changed during the upgrade because of a merge conflict
  • Trivial rollbacks, less space for human error
  • Changing patches is trivial; in the rebase strategy, we change the commit by interactive rebase and then we have to force push to master
  • Contributing to the project doesn't require maintainer permissions (because the change can be reviewed and merged without force push to main). Otherwise, if there's a community contribution that rebases the main, there would be a lot of manual work that the maintainer has to do locally to verify that the changes are as expected.

The drawbacks of using the patch strategy:

  • pure quilt conflict resolution requires more manual effort
    • we could work around this by having a process for complicated merge conflicts
      1. you create a temporary commit/stash from the original patches
      2. use this commit/stash for conflict resolution with the new VS Code version
      3. take a quilt snapshot of the resolved version (this generates an updated patch)
  • before patching files in the VS Code repository, you have to tell quilt that you are going to patch them (so it can take snapshot before and after and generate the patch), in the "rebase" strategy, you just commit what you've changed

Quilt is used by Debian and code-server

I'm not married to quilt specifically, and I'm happy with any patch solution. If quilt looks like an unnecessary complexity, we can replicate this strategy with just git diff and git apply same as VSCodium does it https://github.com/VSCodium/vscodium/blob/master/docs/build.md#patch-update-process

Edited by Tomas Vik