[PATCH] D140462: [clangd] Add schema for `.clangd` config

Fri Dec 23 02:05:07 PST 2022

nridge added a comment.

In D140462#4014944 <https://reviews.llvm.org/D140462#4014944>, @sammccall wrote:

> given lack of any automation/tests

That's a fair point, it would definitely help validate the correctness of the schema if we had tests in the form of example config files that pass or fail validation.

I would be supportive of adding such tests, but I'm also hesitant to require them as a condition of accepting the addition of the schema file since it does add a fair amount of effort and complexity.

> If clangd contributors should maintain this, how should contributors/reviewers know whether changes are correct?

Is "look at existing sections of our schema file as a guide, or barring that, the JSON-schema specification" too unsatisfactory an answer?

My feeling is that, at the end of the day, the schema format is relatively straightforward compared to other things that a clangd reviewer needs to know (like C++, or the Clang AST API), and the stakes of letting a mistake slip in are quite low (i.e. maybe a user will fail to get code completion for a config file key, as opposed to say clangd crashing on your code).

> If they needn't maintain it, then having it on a third-party site seems appropriate. Maybe a `/contrib/` directory is a useful compromise?

My original thinking was that reviewers should ask for patches that change config to make correspoding changes to the schema, which I guess would fall under "clangd contributors should maintain this".

But I'm definitely happy to compromise on this -- perhaps we could keep it in a `/contrib/` directory like you say, and encourage but not require that config changes keep it up to date? And perhaps, if someone contributes automated tests for the schema in the future, we could consider upgrading its status to "maintained" at that time?

> I don't use VSCode

(Note, there's nothing tying this to VSCode in particular. For example, lsp-mode seems to have support for consuming schemas from SchemaStore based on https://emacs-lsp.github.io/lsp-mode/page/lsp-yaml/#lsp-yaml-schema-store-uri.)

> One practical question: AIUI the main point of having this is so it can be provided to the VSCode YAML extension so it understands .clangd files. How does this work mechanically?

My understanding, based on the discussion in the issue and my experimentation is:

- If the YAML extension's `"yaml.schemaStore.enable"` setting is enabled (which is the default), the extension downloads a catalog of schemas from schemastore.org
- Clangd's entry in that catalog, which you can see if you load https://www.schemastore.org/api/json/catalog.json and filter for "clangd" [aside: I recommend Firefox's built-in JSON viewer for such tasks, the builtin JSON visualization and filtering is really neat; if you have any pull with the Chrome team, maybe put in a good word for adding a similar JSON viewer], declares that the schema applies to files named `.clangd`
- The extension automatically applies the schema to the `.clangd` file in your workspace

> Does it need to be part of the vscode-clangd repo instead?

I think being in the vscode-clangd repo would have the small advantage that the vscode-clangd extension could use the YAML extension's contribution point to install the schema locally even if `"yaml.schemaStore.enable"` is set to false. Not sure whether that's worth putting in place.

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D140462/new/

https://reviews.llvm.org/D140462