Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Design Document: Built-in resources

Aperta
  • Qualcosa non va?
#1,539 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Documentazione
Chiarezza
Da chiarire
Stato di attività
Tranquilla
Stack tecnologico
json
Ambito
documentation

Direzione di ricerca

Nell'issue non sono indicati file, test o entry point. Definisci e documenta i principi di progettazione per le risorse integrate, inclusi i requisiti elencati relativi a schema, operazione, what-if, proprietà, nullability e risorse complementari; il lavoro è considerato completato quando i principi sono registrati in un documento di progettazione concordato.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Doc-Impact

We need to define some design principles for built-in resources so we can ensure that the resources that ship with DSC follow best practices and provide first-class ergonomics to users. The built-in resources serve both as examples for resource design and will be among the most-used resources.

During the review for the 3.2 GA, I noticed a few specific design principles we should call out. The following list is non-exhaustive:

  1. Only define the _exist canonical property at the top-level for a resource instance JSON Schema and only when the resource can both create and delete instances. The resource must implement the canonical property in adherence to the contract. Don't define _exist for nested instances of a *List resource, since those instances can't participate in the engine semantics for existence.
  2. When a resource has the _exist canonical property it should implement the get, set, export, and delete operations.
  3. Always implement what-if support for set and delete operations.
  4. Always return all non-write-only properties for the actual state of a resource if those property values are knowable. If the values are not knowable for a given operation, omit those properties from the return data. In JSON Schema defining a property as null and omitting the property are semantically distinct representations of data. Only populate a field with null when that actually matches the underlying resource behavior (when the resource has a nullable property, rather than an unset or undiscoverable property value).
  5. Always mark properties that can be passed to but not returned by the resource with the writeOnly keyword.
  6. Always mark properties that can be returned by but not passed to the resource with the readOnly keyword.
  7. Never add null as a valid value for a property in the instance JSON Schema when null indicates that you aren't passing a value for the property. Only allow null for properties where null is a valid value for that property.
  8. When creating a *List resource to manage multiple instances, also be sure to create a companion resource that manages a single instance. We should direct users towards the *List resource options only when the performance impact for single instances is too high. Those resources are much less ergonomic for result output and are somewhat obfuscated in the node graph. Using those resources necessitates tradeoffs in ergonomics for authoring vs reporting and performance vs clarity.
Lingua principale
Rust
Stelle
536
Fork
76
Merge medio
1g 11h
PR unite (30g)
15

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di PowerShell/DSC

Tutte le issue di PowerShell/DSC

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.