Skip to content

Latest commit

 

History

History
93 lines (59 loc) · 6.41 KB

DEVELOPMENT.md

File metadata and controls

93 lines (59 loc) · 6.41 KB
Raw

How to Add an Extension?

Prerequisites

  • Node.js (we use Node 18)
  • Ubuntu Linux (Windows and macOS work fine for adding extensions, but extensions are always tested on Ubuntu, so they only need to build correctly there)

To add an extension to this repo, clone the repo1, install the dependencies2, and use the following command:

node add-extension.js ext.id https://github.com/x/y --optional arg

Or, if the extension you want to add exists on the MS Marketplace3, you can simply feed the script the item URL (this automatically populates both the ID and git repository).

node add-extension.js https://marketplace.visualstudio.com/items?itemName=ext.id --optional arg

All of the arguments are also valid options if you add the extension manually to the JSON file directly. You can find them in the extension-schema.json file.

See Publishing options below for a quick guide.

⚠️ Some extensions require additional build steps, and failing to execute them may lead to a broken extension published to Open VSX. Please check the extension's scripts section in the package.json file to find such steps; usually they are named build or similar. In case the build steps are included in the vscode:prepublish script, they are executed automatically, so it's not necessary to mention them explicitly. Otherwise, please include them in the prepublish value, e.g. "prepublish": "npm run build".

Click the button below to start a Gitpod workspace where you can run the scripts contained in this repository:

Open in Gitpod

Publishing Options

The best way to add an extension here is to open this repository in Gitpod and add a new entry to extensions.json.

To test, run:

GITHUB_TOKEN=your_pat EXTENSIONS=rebornix.ruby SKIP_PUBLISH=true node publish-extensions.js

GITHUB_TOKEN

For testing locally, we advise you to provide a GitHub Personal Access Token for release and file resolution in our scripts. Otherwise, publishing can work in our workflow but fail for you locally and vice-a-versa.

You can create one in your GitHub Token Settings. This token does not require any special permissions.

    // Unique Open VSX extension ID in the form "<publisher>.<name>"
    "rebornix.ruby": {
      // Repository URL to clone and publish from. If the extension publishes `.vsix` files as release artifacts, this will determine the repo to fetch the releases from.
      "repository": "https://github.com/redhat-developer/vscode-yaml"
    },

How do extensions get updated?

The publishing job auto infers the latest version published to the MS Marketplace3 using vsce and then tries to resolve a vsix file using a GitHub Release asset or, when one doesn't exist, it tries to find a commit to a build associated with the version using tags and commits around the last MS Marketplace3 updated date.

How are Extensions Published?

Every night (Monday-Friday) at 03:03 UTC, a GitHub Actions workflow goes through all entries in extensions.json, and checks for every entry whether it needs to be published to https://open-vsx.org or not (whether it is up-to-date).

The publishing process can be summarized like this:

  1. git clone "repository"

If a custom property is provided, then every command from the array is executed. Otherwise, the following 2 steps are executed: (steps 4 and 5 are executed in both cases)

  1. npm install (or yarn install if a yarn.lock file is detected in the repository)
  2. ("prepublish")
  3. (ovsx create-namespace "publisher" if it doesn't already exist)
  4. ovsx publish (with --yarn if a yarn.lock file was detected earlier)

See all ovsx CLI options here.

Environment Variables

Custom commands such as prepublish and the ones inside the custom-array receive a few environment variables in order to perform advanced tasks such as executing operations based on the extension version.

Following environment variables are available:

  • EXTENSION_ID: the extension ID, e.g. rebornix.ruby
  • EXTENSION_PUBLISHER: the extension publisher, e.g. rebornix
  • EXTENSION_NAME: the extension name, e.g. ruby
  • VERSION: the version of the extension to publish, e.g. 0.1.0
  • MS_VERSION: the latest version of the extension on the MS Marketplace3, e.g. 0.1.0
  • OVSX_VERSION: the latest version of the extension on Open VSX, e.g. 0.1.0

Footnotes

  1. git clone https://github.com/open-vsx/publish-extensions/ ↩

  2. npm i ↩

  3. The Microsoft Visual Studio Code Extensions Marketplace ↩ ↩2 ↩3 ↩4