Document updating,building, and running WebIDE and VS Code server

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Work on this issue
• Close this issue

We created many projects/artefacts/processes during our initial 3-month investigation. These are not always properly documented or the documentation is out of date.

This is an umbrella issue for all MRs that will update the documentation. The main problem is that there is no natural SSOT place for all this documentation to live. Most of it is scattered across several projects.

I see three categories of documentation:

• Updating dependencies
• Building WebIDE and VS Code server
• Running WebIDE and VS Code server

Dependency diagram

graph TD
A[gitlab-org/gitlab] --> B[gitlab-web-ide]
B --> C[gitlab-web-ide-vscode-fork]
C --> D[MSFT's VS Code repo]
E[gitlab-rd-web-ide-docker] --> C

• gitlab-org/gitlab - https://gitlab.com/gitlab-org/gitlab
• gitlab-web-ide - https://gitlab.com/gitlab-org/gitlab-web-ide
• gitlab-rd-web-ide-docker - https://gitlab.com/gitlab-com/create-stage/editor-poc/remote-development/gitlab-rd-web-ide-docker
• gitlab-web-ide-vscode-fork - https://gitlab.com/gitlab-org/gitlab-web-ide-vscode-fork
• MSFT's VS Code repo - https://github.com/Microsoft/vscode

Updating dependencies

• Update VS Code version in our fork
  • There is documentation of how I've made the last update gitlab-web-ide-vscode-fork!11 (closed)
  • There is a comment from @cwoolley-gitlab gitlab-web-ide-vscode-fork#5 (comment 1104247190)
  • There's also an alternative process for updating that we are considering gitlab-web-ide-vscode-fork#5 (comment 1108948684)
  • There is no clear option for updating. Up to date documentation is not present. We'll have to re-open this topic when there is the next VS Code update /cc @cwoolley-gitlab @pslaughter
• Update VS Code build (from fork) in the gitlab-web-ide project
  • Example MR gitlab-web-ide!62 (merged)
  • There is a paragraph in our dev documentation that has a similar topic https://gitlab.com/gitlab-org/gitlab-web-ide/-/tree/main/docs/dev#setup-integrating-with-candidate-vs-code-build
• Update WebIDE version in the main gitlab-org/gitlab project
  • We've got documentation on how to publish the gitlab-web-ide package to npm https://gitlab.com/gitlab-org/gitlab-web-ide/-/tree/main/docs/dev#publishing
  • I don't think we documented how to update npm package in the main gitlab-org/gitlab project
• Update server version in the gitlab-rd-web-ide-docker project
  • We have a flag --ignore-version-mismatch which can work as temporary workaround, although not recommended
  • While building the Docker image, we will pass(changes need to be done) a VS Code version. Thus when a new version is released, we would need to update the VS Code version and build a newer version of the image. (details)

Building WebIDE and VS Code server

• The gitlab-web-ide-vscode-fork local build process is documented in Contribution guide, linked from readme https://gitlab.com/gitlab-org/gitlab-web-ide-vscode-fork/-/blob/main/GL_CONTRIBUTING.md#build
• The gitlab-web-ide build process is documented in developer documentation https://gitlab.com/gitlab-org/gitlab-web-ide/-/tree/main/docs/dev#scripts
  • I think it should move to README

Running WebIDE and VS Code server

• The fact that WebIDE example is deployed to review apps might not be visible enough in the gitlab-web-ide README https://gitlab.com/gitlab-org/gitlab-web-ide - This is a key point for any person learning about this category for the first time
• The local setup for gitlab-web-ide is well explained in https://gitlab.com/gitlab-org/gitlab-web-ide/-/blob/main/docs/dev/README.md#setup maybe we should also put it in the normal README, not docs/dev README
• Running the gitlab-rd-web-ide-docker is well described in README https://gitlab.com/gitlab-com/create-stage/editor-poc/remote-development/gitlab-rd-web-ide-docker#usage
• Explaining how RDE WebIDE and VS Code Server work together - There is outdated documentation (still using VS Codium) in https://gitlab.com/gitlab-org/gitlab-web-ide/-/blob/main/docs/dev/vscode-server.md but most of the knowledge is spread across many issues
  • Fixed in docs: update server documentation (gitlab-web-ide!64 - merged)

/cc @ashrafkhamis