(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,31 @@ 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.
+>
+> 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`, it indicates that the resource implements pretest. If `set.implementsPretest`
+> is set to `false` or is undefined, the manifest indicates that the resource doesn't implement
+> pretest.
+>
+> If a resource indicates that it implements pretest, users should expect that the resource only
+> modifies an instance during a `set` operation if the pretest shows that the instance isn't in the
+> desired state.
+>
+> If a resource doesn't implement pretest, users should expect that the resource always modifies an
+> instance during a `set` operation.
+>
+> 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 +129,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