Merge pull request #325 from michaeltlombardi/docs/main/yaml-manifests

(DOCS) Document resource manifests as YAML

Author: SteveL-MSFT

CHANGELOG.md

@@ -24,6 +24,8 @@ changes since the last release, see the [diff on GitHub][unreleased].
 <!-- Unreleased comparison link -->
 [unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...main
 
+<!-- Add entries between releases under the appropriate section heading here  -->
+
 ### Changed
 
 - Updated the options for the `dsc` root command:
@@ -62,7 +64,16 @@ changes since the last release, see the [diff on GitHub][unreleased].
 
   </details>
 
-<!-- Add entries between releases under the appropriate section heading here  -->
+- 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`.
+
+  <details><summary>Related work Items</summary>
+
+  - Issues: [#129][#129]
+  - PRs: [#311][#311]
+
+  </details>
 
 ## [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

docs/reference/cli/resource/list.md

@@ -21,8 +21,8 @@ dsc resource list [Options] <RESOURCE_NAME>
 
 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.

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]

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 `<name>.dsc.resource.json`.
+1. Be formatted as either JSON or YAML.
+1. Follow the naming convention `<name>.dsc.resource.<extension>`. 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.