(DOCS) Update docs and changelog for alpha.3

This change updates the reference documentation and the changelog
to reflect the changes that were included in the `alpha.3` release:

- PowerShell#197
- PowerShell#198
- PowerShell#199

CHANGELOG.md

@@ -2,7 +2,7 @@
 title: "Desired State Configuration changelog"
 description: >-
   A log of the changes for releases of DSCv3.
-ms.date: 09/06/2023
+ms.date: 09/27/2023
 ---
 
 # Changelog
@@ -20,10 +20,74 @@ This section includes a summary of user-facing changes since the last release. F
 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.2...main
+[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.3...main
 
 <!-- Add entries between releases under the appropriate section heading here  -->
 
+## [v3.0.0-alpha.3][release-v3.0.0-alpha.3] - 2023-09-26
+
+This section includes a summary of changes for the `alpha.3` release. For the full list of changes
+in this release, see the [diff on GitHub][compare-v3.0.0-alpha.3].
+
+<!-- Release links -->
+[release-v3.0.0-alpha.3]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.3 "Link to the DSC v3.0.0-alpha.3 release on GitHub"
+[compare-v3.0.0-alpha.3]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.2...v3.0.0-alpha.3
+
+### Changed
+
+- Replaced the `manifestVersion` property for resource manifests with [$schema][15]. Instead of
+  specifying a semantic version, resources need to indicate which canonical schema DSC should use
+  to validate and process the manifest.
+
+  <details><summary>Related work items</summary>
+
+  - Issues: [#127][#127]
+  - PRs: [#199][#199]
+
+  </details>
+
+- Updated the `preTest` property for the `set` command in resource manifests to
+  [implementsPretest][16] to more make the manifest easier to read and understand.
+
+  <details><summary>Related work items</summary>
+
+  - PRs: [#197][#197]
+
+  </details>
+
+- The [dsc resource set][17] command no longer tests the resource instance before invoking the
+  `set` operation. This simplifies the behavior for the command and adheres more accurately to the
+  implied contract for directly invoking a resource with DSC.
+
+  <details><summary>Related work items</summary>
+
+  - Issues: [#98][#98]
+  - PRs: [#197][#197]
+
+  </details>
+
+- Replaced the `args` option with `env` for defining how a command-based resource expects to
+  receive input for the [get][18], [set][19], and [test][20] commands in the resource manifest.
+
+  The `args` option was never implemented. Instead, resource authors can set the `input` property
+  to `env` to indicate that the resource expects input as environmental variables.
+
+  <details><summary>Related work items</summary>
+
+  - PRs: [#198][#198]
+
+  </details>
+
+- The `input` property for the [get][18] command in a resource manifest no longer has a default
+  value. Instead, when a resource doesn't define `input` for the `get` command, DSC doesn't send
+  any input to the resource for that command.
+
+  <details><summary>Related work items</summary>
+
+  - PRs: [#198][#198]
+
+  </details>
+
 ## [v3.0.0-alpha.2][release-v3.0.0-alpha.2] - 2023-09-05
 
 This section includes a summary of changes for the `alpha.2` release. For the full list of changes
@@ -219,19 +283,32 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [13]: https://learn.microsoft.com/powershell/dsc/reference/microsoft/osinfo/resource?view=dsc-3.0&preserve-view=true
 [14]: docs/reference/schemas/config/document.md#schema
 
+<!-- alpha.3 links -->
+[15]: docs/reference/schemas/resource/manifest/root.md#schema
+[16]: docs/reference/schemas/resource/manifest/set.md#implementspretest
+[17]: docs/reference/cli/resource/set.md
+[18]: docs/reference/schemas/resource/manifest/get.md#input
+[19]: docs/reference/schemas/resource/manifest/set.md#input
+[20]: docs/reference/schemas/resource/manifest/test.md#input
+
 <!-- Issue and PR links -->
-[#163]: https://github.com/PowerShell/DSC/163
-[#156]: https://github.com/PowerShell/DSC/156
-[#168]: https://github.com/PowerShell/DSC/168
-[#172]: https://github.com/PowerShell/DSC/172
-[#182]: https://github.com/PowerShell/DSC/182
-[#181]: https://github.com/PowerShell/DSC/181
-[#177]: https://github.com/PowerShell/DSC/177
-[#150]: https://github.com/PowerShell/DSC/150
-[#176]: https://github.com/PowerShell/DSC/176
-[#133]: https://github.com/PowerShell/DSC/133
-[#73]:  https://github.com/PowerShell/DSC/73
-[#174]: https://github.com/PowerShell/DSC/174
-[#171]: https://github.com/PowerShell/DSC/171
-[#45]:  https://github.com/PowerShell/DSC/45
-[#175]: https://github.com/PowerShell/DSC/175
+[#127]: https://github.com/PowerShell/DSC/issues/127
+[#133]: https://github.com/PowerShell/DSC/issues/133
+[#150]: https://github.com/PowerShell/DSC/issues/150
+[#156]: https://github.com/PowerShell/DSC/issues/156
+[#163]: https://github.com/PowerShell/DSC/issues/163
+[#168]: https://github.com/PowerShell/DSC/issues/168
+[#171]: https://github.com/PowerShell/DSC/issues/171
+[#172]: https://github.com/PowerShell/DSC/issues/172
+[#174]: https://github.com/PowerShell/DSC/issues/174
+[#175]: https://github.com/PowerShell/DSC/issues/175
+[#176]: https://github.com/PowerShell/DSC/issues/176
+[#177]: https://github.com/PowerShell/DSC/issues/177
+[#181]: https://github.com/PowerShell/DSC/issues/181
+[#182]: https://github.com/PowerShell/DSC/issues/182
+[#197]: https://github.com/PowerShell/DSC/issues/197
+[#198]: https://github.com/PowerShell/DSC/issues/198
+[#199]: https://github.com/PowerShell/DSC/issues/199
+[#45]:  https://github.com/PowerShell/DSC/issues/45
+[#73]:  https://github.com/PowerShell/DSC/issues/73
+[#98]:  https://github.com/PowerShell/DSC/issues/98

docs/reference/cli/resource/set.md

@@ -1,6 +1,6 @@
 ---
 description: Command line reference for the 'dsc resource set' command
-ms.date:     08/04/2023
+ms.date:     09/27/2023
 ms.topic:    reference
 title:       dsc resource set
 ---
@@ -31,17 +31,27 @@ This subcommand can only be invoked for command-based DSC Resources that define
 of their resource manifest. If this subcommand is called for a resource that doesn't define a set
 operation, DSC raises an error.
 
-The subcommand's behavior depends on the value of the `set.preTest` option in the resource
-manifest:
-
-- If the resource's manifest doesn't define the `set.preTest` key as `true`, DSC invokes the
-  resource's test operation to determine whether a set operation is required.
-
-  If the instance is already in the desired state, DSC doesn't invoke the set operation. If the
-  instance isn't in the desired state, DSC invokes the resource's set operation with the desired
-  state as input.
-- If the resource's manifest defines the `set.preTest` key as `true`, DSC invokes the resource's
-  set operation without testing the resource state first.
+> [!IMPORTANT]
+> The `dsc resource set` command always invokes the `set` operation for the resource. Resources
+> may, but aren't required to, implement logic that pretests an instance for the `set` operation.
+>
+> This is different from how [dsc config set][02] works, where DSC always tests an instance, either
+> synthetically or by invoking the `test` operation for the resource, and only invokes `set` for an
+> instance if it's not in the desired state.
+>
+> If a resource doesn't implement pretest, it enforces the desired state regardless of the current
+> state when this command executes. If a resource does implement pretest, it only modifies the
+> system if the instance is out of the desired state.
+>
+> Command-based resources indicate whether they implement pretest for the `set` operation by
+> defining the [set.implementsPretest][03] property in their resource manifest. If that property is
+> defined as `true`, the resource implements pretest. If `set.implementsPretest` is set to `false`
+> or is undefined, the resource doesn't implement pretest.
+>
+> For resources that don't implement pretest for the `set` operation, Microsoft recommends always
+> calling `dsc resource test` against an instance to see whether it's in the desired state _before_
+> invoking `dsc resource set`. This can help avoid accidental errors caused by resources that don't
+> implement a fully idempotent `set` command.
 
 ## Examples
 
@@ -115,7 +125,9 @@ Mandatory: false
 
 This command returns JSON output that includes the actual state of the instance before and after
 the set operation, and the list of properties that the set operation modified. For more
-information, see [dsc resource set result schema][02].
+information, see [dsc resource set result schema][04].
 
 [01]: ../config/set.md
-[02]: ../../schemas/outputs/resource/set.md
+[02]: ../config/set.md
+[03]: ../../schemas/resource/manifest/set.md#implementspretest
+[04]: ../../schemas/outputs/resource/set.md

docs/reference/schemas/resource/manifest/get.md

@@ -1,6 +1,6 @@
 ---
 description: JSON schema reference for the 'get' property in a DSC Resource manifest
-ms.date:     08/04/2023
+ms.date:     09/27/2023
 ms.topic:    reference
 title:       DSC Resource manifest get property schema reference
 ---
@@ -24,6 +24,12 @@ Type:          object
 Every command-based DSC Resource must define the `get` property in its manifest. This property
 defines how DSC can get the current state of a resource instance.
 
+When defining this property, be sure to define a value for [input](#input). Even though it isn't
+required, most resources need to receive input to enforce the desired state. When this property
+isn't defined, DSC doesn't send any input to the resource for `get` operations. The only resources
+that usually don't require any input for `get` are resources that only describe a single instance,
+like the operating system information or timezone.
+
 ## Examples
 
 ### Example 1 - Minimal definition
@@ -104,16 +110,36 @@ Default:  []
 
 ### input
 
-The `input` property defines how to pass input to the resource. The value of this property must
-be one of the following strings:
+The `input` property defines how to pass input to the resource. If this property isn't defined, DSC
+doesn't send any input to the resource when invoking the `get` operation.
+
+The value of this property must be one of the following strings:
+
+- `env` - Indicates that the resource expects the properties of an instance to be specified as
+  environment variables with the same names and casing.
+
+  This option only supports the following data types for instance properties:
+
+  - `boolean`
+  - `integer`
+  - `number`
+  - `string`
+  - `array` of `integer` values
+  - `array` of `number` values
+  - `array` of `string` values
+
+  For non-array values, DSC sets the environment variable to the specified value as-is. When the
+  data type is an array of values, DSC sets the environment variable as a comma-delimited string.
+  For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo` environment
+  variable as `"1,2,3"`.
 
-- `args` - Indicates that the resource expects the properties of an instance to be specified with
-  command line arguments. This option isn't implemented yet.
+  If the resource needs to support complex properties with an `object` value or multi-type arrays,
+  set this to `stdin` instead.
 - `stdin` - Indicates that the resource expects a JSON blob representing an instance from `stdin`.
+  The JSON must adhere to the instance schema for the resource.
 
 ```yaml
 Type:        string
 Required:    false
-Default:     stdin
-ValidValues: [args, stdin]
+ValidValues: [env, stdin]
 ```

docs/reference/schemas/resource/manifest/root.md

@@ -1,6 +1,6 @@
 ---
 description: JSON schema reference for a DSC Resource manifest
-ms.date:     08/04/2023
+ms.date:     09/27/2023
 ms.topic:    reference
 title:       Command-based DSC Resource manifest schema reference
 ---
@@ -33,24 +33,26 @@ The rest of this document describes the manifest's schema.
 
 The manifest must include these properties:
 
-- [manifestVersion](#manifestversion)
+- [$schema](#schema)
 - [type](#type)
 - [version](#version)
 - [get](#get)
 
 ## Properties
 
-### manifestVersion
+### $schema
 
-The `manifestVersion` property indicates the semantic version (semver) of this schema that the
-manifest validates against. This property is mandatory. DSC uses this value to validate the
-manifest against the correct JSON schema.
+The `$schema` property indicates the canonical URI of this schema that the manifest validates
+against. This property is mandatory. DSC uses this value to validate the manifest against the
+correct JSON schema.
 
 ```yaml
 Type:        string
 Required:    true
-Pattern:     ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
-ValidValues: ['1.0']
+Format:      URI
+ValidValues: [
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json
+             ]
 ```
 
 ### type
@@ -144,8 +146,8 @@ defined, the DSC can't manage instances of the resource. It can only get their c
 test whether the instance is in the desired state.
 
 The value of this property must be an object. The `executable` property, defining the name of the
-command to call, is mandatory. The `args` `input`, `preTest`, and `returns` properties are
-optional. For more information, see [DSC Resource manifest set property schema reference][08].
+command to call, is mandatory. The `args` `input`, `implementsPretest`, and `returns` properties
+are optional. For more information, see [DSC Resource manifest set property schema reference][08].
 
 ```yaml
 Type:     object

docs/reference/schemas/resource/manifest/set.md

@@ -1,6 +1,6 @@
 ---
 description: JSON schema reference for the 'set' property in a DSC Resource manifest
-ms.date:     08/04/2023
+ms.date:     09/27/2023
 ms.topic:    reference
 title:       DSC Resource manifest set property schema reference
 ---
@@ -40,9 +40,9 @@ This example is from the `Microsoft.Windows/Registry` DSC Resource.
     "config",
     "set"
   ],
-  "input": "stdin",
-  "preTest": true,
-  "return": "state"
+  "input":            "stdin",
+  "implementsPretest": true,
+  "return":           "state"
 }
 ```
 
@@ -59,9 +59,9 @@ running:
 { ... } | registry config set
 ```
 
-Because the manifest defines `preTest` as `true`, DSC won't call the `test` method for the resource
-before calling `set`. This setting indicates that the resource itself tests instances before
-enforcing their desired state.
+Because the manifest defines `implementsPretest` as `true`, DSC won't call the `test` method for
+the resource before calling `set`. This setting indicates that the resource itself tests instances
+before enforcing their desired state.
 
 The manifest defines `return` as `state`, indicating that it only returns the final state of the
 resource after the `set` method runs. DSC compares the desired state to the return data of this
@@ -100,24 +100,43 @@ Default:  []
 
 ### input
 
-The `input` property defines how to pass input to the resource. The value of this property must
-be one of the following strings:
+The `input` property defines how to pass input to the resource. If this property isn't defined, DSC
+doesn't send any input to the resource when invoking the `set` operation.
 
-- `args` - Indicates that the resource expects the properties of an instance to be specified
-  with command line arguments. This option isn't implemented yet.
-- `stdin` - Indicates that the resource expects a JSON blob representing an instance from
-  `stdin`.
+The value of this property must be one of the following strings:
+
+- `env` - Indicates that the resource expects the properties of an instance to be specified as
+  environment variables with the same names and casing.
+
+  This option only supports the following data types for instance properties:
+
+  - `boolean`
+  - `integer`
+  - `number`
+  - `string`
+  - `array` of `integer` values
+  - `array` of `number` values
+  - `array` of `string` values
+
+  For non-array values, DSC sets the environment variable to the specified value as-is. When the
+  data type is an array of values, DSC sets the environment variable as a comma-delimited string.
+  For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo` environment
+  variable as `"1,2,3"`.
+
+  If the resource needs to support complex properties with an `object` value or multi-type arrays,
+  set this to `stdin` instead.
+- `stdin` - Indicates that the resource expects a JSON blob representing an instance from `stdin`.
+  The JSON must adhere to the instance schema for the resource.
 
 ```yaml
 Type:        string
 Required:    false
-Default:     stdin
-ValidValues: [args, stdin]
+ValidValues: [env, stdin]
 ```
 
-### preTest
+### implementsPretest
 
-The `preTest` property defines whether the resource tests the instance internally before
+The `implementsPretest` property defines whether the resource tests the instance internally before
 enforcing the desired state. Set this property to `true` when the resource tests the instance.
 Set this property to `false` to ensure DSC tests the instance first instead. The default value
 is `false`.