Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Publish schemas for other Zed extension config files (config.toml, extension.toml) #21994

Open
1 task done
uncenter opened this issue Dec 13, 2024 · 10 comments
Open
1 task done
Assignees
Labels
documentation [core label] enhancement [core label] extension infrastructure Feedback for extensions APIs, creation, management, etc

Comments

@uncenter
Copy link
Contributor

Check for existing issues

  • Completed

Describe the feature

There is a schema for the themes JSON file, but no schemas for the extension.toml/extension.json file or the config.toml file for languages. Would be appreciated if there were at least schemas for these to supplement the docs and for improved editor experience.

Environment

N/A

If applicable, add mockups / screenshots to help present your vision of the feature

No response

@notpeter notpeter added extension infrastructure Feedback for extensions APIs, creation, management, etc and removed triage labels Dec 16, 2024
@notpeter notpeter changed the title Publish schemas for other Zed configuration files Publish schemas for other Zed extension config files (config.toml, extension.toml) Dec 16, 2024
@notpeter
Copy link
Member

Love it. extension.json is deprecated, so we probably won't do that, but it'd be sweet to publish schemas for the other extension config file formats.

@uncenter
Copy link
Contributor Author

uncenter commented Dec 16, 2024

Might also be an opportunity to clean parts of the format up with some deprecations; for entries in the grammars table of extension.toml, you have rev (only seen used, not in docs) and commit (in docs: https://zed.dev/docs/extensions/languages#grammar), both seem to work. The language_servers table entries can have a varying array of key names for mostly the same purpose; language, languages, and language_ids should probably be consolidated.

@uncenter
Copy link
Contributor Author

Speaking of the last example there for languages, looks like language is already "deprecated":

/// Deprecated in favor of `languages`.
#[serde(default)]
language: Option<LanguageName>,

But the docs on https://zed.dev/docs/extensions/languages#language-servers continue to suggest language.
I'm pretty interested in helping out on the language and theme docs anyway, please let me know if contributions are wanted in that area.

@notpeter
Copy link
Member

I am always happy to review docs PRs! Note CI runs with docs/* only changes are <15secs so we can quickly and easily merge multiple small PRs.

  1. Nice catch with language that should definitely be fixed.

    /// Deprecated in favor of `languages`.
    #[serde(default)]
    language: Option<LanguageName>,

  2. There is a placeholder (TBD: To Be Documented) for config.toml keys here:

    TBD: Document `language_name/config.toml` keys
    - autoclose_before
    - brackets (start, end, close, newline, not_in: ["comment", "string"])
    - word_characters
    - prettier_parser_name
    - opt_into_language_servers
    - code_fence_block_name
    - scope_opt_in_language_servers

  3. Thanks for pointing out rev. commit is just an alias for rev for backward compatibility rev is the preferred key.

    #[derive(Clone, Default, PartialEq, Eq, Debug, Deserialize, Serialize)]
    pub struct GrammarManifestEntry {
    pub repository: String,
    #[serde(alias = "commit")]
    pub rev: String,
    #[serde(default)]
    pub path: Option<String>,
    }

Ideally in addition to formalizing/publishing these schemas, I would love to implement tests on Pull Requests to the zed-industries/extensions fail (or at least warn) when extensions are using deprecated keys. Basically a PR-only test so we surface a warning for deprecated things (old keys, old schema versions, etc).

@notpeter notpeter added the documentation [core label] label Dec 16, 2024
maxdeviant pushed a commit that referenced this issue Dec 16, 2024
#22107)

Ref
#21994 (comment),
`language` is already deprecated but was still suggested in the docs
here.

Release Notes:

- N/A
@maxdeviant
Copy link
Member

3. Thanks for pointing out rev. commit is just an alias for rev for backward compatibility rev is the preferred key.

I don't think we actually have a preference here.

We just support both.

@uncenter
Copy link
Contributor Author

Ideally in addition to formalizing/publishing these schemas, I would love to implement tests on Pull Requests to the zed-industries/extensions fail (or at least warn) when extensions are using deprecated keys. Basically a PR-only test so we surface a warning for deprecated things (old keys, old schema versions, etc).

Happy to implement this! I think it might be easier to deal with these sort of things though if the scripts over at https://github.com/zed-industries/extensions were properly typed, written in TypeScript ideally. Not sure how the team feels about that though, if there is interest I'm willing to try converting the scripts over.

Also, thinking a bit into the future. It's kind of annoying to only see the lints after you make the new/update PR. Wouldn't it be better to see the warnings during local development? Might be useful to provide some sort of linting tool as a package that can be used outside just this repository. Just a thought :)

@uncenter
Copy link
Contributor Author

Also, connecting back to the original reason I opened this issue - if JSON schemas were provided (which doesn't seem too difficult seeing as Zed already uses schemars under the hood) for these other files, TypeScript types could be autogenerated from those schemas, which could make interop between this repository and the extensions repository (and it's linting process) easier and quicker.

@maxdeviant
Copy link
Member

Happy to implement this! I think it might be easier to deal with these sort of things though if the scripts over at https://github.com/zed-industries/extensions were properly typed, written in TypeScript ideally. Not sure how the team feels about that though, if there is interest I'm willing to try converting the scripts over.

The scripts in the extension repo are typed. We run the JS files through tsc to ensure they type-check: https://github.com/zed-industries/extensions/blob/71a70026b066a1a01c2f5eea80e02e050931321d/tsconfig.json

@uncenter
Copy link
Contributor Author

Sure, I see. I still think JSDoc leads to a worse DX and looser typing, but I understand your position.

Where should I look to for adding JSON schemas to the rest of the config files? Is there a centralized process or are all the schema types spread out across the various crates? I understand they are generated via schemars but how does that output turn into the assets on the website? Eager to get this moving if possible :)

@notpeter
Copy link
Member

notpeter commented Dec 17, 2024

Where should I look to for adding JSON schemas to the rest of the config files? Is there a centralized process or are all the schema types spread out across the various crates? I understand they are generated via schemars but how does that output turn into the assets on the website? Eager to get this moving if possible :)

Currently the process is not automated.
Everything is spread out across crates.

Theme JSON schema export is hacked into the theme-importer which I fixed as part of #21428.
See: crates/theme_importer/src/main.rs

You can invoke with cargo run -p theme_importer print-schema.
I imagine that could be extracted into a more generalized schema_exporter crate/entrypoint.

helgemahrt pushed a commit to helgemahrt/zed that referenced this issue Dec 18, 2024
zed-industries#22107)

Ref
zed-industries#21994 (comment),
`language` is already deprecated but was still suggested in the docs
here.

Release Notes:

- N/A
@maxdeviant maxdeviant self-assigned this Jan 31, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation [core label] enhancement [core label] extension infrastructure Feedback for extensions APIs, creation, management, etc
Projects
None yet
Development

No branches or pull requests

3 participants