coder · nhooyr · Jun 4, 2020 · Jun 4, 2020 · Jun 4, 2020
diff --git a/README.md b/README.md
@@ -18,6 +18,8 @@ Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and a
 
 For a full setup and walkthrough, please see [./doc/guide.md](./doc/guide.md).
 
+### Quick Install
+
 We have a [script](./install.sh) to install code-server for Linux and macOS.
 
 It tries to use the system package manager if possible.
@@ -36,14 +38,10 @@ curl -fsSL https://code-server.dev/install.sh | sh
 
 The install script will print out how to run and start using code-server.
 
-If you believe an install script used with `curl | sh` is insecure, please give
-[this wonderful blogpost](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) by
-[sandstorm.io](https://sandstorm.io) a read.
+### Manual Install
 
 Docs on the install script, manual installation and docker image are at [./doc/install.md](./doc/install.md).
 
-We also highly recommend reading the [FAQ](./doc/FAQ.md) on the [Differences compared to VS Code](./doc/FAQ.md#differences-compared-to-vs-code).
-
 ## FAQ
 
 See [./doc/FAQ.md](./doc/FAQ.md).

diff --git a/ci/README.md b/ci/README.md
@@ -22,10 +22,11 @@ Make sure you have `$GITHUB_TOKEN` set and [hub](https://github.com/github/hub)
    the updated version.
    1. Summarize the major changes in the release notes and link to the relevant issues.
 4. Wait for the artifacts in step 2 to build.
-5. Run `yarn release:github-assets` to download the `release-packages` artifact and then
+5. Run `yarn release:github-assets` to download the `release-packages` artifact and
    upload them to the draft release.
 6. Run some basic sanity tests on one of the released packages.
-7. Make sure the github release tag is the commit with the artifacts.
+7. Make sure the github release tag is the commit with the artifacts. This is a bug in
+   `hub` where uploading assets in step 5 will break the tag.
 8. Publish the release and merge the PR.
    1. CI will automatically grab the artifacts and then:
       1. Publish the NPM package from `npm-package`.

diff --git a/ci/build/release-github-assets.sh b/ci/build/release-github-assets.sh
@@ -11,7 +11,7 @@ main() {
   source ./ci/lib.sh
 
   download_artifact release-packages ./release-packages
-  local assets=(./release-packages/code-server*"$VERSION"*{.tar.gz,.deb,.rpm})
+  local assets=(./release-packages/code-server*"$VERSION"*{.tar.gz,.zip,.deb,.rpm})
   for i in "${!assets[@]}"; do
     assets[$i]="--attach=${assets[$i]}"
   done

diff --git a/doc/FAQ.md b/doc/FAQ.md
@@ -6,6 +6,7 @@
 - [How can I reuse my VS Code configuration?](#how-can-i-reuse-my-vs-code-configuration)
 - [Differences compared to VS Code?](#differences-compared-to-vs-code)
 - [How can I request a missing extension?](#how-can-i-request-a-missing-extension)
+- [How do I configure the marketplace URL?](#how-do-i-configure-the-marketplace-url)
 - [Where are extensions stored?](#where-are-extensions-stored)
 - [How is this different from VS Code Codespaces?](#how-is-this-different-from-vs-code-codespaces)
 - [How should I expose code-server to the internet?](#how-should-i-expose-code-server-to-the-internet)
@@ -22,6 +23,7 @@
 - [Blank screen on iPad?](#blank-screen-on-ipad)
 - [Isn't an install script piped into sh insecure?](#isnt-an-install-script-piped-into-sh-insecure)
 - [How do I make my keyboard shortcuts work?](#how-do-i-make-my-keyboard-shortcuts-work)
+- [Differences compared to Theia?](#differences-compared-to-theia)
 - [Enterprise](#enterprise)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -78,8 +80,15 @@ point to the .vsix file.
 
 See below for installing an extension from the cli.
 
-If you have your own custom marketplace, it is possible to point code-server to it by setting
-`$SERVICE_URL` and `$ITEM_URL` to point to it.
+## How do I configure the marketplace URL?
+
+If you have your own marketplace that implements the VS Code Extension Gallery API, it is possible to
+point code-server to it by setting `$SERVICE_URL` and `$ITEM_URL`. These correspond directly
+to `serviceUrl` and `itemUrl` in VS Code's `product.json`.
+
+While you can technically use Microsoft's marketplace with these, please do not do so as it
+is against their terms of use. See [above](#differences-compared-to-vs-code). These variables
+are most valuable to our enterprise customers for whom we have a self hosted marketplace product.
 
 ## Where are extensions stored?
 
@@ -272,6 +281,19 @@ This will install a Chrome PWA and now all keybindings will work!
 
 For other browsers you'll have to remap keybindings unfortunately.
 
+## Differences compared to Theia?
+
+[Theia](https://github.com/eclipse-theia/theia) is a browser IDE loosely based on VS Code. It uses the same
+text editor library named [Monaco](https://github.com/Microsoft/monaco-editor) and the same
+extension API but everything else is very different. It also uses [open-vsx.org](https://open-vsx.org)
+for extensions which has an order of magnitude less extensions than our marketplace.
+See [#1473](https://github.com/cdr/code-server/issues/1473).
+
+You can't just use your VS Code config in Theia like you can with code-server.
+
+To summarize, code-server is a patched fork of VS Code to run in the browser whereas
+Theia takes some parts of VS Code but is an entirely different editor.
+
 ## Enterprise
 
 Visit [our enterprise page](https://coder.com) for more information about our

diff --git a/doc/guide.md b/doc/guide.md
@@ -25,6 +25,8 @@ Further docs are at:
 - [FAQ](./FAQ.md) for common questions.
 - [CONTRIBUTING](../doc/CONTRIBUTING.md) for development docs
 
+We highly recommend reading the [FAQ](./doc/FAQ.md) on the [Differences compared to VS Code](./doc/FAQ.md#differences-compared-to-vs-code) before beginning.
+
 We'll walk you through acquiring a remote machine to run `code-server` on
 and then exposing `code-server` so you can securely access it.
 

diff --git a/doc/install.md b/doc/install.md
@@ -4,7 +4,7 @@
 
 - [install.sh](#installsh)
   - [Flags](#flags)
-  - [Detect Reference](#detect-reference)
+  - [Detection Reference](#detection-reference)
 - [Debian, Ubuntu](#debian-ubuntu)
 - [Fedora, CentOS, RHEL, SUSE](#fedora-centos-rhel-suse)
 - [Arch Linux](#arch-linux)
@@ -42,7 +42,7 @@ If you believe an install script used with `curl | sh` is insecure, please give
 [this wonderful blogpost](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) by
 [sandstorm.io](https://sandstorm.io) a read.
 
-If you'd still prefer manual installation despite the below [detect reference](#detect-reference) and `--dry-run`
+If you'd still prefer manual installation despite the below [detection reference](#detection-reference) and `--dry-run`
 then continue on for docs on manual installation. The [`install.sh`](../install.sh) script runs the _exact_ same
 commands presented in the rest of this document.
 
@@ -56,7 +56,7 @@ commands presented in the rest of this document.
 - `--version=X.X.X` to install version `X.X.X` instead of latest.
 - `--help` to see full usage docs.
 
-### Detect Reference
+### Detection Reference
 
 - For Debian, Ubuntu and Raspbian it will install the latest deb package.
 - For Fedora, CentOS, RHEL and openSUSE it will install the latest rpm package.