PowerShell / PowerShell/DSC

Semantic vocabulary proposal: From "well-known properties" to "canonical properties"

Open
#633 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Issue-Enhancement Needs Triage
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.