(MAINT) Schema improvements #203
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
michaeltlombardi
force-pushed
the
maint/main/schema-improvements
branch
from
f6f6c87
to
5e10fbb
Compare
|
Looks like we need to regen again. Frequent changes. Want to put them in the same PR? |
SteveL-MSFT
requested changes
Sep 26, 2023
michaeltlombardi
force-pushed
the
maint/main/schema-improvements
branch
from
b6afa16
to
f55fec0
Compare
michaeltlombardi
force-pushed
the
maint/main/schema-improvements
branch
from
f55fec0
to
6366dff
Compare
|
@SteveL-MSFT, @mgreenegit - ended up pulling all the changes for the |
SteveL-MSFT
requested changes
Sep 29, 2023
| ${1:metadataName}: | ||
| ${2:key}: ${3:value} | ||
|
|
||
| - label: ' New metadata property (array)' |
There was a problem hiding this comment.
Looks like a bunch of these have extra whitespace
Suggested change
| - label: ' New metadata property (array)' | |
| - label: 'New metadata property (array)' |
There was a problem hiding this comment.
@SteveL-MSFT - the extra whitespace is intentional, it moves them to the top of the IntelliSense completion list - otherwise they often end up hidden at the bottom, depending on the extensions you have installed.
Prior to this change, the schema generation relied on hard-coding the full URL to docs pages, including the version query parameters. This change updates the build script and configuration for schema generation to handle replacing the URLs using placeholders.
This change updates the documentation links in the markdown descriptions for the schemas to: 1. Use the placeholders for more robust linking. 1. Reformat the display so the link is wrapped in horizontal rules.
This change reformats and rewords the Markdown descriptions for schema enum values. This change only affects the schemas enhanced for authoring in VS Code. The standardized format it to include a brief synopsis at the start of the enum description in italics, then additional information in a blockquote.
This change reworks the snippets for usability and contextual help. It: - Ensures snippets use `body` instead of `bodyText` for non-scalar value snippets, so they are correctly inserted instead of relying on fragile strings, which might break indentation or syntax. - Adds many new snippets for faster authoring - Shows a preview of the snippet insert for the configuration snippets, where we can reliably show YAML syntax.
Prior to this change, the markdown description for the semver schema was used anywhere the value of a property referenced that definition instead of the defined description on that property. This change converts the markdownDescription for the definition into a comment for maintainers, ensuring that more specific documentation can be shown in the hover context for manifest and configuration authors.
Prior to this change, the schema specified `enums` instead of `enum`, which broke the validation for that property. This change corrects the spelling and ensures the validation applies.
This change regenerates the schemas from the updated source definitions. This ensures the fixes and enhancements are usable.
This change updates the schemas to reflect the renaming of the `set.preTest` setting in the resource manifest to the more readable and semantically correct `set.implementsPretest` to reflect the change in PowerShell#197.
Prior to this change, the schema generation had a bug that incorrectly munged the values for always-array keywords, like `enum` and `requires` to scalar values when the definition was a single-item array. This change ensures that those values are not incorrectly munged, fixing hidden bugs in the behavior for those values in the generated schemas.
This change updates the schema definitions to replace the `manifestVersion` property for resource manifests with the more canonical `$schema` keyword to reflect the changes from PowerShell#199.
Prior to this change, the config command output schemas referenced the result data subschemas for the `dsc resource *` commands as `/<PREFIX>/<VERSION>/results/resource/<COMMAND>.yaml` instead of `/<PREFIX>/<VERSION>/outputs/resource/<COMMAND>.yaml`, which is their actual canonical URI. This change fixes the error, ensuring the schemas validate correctly.
This change updates the schemas to replace the unimplemented `args` option for command input in the resource manifest with the `env` option. It also updates the schema and documentation to indicate that when the `input` option is not defined for a command in a resource manifest, DSC does not send the resource any input for that command. This update is made to reflect the changes from PowerShell#198.
This change standardizes formatting for the default snippets definitions in the source schemas and ensures that every snippet label starts with a leading space - this puts them at the top of the IntelliSense list for completions when they are available.
Prior to this change, the enum documentation for the enhanced schema didn't clarify how the environment variables are named or their values passed. This change clarifies both, making it easier for manifest authors to determine whether the input option is right for them and how they should expect to handle the input in their resource without consulting the online documentation.
Prior to this change, the schema docs erroneously noted that when `input` is not defined in a resource manifest for the `set` and `test` definitions that DSC doesn't send any input. This is _technically_ true, but the `input` property is included in the list of `required` properties for `set` and `test`, unlike `get`. This change removes the misleading sentence, since those properties can't be undefined in a valid manifest.
michaeltlombardi
force-pushed
the
maint/main/schema-improvements
branch
from
e7b1546
to
45958c3
Compare
SteveL-MSFT
approved these changes
Sep 29, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
PR Summary
This change adds a set of enhancement to the schemas, adding online documentation to the contextual help, new snippets, and reformatting the help.
This change set also includes the following updates to the schemas to reflect the changes for
alpha.3:manifestVersionkeyword with$schemapointing to the canonical bundled schema URI, per change ManifestVersion to $schema and validate #199.set.preTestwithset.implementsPretest, per Direct resourcesetno longer requirestest#197.argswithenvfor input kind, per add support to pass JSON as env var #198.enumandrequired, to scalar values when the array only contains a single item.PR Context
This change helps improve the experience for configuration and manifest authors, improving their contextual help and giving them a faster way to add sections and entries to those files.