Skip to content

RFC: Proposal to improve VSCode upgrade process

Summary

The proposed VSCode fork upgrade process aims to optimize time, flatten the learning curve to execute the process, run more frequent upgrade cycles, and assign a clear DRI for each cycle. The plan includes separating the commits that modify the upstream project from commits related to release management, running scheduled jobs to detect new VSCode versions, automating the creation of an "upgrade MR", automating the creation of integration MRs for exploratory tests, publishing VSCode releases from a CI job, and parameterizing the VSCode release in the tools-injector build.

Goals

  • Reduce the time needed to upgrade the VSCode Fork by identifying opportunities to automate one or more steps.
  • Flatten the learning curve to participate in the upgrade process by writing detailed documentation and automating part of the process.
  • Run more frequent upgrade cycles. Reduce the time between upgrades from 3-4 months to monthly or bi-monthly.
  • Assign a clear DRI to run the upgrade process on every cycle.

Detailed plan

The following flowchart diagram goes over the new upgrade process as described in the following sections:

flowchart LR
    subgraph SUB_A["Actor: CI - Detect new VSCode release"]
    direction TB
    A[[job: check-upstream-releases]] -->B{new release?}
    B --> |yes| C[create upgrade issue]
    B --> |no| C2[nothing to do]
    C --> D[mention upgrade DRI]
    end
    subgraph SUB_B["Actor: Upgrade DRI - Submit upgrade MR"]
    direction TB
    E[[run create-upgrade-mr]] --> F[Resolve merge conflicts]
    F --> G[Submit MR and VSCode upgrade template]
    G --> H[Wait for successful pipeline]
    end
    subgraph SUB_C["Actor: CI - Create integration MRs"]
    direction TB
    I[job: publish-tools-injector-dev-image] --> J[job: create web-ide integration MR]
    J --> K[job: create workspaces integration MR]
    end
    subgraph SUB_D["Actor: Upgrade DRI - Perform exploratory testing"]
    direction TB
    L[Test new VSCode release in the Web IDE] --> M[Test new VSCode release in Workspaces]
    M --> N[Publish exploratory test results in the Web IDE]
    N --> P[Request maintainer review]
    P --> Q[Merge changes to `main`]
    end
    subgraph SUB_E["Actor: CI - Release VSCode artifact"]
    direction TB
    R[[job: create-release]] --> S[create release tag]
    S --> |in release tag pipeline| T[publish package to registry]
    T -->  U[create release page]
    end
    SUB_A --> SUB_B
    SUB_B --> SUB_C
    SUB_C --> SUB_D
    SUB_D --> SUB_E

Isolate commits that modify the upstream repository

Context

The commits in the VSCode Fork repository has several purposes:

  • Modify the upstream VSCode project.
  • Set up GitLab CI pipeline, local development tools, scripts to generate releases, and GitLab-specific documentation.
  • Contains the tools-injector implementation used by the Workspaces project.

Every time that we upgrade the VSCode fork, we have to review every commit in the repository regardless of its purpose. This is an error-prone, and cognitively heavy operation that makes the upgrade process very complex.

Proposal

Separate the commits in the VSCode fork repository into two groups:

  • Commits that modify the VSCode upstream project.
  • Commits related to the build process, release management, GitLab-specific documentation, automation, etc.

