MicrosoftDocs
Draft resource authoring design guide
PR Summary
This change drafts the conceptual documentation for guidance on how to author DSC resources from a design perspective. It does not include any specific guidance from a code or language perspective.
Instead, it focuses on the high level concepts and on defining the resource manifest and instance JSON Schema.
This change is a mirror of the one submitted to the source repository:
- PowerShell/DSC#1027
To do:
- [ ] Draft guidance for typical resource manifests
- [ ] Draft guidance for defining a typical resource instance schema
- [ ] Draft guidance for exporter resource manifests
PR Checklist
- [x] Descriptive Title: This PR's title is a synopsis of the changes it proposes.
- [x] Summary: This PR's summary describes the scope and intent of the change.
- [x] Contributor's Guide: I have read the contributors guide.
- [x] Style: This PR adheres to the style guide.
PoliCheck Scan Report
The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.
:white_check_mark: No issues found
More information about PoliCheck
Information: PoliCheck | Severity Guidance | Term For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.
![learn-build-service-prod[bot] avatar](https://avatars.githubusercontent.com/in/237442?v=4 "Published by a pub.dev verified publisher"){kind=small}
Learn Build status updates of commit 2f7be55:
:warning: Validation status: warnings
dsc/docs-conceptual/dsc-3.0
-
Line 0, Column 0: [Warning: folder-name-invalid-character - See documentation]
Only lowercase letters, numbers, and hyphens are allowed in folder names. -
Line 0, Column 0: [Suggestion: folder-name-incomplete - See documentation]
The folder name contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.
dsc/docs-conceptual/dsc-3.0/concepts/resources/authoring/toc.yml
-
Line 11, Column 11: [Warning: file-not-found - See documentation]
Invalid file link: 'defining-operation-invocations.md'.
dsc/docs-conceptual/dsc-3.0/concepts/resources/authoring/exit-codes.md
-
Line 3, Column 3: [Suggestion: duplicate-descriptions - See documentation]
Attribute 'description' with value 'Considerations and guidance for defining exit codes for a resource.' is duplicated in 'docs-conceptual/dsc-3.0/concepts/resources/authoring/exit-codes.md(3,3)', 'docs-conceptual/dsc-3.0/concepts/resources/authoring/operation-invocations.md(3,3)'.
dsc/docs-conceptual/dsc-3.0/concepts/resources/authoring/operation-invocations.md
-
Line 3, Column 3: [Suggestion: duplicate-descriptions - See documentation]
Attribute 'description' with value 'Considerations and guidance for defining exit codes for a resource.' is duplicated in 'docs-conceptual/dsc-3.0/concepts/resources/authoring/exit-codes.md(3,3)', 'docs-conceptual/dsc-3.0/concepts/resources/authoring/operation-invocations.md(3,3)'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
PoliCheck Scan Report
The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.
:white_check_mark: No issues found
More information about PoliCheck
Information: PoliCheck | Severity Guidance | Term For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.
Learn Build status updates of commit 6883779:
:warning: Validation status: warnings
dsc/docs-conceptual/dsc-3.0
-
Line 0, Column 0: [Warning: folder-name-invalid-character - See documentation]
Only lowercase letters, numbers, and hyphens are allowed in folder names. -
Line 0, Column 0: [Suggestion: folder-name-incomplete - See documentation]
The folder name contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.
dsc/docs-conceptual/dsc-3.0/concepts/resources/authoring/toc.yml
-
Line 11, Column 11: [Warning: file-not-found - See documentation]
Invalid file link: 'defining-operation-invocations.md'.
dsc/docs-conceptual/dsc-3.0/concepts/resources/authoring/exit-codes.md
-
Line 3, Column 3: [Suggestion: duplicate-descriptions - See documentation]
Attribute 'description' with value 'Considerations and guidance for defining exit codes for a resource.' is duplicated in 'docs-conceptual/dsc-3.0/concepts/resources/authoring/exit-codes.md(3,3)', 'docs-conceptual/dsc-3.0/concepts/resources/authoring/operation-invocations.md(3,3)'.
dsc/docs-conceptual/dsc-3.0/concepts/resources/authoring/operation-invocations.md
-
Line 3, Column 3: [Suggestion: duplicate-descriptions - See documentation]
Attribute 'description' with value 'Considerations and guidance for defining exit codes for a resource.' is duplicated in 'docs-conceptual/dsc-3.0/concepts/resources/authoring/exit-codes.md(3,3)', 'docs-conceptual/dsc-3.0/concepts/resources/authoring/operation-invocations.md(3,3)'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
PoliCheck Scan Report
The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.
:white_check_mark: No issues found
More information about PoliCheck
Information: PoliCheck | Severity Guidance | Term For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.
Learn Build status updates of commit b1c7d43:
:warning: Validation status: warnings
dsc/docs-conceptual/dsc-3.0
-
Line 0, Column 0: [Warning: folder-name-invalid-character - See documentation]
Only lowercase letters, numbers, and hyphens are allowed in folder names. -
Line 0, Column 0: [Suggestion: folder-name-incomplete - See documentation]
The folder name contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.