docs(MAINTAINING): add section for syncing VS Code upstream

Author: jsjoeio

docs/CONTRIBUTING.md

@@ -2,23 +2,22 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 # Contributing
 
-- [Contributing](#contributing)
-  - [Requirements](#requirements)
-    - [Linux-specific requirements](#linux-specific-requirements)
-  - [Creating pull requests](#creating-pull-requests)
-    - [Commits and commit history](#commits-and-commit-history)
-  - [Development workflow](#development-workflow)
-    - [Updates to VS Code](#updates-to-vs-code)
-    - [Build](#build)
-    - [Help](#help)
-  - [Test](#test)
-    - [Unit tests](#unit-tests)
-    - [Script tests](#script-tests)
-    - [Integration tests](#integration-tests)
-    - [End-to-end tests](#end-to-end-tests)
-  - [Structure](#structure)
-    - [Modifications to VS Code](#modifications-to-vs-code)
-    - [Currently Known Issues](#currently-known-issues)
+- [Requirements](#requirements)
+  - [Linux-specific requirements](#linux-specific-requirements)
+- [Creating pull requests](#creating-pull-requests)
+  - [Commits and commit history](#commits-and-commit-history)
+- [Development workflow](#development-workflow)
+  - [Updates to VS Code](#updates-to-vs-code)
+  - [Build](#build)
+  - [Help](#help)
+- [Test](#test)
+  - [Unit tests](#unit-tests)
+  - [Script tests](#script-tests)
+  - [Integration tests](#integration-tests)
+  - [End-to-end tests](#end-to-end-tests)
+- [Structure](#structure)
+  - [Modifications to VS Code](#modifications-to-vs-code)
+  - [Currently Known Issues](#currently-known-issues)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -105,11 +104,11 @@ If changes are made and merged into `main` in the [`cdr/vscode`](https://github.
 }
 ```
 
-1. From the code-server **project root**, run `yarn install`.
+2. From the code-server **project root**, run `yarn install`.
    Then, test code-server locally to make sure everything works.
-1. Check the Node.js version that's used by Electron (which is shipped with VS
+3. Check the Node.js version that's used by Electron (which is shipped with VS
    Code. If necessary, update your version of Node.js to match.
-1. Open a PR
+4. Open a PR
 
 > Watch for updates to
 > `vendor/modules/code-oss-dev/src/vs/code/browser/workbench/workbench.html`. You may need to

docs/MAINTAINING.md

@@ -19,6 +19,7 @@
     - [Docker](#docker)
     - [Homebrew](#homebrew)
     - [npm](#npm)
+- [Syncing with Upstream VS Code](#syncing-with-upstream-vs-code)
 - [Testing](#testing)
 - [Documentation](#documentation)
   - [Troubleshooting](#troubleshooting)
@@ -126,8 +127,7 @@ the issue.
 
 ### Merge strategies
 
-For most things, we recommend the **squash and merge** strategy. If you're
-updating `lib/vscode`, we suggest using the **rebase and merge** strategy. There
+For most things, we recommend the **squash and merge** strategy. There
 may be times where **creating a merge commit** makes sense as well. Use your
 best judgment. If you're unsure, you can always discuss in the PR with the team.
 
@@ -215,6 +215,18 @@ We publish code-server as a npm package [here](https://www.npmjs.com/package/cod
 
 This is currently automated with the release process.
 
+## Syncing with Upstream VS Code
+
+The VS Code portion of code-server lives under [`cdr/vscode`](https://github.com/cdr/vscode). To update VS Code for code-server, follow these steps:
+
+1. `git checkout -b vscode-update` - Create a new branch locally based off `main`
+2. `git fetch upstream` - Fetch upstream (VS Code)'s latest `main` branch
+3. `git merge upstream/main` - Merge it locally
+   1. If there are merge conflicts, fix them locally
+4. Open a PR merging your branch (`vscode-update`) into `main` and add the code-server review team
+
+Ideally, our fork stays as close to upstream as possible. See the differences between our fork and upstream [here](https://github.com/microsoft/vscode/compare/main...cdr:main).
+
 ## Testing
 
 Our testing structure is laid out under our [Contributing docs](https://coder.com/docs/code-server/latest/CONTRIBUTING#test).