We will follow the strategy of converting the commits that modify the VSCode upstream project into patch files as describe Use patch strategy instead of force pushing to ... (#5 - closed). The vscode upstream project will become a submodule of the VSCode Fork repository. When producing a new build of the VSCode Fork, it happens in the following way:

  1. The vscode submodule is initialized and reset to the latest stable revision supported and tested by GitLab.
  2. The patch files that contain the modifications to the vscode upstream project are applied to the submodule using git apply .
  3. The scripts that produce the build artifacts are executed.

The patch-based strategy has the following advantages and disadvantages:

  1. Advantage 1: Unlike the current VSCode Upgrade process, we don't have force push to the main to publish an upgrade. This significantly simplifies the code review process.
  2. Advantage 2: It reduces the size of the review MR to only the merge conflicts that we might encounter when applying the patch files.
  3. Advantage 3: It's easy to automate the creation of "Upgrade Merge Requests" because it only requires checking out a newer tag in the vscode upstream submodule.
  4. Disadvantage 1: Reviewing changes to patch files is cumbersome. Changing patch files is even more so. Given the number of changes we’ve applied to upstream, managing patch files might not be a scalable approach.

Run scheduled jobs that detect new VSCode versions and create an upgrade issue

Context

Identifying new VSCode releases and scheduling fork upgrades is not a predictable and standardized process. VSCode upgrades are only scheduled where the IDE group is interested in a feature included in a new release. Since there isn't an upgrade issue created in advanced, upgrading the VSCode fork is not taken into consideration during the high-level planning phase.

There isn’t an issue template that describes the acceptance criteria to approve an upgrade or lists the steps to run the process.

Proposal

  • Implement a scheduled CI job that identifies new VSCode releases and creates an upgrade issue.
  • Create an issue template that describes instructions to run the entire VSCode upgrade process.

Benefits

  • Create a predictable VSCode fork upgrade cadence and allow stakeholders to consider this task in the high-level planning meetings.
  • Standardize the acceptance criteria and the instructions to run a VSCode fork upgrade.
  • Flattens the learning curve to run the upgrade process.

Write a script to automate the creation of an “upgrade MR”

Context

Creating an MR to review a VSCode fork upgrade requires running several git commands. Most of these commands can be automated except for resolving merge conflicts that arise from applying GitLab’s customizations.

Proposal

  • Create a script or program that the “Upgrade DRI” runs in their local environment. The script creates the necessary git branches, and tags, and only requires the intervention of the DRI to resolve merge conflicts.
  • Create an “Upgrade MR” template that instructs the DRI about the next steps during the upgrade process.

Benefits

  • Flattens the learning curve to run the upgrade process.
  • Reduces human error by automating the steps that don’t require human intervention.

Create tools-injector development image

Context

The tools-injector is the container image used by Workspaces to start VSCode. There’s an ongoing project to move the code that builds and releases the tools-injector to a separate repository https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-tools. This project will simplify the VSCode Fork repository.

To facilitate the creating of integration MRs to test a new VSCode release in Workspaces, we have to create development images of the tools-injector that contains the new VSCode release.

Proposal

  • Trigger a downstream pipeline in the tools-injector repository that builds a container image that contains the new VSCode release for development purposes.

Benefits

  • Release development builds of the tools-injector to run exploratory testing.

Automate creating integration MRs to run exploratory tests in the Web IDE and Workspaces

Context

Testing a new version of VSCode in the Web IDE and Workspaces is complex. For workspaces, it entails creating a development Container image of the tools injector and testing it in a local kubernetes cluster. In the Web IDE, we should replace the production reference to VSCode release with a development one. Moreover, there aren’t documented instructions on how to do it. The expected outcome of the exploratory testing is unclear.

Proposal

  • Create a CI job that opens an MR to test a new VSCode fork version in the Web IDE project.
  • Create a CI job that opens an MR to test a new VSCode fork version in Workspaces.
  • Document the instructions to perform exploratory testing on both projects.

Benefits

  • Expedites the process of running exploratory tests for new VSCode versions.
  • Flattens the learning curve to run the upgrade process.

Publish VSCode releases from a CI job

Context

Currently, creating a VSCode fork release entails running a script in your local environment and pushing a tag to the remote repository. The entire process is automated which would save us considerable time during the upgrade process.

Proposal

  • Create a CI job that create a new tag for the latest VSCode release.
  • Create a CI job that pushes artifacts to the package registry for the most recent tag and also publish a new release page.

Benefits

  • Flattens the learning curve to run the upgrade process.
  • Reduces human error by automating the steps that don’t require human intervention.

Risks

[TODO: Work in progress]

Dependencies

GitLab Workspaces Tools is the new project where the tools-injector is hosted: https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-tools

Proposal updates

2024-06-11

  • The proposal has been updated to reflect the decision of adopting a patch-based strategy to manage changes to upstream as explained in #32 (comment 1944423529)
Edited by Enrique Alcántara