From 4bc6f10be34a50ac80da1352ffb10d64a2d17885 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 23 Feb 2024 13:15:25 -0600 Subject: [PATCH] (DOCS) Document resource manifests as YAML This change updates the reference docs and changelog to reflect that DSC now recognizes resource manifests authored in YAML instead of JSON. --- CHANGELOG.md | 15 ++++++++++++++- docs/reference/cli/resource/list.md | 4 ++-- docs/reference/schemas/config/document.md | 2 +- docs/reference/schemas/resource/manifest/root.md | 6 ++++-- 4 files changed, 21 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bed531c1..2297b485 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,8 @@ changes since the last release, see the [diff on GitHub][unreleased]. [unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...main + + ### Changed - Updated the options for the `dsc` root command: @@ -62,7 +64,16 @@ changes since the last release, see the [diff on GitHub][unreleased]. - +- Added support for authoring DSC Resource manifests in YAML. DSC now recognizes resource manifests + that use the `.dsc.resource.yml` or `.dsc.resource.yaml` file extension instead of only + `.dsc.resource.json`. + +
Related work Items + + - Issues: [#129][#129] + - PRs: [#311][#311] + +
## [v3.0.0-alpha.4][release-v3.0.0-alpha.4] - 2023-11-14 @@ -523,6 +534,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#107]: https://github.com/PowerShell/DSC/issues/107 [#121]: https://github.com/PowerShell/DSC/issues/121 [#127]: https://github.com/PowerShell/DSC/issues/127 +[#129]: https://github.com/PowerShell/DSC/issues/129 [#130]: https://github.com/PowerShell/DSC/issues/130 [#133]: https://github.com/PowerShell/DSC/issues/133 [#150]: https://github.com/PowerShell/DSC/issues/150 @@ -561,6 +573,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#291]: https://github.com/PowerShell/DSC/issues/291 [#294]: https://github.com/PowerShell/DSC/issues/294 [#299]: https://github.com/PowerShell/DSC/issues/299 +[#311]: https://github.com/PowerShell/DSC/issues/311 [#45]: https://github.com/PowerShell/DSC/issues/45 [#49]: https://github.com/PowerShell/DSC/issues/49 [#57]: https://github.com/PowerShell/DSC/issues/57 diff --git a/docs/reference/cli/resource/list.md b/docs/reference/cli/resource/list.md index 2c44ae1f..f5e54b7e 100644 --- a/docs/reference/cli/resource/list.md +++ b/docs/reference/cli/resource/list.md @@ -21,8 +21,8 @@ dsc resource list [Options] The `list` subcommand searches for available DSC Resources and returns their information. DSC discovers resources by first searching the `PATH` or `DSC_RESOURCE_PATH` environment variable for -`.dsc.resource.json` files. For more information about the environment variables DSC uses, see -[Environment variables][01] +`.dsc.resource.json`, `.dsc.resource.yml`, and `dsc.resource.yaml` files. For more information +about the environment variables DSC uses, see [Environment variables][01] If any of the discovered resources are resource providers, DSC then calls the providers to list their resources, too. diff --git a/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md index 3665b2e0..f04d1cd3 100644 --- a/docs/reference/schemas/config/document.md +++ b/docs/reference/schemas/config/document.md @@ -29,7 +29,7 @@ A configuration document can be defined as either YAML or JSON. For ease of auth recommends drafting configuration documents in YAML. For DSC's authoring tools to recognize a file as a DSC Configuration document, the filename must -end with `.dsc.config.json` or `.dsc.config.yaml`. +end with `.dsc.config.json`, `.dsc.config.yml`, or `.dsc.config.yaml`. You can use configuration document functions to dynamically determine values in the document at runtime. For more information, see [DSC Configuration document functions reference][01] diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md index 95c5c16b..fc268094 100644 --- a/docs/reference/schemas/resource/manifest/root.md +++ b/docs/reference/schemas/resource/manifest/root.md @@ -9,7 +9,7 @@ title: Command-based DSC Resource manifest schema reference ## Synopsis -The JSON file that defines a command-based DSC Resource. +The data file that defines a command-based DSC Resource. ## Metadata @@ -24,7 +24,9 @@ Type: object Every command-based DSC Resource must have a manifest. The manifest file must: 1. Be discoverable in the `PATH` environment variable. -1. Follow the naming convention `.dsc.resource.json`. +1. Be formatted as either JSON or YAML. +1. Follow the naming convention `.dsc.resource.`. Valid extensions include `json`, + `yml`, and `yaml`. 1. Be valid for the schema described in this document. The rest of this document describes the manifest's schema.