From 875e2a1c458ffcf2bfe90be841eb9893f399b4ff Mon Sep 17 00:00:00 2001 From: Finn Evers Date: Fri, 21 Aug 2026 10:06:24 +0000 Subject: [PATCH] Revise extension publishing documentation (#62767) Release Notes: - N/A --- docs/.gitignore | 1 + docs/redirects/legacy-fragment-redirects.js | 2 +- docs/src/SUMMARY.md | 4 +- docs/src/extensions.md | 2 + docs/src/extensions/publishing/faq.md | 97 +++++++++++++++++++ .../publishing/license-requirements.md | 12 ++- docs/src/extensions/publishing/overview.md | 4 +- .../extensions/publishing/prerequisites.md | 85 +++++++++++++--- .../extensions/publishing/publishing-guide.md | 50 +++++----- .../publishing/updating-and-maintenance.md | 28 ++++++ 10 files changed, 236 insertions(+), 49 deletions(-) create mode 100644 docs/src/extensions/publishing/faq.md create mode 100644 docs/src/extensions/publishing/updating-and-maintenance.md diff --git a/docs/.gitignore b/docs/.gitignore index 3006b271da..d987d56b99 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ book/ +_redirects diff --git a/docs/redirects/legacy-fragment-redirects.js b/docs/redirects/legacy-fragment-redirects.js index 1adf41f2fb..cd58686817 100644 --- a/docs/redirects/legacy-fragment-redirects.js +++ b/docs/redirects/legacy-fragment-redirects.js @@ -14,7 +14,7 @@ page: "publishing/publishing-guide", }, "#updating-an-extension": { - page: "publishing/publishing-guide", + page: "publishing/updating-and-maintenance", hash: "#updating-an-extension", }, }; diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index df64eee114..1ab5579bf6 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -192,9 +192,11 @@ - [Installing Extensions](./extensions/installing-extensions.md) - [Developing Extensions](./extensions/developing-extensions.md) - [Publishing Your Extension](./extensions/publishing/overview.md) - - [Publishing Prerequisites](./extensions/publishing/prerequisites.md) - [License Requirements](./extensions/publishing/license-requirements.md) + - [Publishing Prerequisites](./extensions/publishing/prerequisites.md) - [Publishing Guide](./extensions/publishing/publishing-guide.md) + - [Updating an Extension](./extensions/publishing/updating-and-maintenance.md) + - [Frequently Asked Questions](./extensions/publishing/faq.md) - [Extension Capabilities](./extensions/capabilities.md) - [Language Extensions](./extensions/languages.md) - [Debugger Extensions](./extensions/debugger-extensions.md) diff --git a/docs/src/extensions.md b/docs/src/extensions.md index 08c5056626..4bb627584e 100644 --- a/docs/src/extensions.md +++ b/docs/src/extensions.md @@ -25,3 +25,5 @@ If you are considering to publish your extension, please have a look through our - [Publishing Prerequisites](./extensions/publishing/prerequisites.md) - [License Requirements](./extensions/publishing/license-requirements.md) - [Publishing Guide](./extensions/publishing/publishing-guide.md) + - [Updating an Extension](./extensions/publishing/updating-and-maintenance.md) + - [Frequently Asked Questions](./extensions/publishing/faq.md) diff --git a/docs/src/extensions/publishing/faq.md b/docs/src/extensions/publishing/faq.md new file mode 100644 index 0000000000..c3203f9db1 --- /dev/null +++ b/docs/src/extensions/publishing/faq.md @@ -0,0 +1,97 @@ +--- +title: Frequently Asked Questions +description: "Answers to common questions around publishing and maintaining extensions." +--- + +# Frequently Asked Questions {#faq} + +Questions come up before, during, and after publishing an extension. Here are the ones we hear most often. + +## How long will the review of my submission take? {#review-duration} + +We do our best to get back to you in a reasonable time frame. However, we are very aware that this is currently not always the case - we sincerely apologize for that! We are continuously iterating on the process to provide every submission with feedback more quickly and with an overall better contribution experience. + +That said, most submissions get their first feedback within a few weeks; for some extensions it might take us longer - up to one or two months. We know this is neither optimal nor a pleasant experience, and we are working on it (in fact, this very document is part of that effort to provide you with more context on our side of things). + +Please note, though, that we currently cannot make any promises, and reviews might sadly take even longer for various reasons - the biggest one being the large backlog we are working through right now. + +## Why was my PR closed? {#pr-closed} + +If your PR was closed without much feedback, it severely violated the [publishing prerequisites](./prerequisites.md). Due to the high volume of submissions, we do not provide more context in such cases. Please make sure to read through the prerequisites again. + +Furthermore, as stated in the [pull request rules](./publishing-guide.md#pull-request-rules), we consider submissions stale after **3 weeks of no response to maintainer feedback** and close them. + +A PR closed due to staleness is not the end of the road: you may open a fresh PR at any time and we will take another look. + +## Why is a response timeframe enforced on me, but not on you? {#response-timeframe} + +We know this seems unfair, especially given our own response times - we are not proud of this either. But we do this in the interest of everybody: closing stale submissions keeps the review queue in a manageable state, which in turn helps us get to every submission sooner, including your next one. + +## Why was I asked to open a new PR instead of continuing my closed one? {#fresh-prs} + +Due to the high backlog, we prefer fresh PRs in some cases, as they keep the queue shorter. Experience has shown that fresh PRs tend to be in a more reviewable state, whereas updated PRs often claim to have addressed all feedback while actually being in a broken and unmergeable state. That in turn costs both reviewers and contributors valuable time. + +A fresh PR is, in that sense, quicker to work with and more often than not an easier and faster merge. + +## Why do you enforce so many strict prerequisites? {#why-prerequisites} + +Our goal with the extension prerequisites is to strike a balance between an open extension ecosystem and a certain level of standard and quality: when you install an extension, you should be able to rest assured that it works well to a certain degree - without having to vet it yourself first. + +The prerequisites also help us bundle effort. Multiple people maintaining multiple near-identical extensions, with users spread across all of them, creates a lot of churn for everyone involved. Guiding that effort into one place benefits owners, contributors, and users alike - and with only one extension per use case, you don't have to guess which one is the right one. + +Of course, we know we will not catch everything with these - but they set a baseline everyone can rely on. And should an extension end up not working or unmaintained regardless, that is exactly what the policies further down this page are for. + +## Do the prerequisites also apply to already published extensions? {#prerequisites-for-existing-extensions} + +Yes. Existing extensions are not exempt from the prerequisites, and updates are held to the same standards as new submissions. + +The only exception are the ID restrictions: since an extension's ID cannot change once published, existing IDs stay as they are. + +## Do I have to maintain my extension? {#do-i-have-to-maintain-my-extension} + +No. After your extension has been published, there are no further requirements from our side. Thank you for enriching the Zed extension collection, we really appreciate it! + +That said, no extension is perfect on day one - bugs may surface and improvement requests may come in. While maintenance is never required, it helps everyone if you respond to those reports within a reasonable timeframe. + +## I found a bug in an extension or want to improve it. What should I do? {#reporting-issues-and-improvements} + +Report the issue or propose your improvement in the original extension repository first, rather than publishing a competing extension. Most owners appreciate reports and contributions, and keeping the effort in one place spares users from having to pick between near-identical extensions - as well as maintainers from having to review them. + +If the owner does not respond for an extended period of time, see [What happens when an extension owner stops responding?](#unresponsive-owner) + +## I no longer want to maintain my extension. What now? {#stepping-back} + +Completely fine - priorities change, and stepping back from an extension is nothing to feel bad about. As the current owner, you can: + +- transfer ownership of the repository to a new owner, or +- open an issue or pull request against [`zed-industries/extensions`](https://github.com/zed-industries/extensions) asking for the removal of your extension. + +Note that you may also just keep your extension around - many extensions have received few to no updates and yet have many happy users. + +## What happens when an extension owner stops responding to reported issues? {#unresponsive-owner} + +We don't want published extensions to go stale, since that leaves their users with a poor experience. So if an extension owner can no longer be reached: + +- a contributor may fork the extension and propose their fork as a replacement for the current extension, or +- Zed staff can fork the extension into the [`zed-extensions`](https://github.com/zed-extensions) organization, where maintenance continues as a joint effort of the community and Zed staff. + +We will only take either action if one of the following requirements is met: + +- the current owner has given written permission, or +- there is **written proof** of attempts to establish contact, and the owner has been unresponsive to them for **at least 6 weeks**. + +Without one of these, the extension stays with its current owner as is. + +Such a switch also does not have to be permanent: should the original owner become responsive again, the extension may be switched back to the original repository. + +## Why can't my language reuse builtin grammars or a grammar from another extension? {#grammar-reuse} + +If your language depended on a grammar it does not own, updates to that grammar could change the nodes produced by Tree-sitter parsing and silently break your language. To avoid this, every language must use a grammar defined in its own extension's `extension.toml`. + +## I have questions about these policies or disagree with them. Where can I raise that? {#policy-discussion} + +First of all, thank you for reading through these! + +While all of these policies were added with good reason, not all of them are entirely set in stone - we value open discussion around all of this. + +If anything here seems off to you or you have questions, feel free to open a discussion in the [`zed-industries/zed`](https://github.com/zed-industries/zed) repository and ping @MrSubidubi there - we would much rather talk it through than leave you frustrated. diff --git a/docs/src/extensions/publishing/license-requirements.md b/docs/src/extensions/publishing/license-requirements.md index ab8e9397c6..731ecaee85 100644 --- a/docs/src/extensions/publishing/license-requirements.md +++ b/docs/src/extensions/publishing/license-requirements.md @@ -19,12 +19,14 @@ The following licenses are accepted: - [zlib](https://opensource.org/license/zlib) This allows us to distribute the resulting binary produced from your extension code to our users. -Without a valid license, the pull request to add or update your extension in the following steps will fail CI. +Without a valid license, the pull request to add or update your extension will fail CI. -Your license file should be at the root of your extension. If your extension is in a subdirectory within its repository, the license must reside within that subdirectory as well; a license at the repository root will not work. You may symlink an existing license into the extension directory or choose another accepted license for the extension code. +Your license file should be at the root of your extension, though not necessarily at the root of the repository. If your extension is in a subdirectory within its repository, the license must reside within that subdirectory; a license at the repository root will not work. You may symlink an existing license into the extension directory or choose another accepted license for the extension code. Any filename that has `LICENCE` or `LICENSE` as a prefix (case insensitive) will be inspected to ensure it matches one of the accepted licenses. See the [license validation source code](https://github.com/zed-industries/extensions/blob/main/src/lib/license.js). -> This license requirement applies only to your extension code itself (the code that gets compiled into the extension binary). -> It does not apply to any tools your extension may download or interact with, such as language servers or other external dependencies. -> If your repository contains both extension code and other projects (like a language server), you are not required to relicense those other projects — only the extension code needs to be one of the aforementioned accepted licenses. +Please note that: + +- This license requirement applies only to your extension code itself (the code that gets compiled into the extension binary). +- It does not apply to any tools your extension may download or interact with, such as language servers or other external dependencies. +- If your repository contains both extension code and other projects (like a language server), you are not required to relicense those other projects; only the extension code needs to be one of the aforementioned accepted licenses. diff --git a/docs/src/extensions/publishing/overview.md b/docs/src/extensions/publishing/overview.md index b57da89ac5..50551f2ec9 100644 --- a/docs/src/extensions/publishing/overview.md +++ b/docs/src/extensions/publishing/overview.md @@ -1,6 +1,6 @@ --- title: Publishing Extensions -description: "Publish extensions in the Zed Extension Gallery." +description: "Publish extensions to the Zed Extension Registry." --- # Publishing Extensions {#publishing-extensions} @@ -10,3 +10,5 @@ To publish an extension: 1. Review the [publishing prerequisites](./prerequisites.md) and ensure your extension is ready. 2. Add an [accepted license](./license-requirements.md) to your extension. 3. Follow the [publishing guide](./publishing-guide.md) to submit it to the Zed extensions repository. + +After your extension is published, see [Updating an Extension](./updating-and-maintenance.md) for how to ship updates, and the [FAQ](./faq.md) for general information regarding maintenance and stale extensions. diff --git a/docs/src/extensions/publishing/prerequisites.md b/docs/src/extensions/publishing/prerequisites.md index 4cecb49c99..3da78316c3 100644 --- a/docs/src/extensions/publishing/prerequisites.md +++ b/docs/src/extensions/publishing/prerequisites.md @@ -5,23 +5,76 @@ description: "Review the requirements for publishing an extension to the Zed Ext # Extension Publishing Prerequisites {#extension-publishing-prerequisites} -Before publishing your extension, make sure that you have chosen a unique extension ID for your extension in the [extension manifest](../developing-extensions.md#directory-structure-of-a-zed-extension). -This will be the primary identifier for your extension and cannot be changed after your extension has been published. -Also, ensure that you have filled out all the required fields in the manifest. +Before submitting your extension for publishing, make sure it meets the following requirements. -Furthermore, please make sure that your extension fulfills the following preconditions before you move on to publishing your extension: +Note that maintainers will raise non-compliance during the publishing process. Should you choose not to follow these requirements, publishing will be delayed or may outright be rejected. -- Extension IDs and names must not contain the words `zed`, `Zed` or `extension`, since they are all Zed extensions. -- Your extension ID should provide some information on what your extension tries to accomplish. E.g. for themes, it should be suffixed with `-theme`, snippet extensions should be suffixed with `-snippets` and so on. An exception to that rule is an extension that provides support for languages or popular tooling that people would expect to find under that ID. You can take a look at the list of [existing extensions](https://github.com/zed-industries/extensions/blob/main/extensions.toml) to get a grasp on how this usually is enforced. -- Your extension must only include the resources it requires to function and nothing else. - - See the [directory structure of a Zed extension](../developing-extensions.md#directory-structure-of-a-zed-extension) and the [Rust and WebAssembly](../developing-extensions.md#rust-and-webassembly) sections for more information. -- Extensions must in no way attempt to read nor modify the environment outside of the environment designated to them by Zed. Should they need to read the environment, they should use methods as provided by the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/) and may fall back to appropriate methods from the Rust standard library. Should they need changes to the environment, they must instead ask the user to perform these for them using an appropriate method within the context (e.g. provide information for doing so using the `ContextServerConfiguration` for context servers). - - Please make sure to have read the [Rust and WebAssembly section](../developing-extensions.md#rust-and-webassembly) for more information and help regarding this topic. -- Extensions should provide something that is not yet available in the marketplace as opposed to fixing something that could be resolved within an existing extension. For example, if you find that an existing extension's support for a language server is not functioning properly, first try contributing a fix to the existing extension as opposed to submitting a new extension immediately. - - If you receive no response or reaction within the upstream repository within a reasonable amount of time, feel free to submit a pull request that aims to fix said issue. Please ensure that you provide your previous efforts within the pull request to the extensions repository for adding your extension. Zed maintainers will then decide on how to proceed on a case by case basis. -- Extensions that intend to provide a language, debugger or MCP server must not ship the language server as part of the extension. Instead, the extension should either download the language server or check for the availability of the language server in the user's environment using the APIs as provided by the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/). -- Themes and icon themes should not be published as part of extensions that provide other features, e.g. language support. Instead, they should be published as a distinct extension. This also applies to themes and icon themes living in the same repository. +## General Requirements -Furthermore, before publishing your extension, [install it locally as a dev extension](../developing-extensions.md#developing-an-extension-locally) and test it thoroughly. Submissions for extensions that have not been tested and do not function at all may be closed without further feedback. +- Test your extension within Zed manually at the submodule commit you are submitting. +- Publish functionality that is not already available in the extension registry. + - If you face issues with an existing extension, first try contributing to the existing extension. See the [FAQ](./faq.md#reporting-issues-and-improvements) for more details on this requirement. +- Do not misuse the extension API to work around its current limitations. + - In rare cases, we may accept a reasonable workaround. + - Acceptance of a workaround is at the maintainers' discretion. +- Use an appropriate ID for your extension. The ID must: + - be unique + - be kebab-cased + - not include the words `zed` or `extension` + - be a good indicator for what your extension provides (more on this below) +- Include only the resources your extension needs to function. +- License your extension under one of the [allowed licenses](./license-requirements.md). +- Write all user-facing text in English. +- Do not read or modify anything outside the environment Zed designates for your extension. + - Use the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/) to read and modify the environment. + - Use Rust standard library methods to read and modify the work directory provided to the extension. + - Ask the user to make any other required changes themselves. -Non-compliance with these rules will be raised during the publishing process by reviewers. If you fail to comply with the laid out guidelines, the publishing of your extension will either be delayed or rejected. +## Language Extensions + +- Only provide support for the language your extension targets, as well as any dialects that are directly associated with that language. +- Define a [grammar](../languages.md#grammar) in your extension's `extension.toml` for every language that you provide. +- You may also provide language servers, debuggers and snippets for that language. +- Choose an extension ID and name similar or equal to the name of the primary language you intend to add. +- Do not include any Rust code should your extension not also provide language servers. + +## Language Server Extensions + +- Should your extension only provide a language server, make sure your extension ID reflects that (e.g., by suffixing it with `-language-server` or `-lsp`). +- Do not bundle a language server with the extension. Download it or check for it in the user's environment through the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/). + +## Debugger Extensions + +- Should your extension only provide a debugger, make sure your extension ID reflects that (e.g., by suffixing it with `-debugger`). +- Do not bundle the debug adapter with the extension. Download it or check for it in the user's environment through the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/). + +## Theme Extensions + +- Only provide themes and nothing else. +- Make sure your extension ID indicates it is a theme (e.g., by suffixing it with `-theme`). + +## Icon Theme Extensions + +- Only provide an icon theme and nothing else. +- Make sure your extension ID indicates it is an icon theme (e.g., by suffixing it with `-icon-theme` or `-icons`). + +## Snippet Extensions + +- Should your extension only provide snippets, make sure your extension ID reflects that (e.g., by suffixing it with `-snippets`). +- Only scope your snippets to the global scope if appropriate. Scope language-specific snippets to the given languages. + +## MCP Server Extensions + +> MCP server extensions will be deprecated in favor of the MCP registry in the future; progress for this is tracked in [#59351](https://github.com/zed-industries/zed/issues/59351). Please make sure to also publish your server to the registry to ensure it can be used with future versions of Zed. + +- Only provide one MCP server and nothing else. +- Make sure your extension ID indicates it is an MCP server (e.g., by prefixing it with `mcp-server-` or suffixing it with `-mcp-server`). +- Do not bundle the MCP server with the extension. Download it or check for it in the user's environment through the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/). + +## Agent Server and Slash Command Extensions + +Agent server and slash command extensions have been deprecated and submissions will no longer be accepted. If you intend on making an agent server available within Zed, publish it to the [ACP Registry](https://agentclientprotocol.com/registry) instead. + +--- + +Passing everything on this list? Let's [get your extension published!](./publishing-guide.md) diff --git a/docs/src/extensions/publishing/publishing-guide.md b/docs/src/extensions/publishing/publishing-guide.md index 90fd3654b3..31cf7ada98 100644 --- a/docs/src/extensions/publishing/publishing-guide.md +++ b/docs/src/extensions/publishing/publishing-guide.md @@ -9,36 +9,50 @@ description: "Submit and update extensions in the Zed Extension Registry." Follow each step carefully to help the publishing process go smoothly. +## Pull request rules {#pull-request-rules} + +To keep the review queue manageable, the following rules apply to every PR against the `zed-industries/extensions` repository: + +- Every PR must add or update **exactly one extension**. +- You may have **at most three open PRs** at any given time. +- Respond to maintainer feedback within **3 weeks**, otherwise your PR will be closed. + +PRs that do not adhere to these rules will be closed without further feedback. Repeated violations of these rules may result in a temporary suspension or a ban from submitting to the extension repository. + ## Forking and cloning the repo 1. Fork the `zed-industries/extensions` repository. > **Note:** It is very helpful if you fork the `zed-industries/extensions` repo to a personal GitHub account instead of a GitHub organization, as this allows Zed staff to push any needed changes to your PR to expedite the publishing process. -2. Clone the repo to your local machine +2. Clone the repo to your local machine. ```sh -# Substitute the url of your fork here: -# git clone https://github.com/zed-industries/extensions +# Substitute the URL of your fork here: +git clone https://github.com/your-username/extensions cd extensions git submodule init git submodule update ``` +## Submitting your extension {#submitting-your-extension} + To publish an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions). In your PR, do the following: -1. Add your extension as a Git submodule within the `extensions/` directory under the `extensions/{extension-id}` path +1. Add your extension as a Git submodule within the `extensions/` directory under the `extensions/{extension-id}` path. + - The submodule must use an HTTPS URL and not an SSH URL (`git@github.com`). + - Your extension repository must be publicly available. + - The checked out submodule commit must be present on a branch and thus not be a detached commit. ```sh git submodule add https://github.com/your-username/foobar-zed.git extensions/my-extension git add extensions/my-extension ``` -> All extension submodules must use HTTPS URLs and not SSH URLS (`git@github.com`). Furthermore, your extension repository must be publicly available and the checked out submodule commit must be on a branch and thus not be a detached commit. - 2. Add a new entry to the top-level `extensions.toml` file containing your extension: + - Make sure the `version` matches the one set in `extension.toml` at the particular commit. ```toml [my-extension] @@ -55,26 +69,12 @@ path = "packages/zed" version = "0.0.1" ``` -3. Run `pnpm sort-extensions` to ensure `extensions.toml` and `.gitmodules` are sorted +3. Run `pnpm sort-extensions` to ensure `extensions.toml` and `.gitmodules` are sorted. -Once your PR is merged, the extension will be packaged and published to the Zed extension registry. +That's it! Once your PR is accepted and merged, the extension will be packaged and published to the Zed extension registry. -## Updating an extension {#updating-an-extension} +## Review process {#review-process} -To update an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions). +Once your PR is open, a maintainer will review it and may request changes. Keep the [pull request rules](#pull-request-rules) in mind: submissions are closed after **3 weeks of no response to maintainer feedback**. -In your PR do the following: - -1. Update the extension's submodule to the commit of the new version. For this, you can run - -```sh -# From the root of the repository: -git submodule update --remote extensions/your-extension-name -``` - -to update your extension to the latest commit available in your remote repository. - -2. Update the `version` field for the extension in `extensions.toml` - - Make sure the `version` matches the one set in `extension.toml` at the particular commit. - -If you'd like to automate this process, there is a [community GitHub Action](https://github.com/huacnlee/zed-extension-action) you can use. +For everything beyond that - how long reviews take, why we enforce the timeframe, or what to do after a PR was closed - see the [FAQ](./faq.md). diff --git a/docs/src/extensions/publishing/updating-and-maintenance.md b/docs/src/extensions/publishing/updating-and-maintenance.md new file mode 100644 index 0000000000..97eac57a5a --- /dev/null +++ b/docs/src/extensions/publishing/updating-and-maintenance.md @@ -0,0 +1,28 @@ +--- +title: Updating an Extension +description: "Ship new versions of your published extension." +--- + +# Updating an Extension {#updating-an-extension} + +To update an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions). + +> Update PRs are subject to the same [pull request rules](./publishing-guide.md#pull-request-rules) as new submissions. + +In your PR, do the following: + +1. Update the extension's submodule to the commit of the new version. For this, you can run + +```sh +# From the root of the repository: +git submodule update --remote extensions/your-extension-name +``` + +to update your extension to the latest commit available in your remote repository. + +2. Update the `version` field for the extension in `extensions.toml`. + - Make sure the `version` matches the one set in `extension.toml` at the particular commit. + +If you'd like to automate this process, there is a [community GitHub Action](https://github.com/huacnlee/zed-extension-action) you can use. + +For questions around maintaining (or no longer maintaining) your extension, see the [FAQ](./faq.md).