Skip to content

Latest commit

 

History

History
73 lines (46 loc) · 6.57 KB

README.md

File metadata and controls

73 lines (46 loc) · 6.57 KB
Raw

Publish Extensions to Open VSX

Gitpod Ready-to-Code GitHub Workflow Status

A CI script for publishing open-source VS Code extensions to open-vsx.org.

When to Add an Extension?

A goal of Open VSX is to have extension maintainers publish their extensions according to the documentation. The first step we recommend is to open an issue with the extension owner. If the extension owner is unresponsive for some time, this repo (publish-extensions) can be used as a temporary workaround to esure the extension is published to Open VSX.

In the long-run it is better for extension owners to publish their own plugins because:

  1. Any future issues (features/bugs) with any published extensions in Open VSX will be directed to their original repo/source-control, and not confused with this repo publish-extensions.
  2. Extensions published by official authors are shown within the Open VSX marketplace as such. Whereas extensions published via publish-extensions display a warning that the publisher (this repository) is not the official author.
  3. Extension owners who publish their own extensions get greater flexibility on the publishing/release process, therefore ensure more accuracy/stability. For instance, in some cases publish-extensions has build steps within this repository, which can cause some uploaded plugin versions to break (e.g. if a plugin build step changes).

⚠️ We only accept extensions with an OSI-approved open source license here. If you want to have an extension with a proprietary or non-approved license published, please ask its maintainers to publish it.

How to Add an Extension?

To add an extension to this repo, add it to the extensions.json file. You can do this directly via GitHub using its web editor, or for a way simpler approach, which makes sure your extension also goes in the right place in the file, use the following command:

node add-extension.js ext.id https://github.com/x/y --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:

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

Notes:

  • Simply replace $REPOSITORY_URL with the extension's actual repository URL
    // 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 MS marketplace using vsce and then tries to resolve vsix file using GitHub releases or a commit to build associated with a version using tags and commits around the last updated date.

How are Extensions Published?

Every night at 03:03 UTC, a GitHub workflow goes through all entries in extensions.json, and checks if it needs to be published to https://open-vsx.org or not.

The publishing process can be summarized like this:

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

See all ovsx CLI options here.