Semantic vocabulary proposal: From "well-known properties" to "canonical properties"
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 523
- Forks
- 75
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 24
Description
Summary of the new feature / enhancement
Early in the design and implementation of DSC, I proposed that we use the term well-known properties to describe special properties that DSC Resources could use to participate in shared semantics and behaviors with the DSC engine, like _exist and _purge.
I now believe that the more semantically accurate and useful term for these properties is canonical properties_. If a resource defines a canonical property as part of its resource instance schema, the resource is opting into a contract about the possible values for that property, expectations for how the resource uses that property, and how DSC will interpret and use that property, especially for synthetic operations.
Proposed technical implementation details (optional)
Update the documentation (and types, if the dsc_lib crate is ever intended for public publishing) to use the term canonical property or canonical properties instead of well-known property or well-known properties.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Search the documentation and the dsc_lib crate for occurrences of “well-known property” and “well-known properties.” Confirm whether the public types are in scope, then update the applicable terminology to “canonical property” or “canonical properties” and verify that no relevant references remain.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100