search

PowerShell / DscResources

Central repository for PowerShell Desired State Configuration (DSC) resources.
http://blogs.msdn.com/b/powershell/
MIT License
776 stars 205 forks source link

Question regarding the advised module structure #481

Closed mrhockeymonkey closed 5 years ago

mrhockeymonkey commented 5 years ago

Many DSC resource repos, including ComputerManagementDSC and NetworkingDSC, direct people to the contributing.md file in this repo. However there is a discrepancy between the advised module structure and the structure these resources actually use. To illustrate:

Advised

  * Root folder (e.g. SampleResourceModuleDsc)
    * DscResources
      * SampleResource
        * SampleResource.psm1
        * SampleResource.schema.mof
    * Tests
      * Unit
        * SampleResource.Tests.ps1
      * Integration
        * SampleResource.Integration.Tests.ps1
    * Examples
      * SampleResource.Example.ps1
    * Module manifest (e.g. SampleResourceModuleDsc.psd1)

Actual:

* Root folder
  * Modules
    * NetworkingDSC
      * Examples
      * DSCResources
        * MSFT_Route
      * Module Manifest
  * Tests

Perhaps the documentation needs to be updated and this is the new preferred way?

If it is indeed a new format I just had one quick question. How exactly are people doing local development? With the (presumably) old way I used to clone a repo into "C:\Program Files\WindowsPowerShell\Modules" and by merit of the structure it all worked nicely. Perhaps there is some trick with this new format I am missing that gets any local changes into my module path?

Just for context I am working on making all our own internal DSC resources align more closely with whats happening in the community is why I am intrigued.

Thanks

PlagueHO commented 5 years ago

Hi @mrhockeymonkey - a great question with a bit of history attached.

Early on, all the original DSC resources had the "Advised" structure. However, the maintainers over on SharePointDsc adopted an "auto-documentation generation" model and some other changes to make maintenance easier and to automatically build a GitHub Wiki. But this required that they reorganize the "Actual" structure.

The maintainers (myself and others) of some of the other resources decided to adopt what SharePointDsc had done so we could get the benefits too. So we moved lots of the modules over to the "Actual" structure.

But about a year ago we refactored DscResource.Tests so that we could get the benefits of "auto-documentation generation" without needing the different structure SharePointDsc used.

So I've been slowly refactoring all the "Actual" structure resources back to "Advised" structure - but it takes a while :cry: - NetworkingDsc and ComputerManagementDsc are the last ones to go but I wanted to get some of the open PRs through on them before migration (didn't want to completely mess up the contributors PR's).

See these issues for more context and tracking on progress of moving back to "Advised": https://github.com/PowerShell/DscResource.Tests/issues/225 https://github.com/PowerShell/ComputerManagementDsc/issues/188 https://github.com/PowerShell/NetworkingDsc/issues/372

tl;dr: Use "Advised" - we're in process of moving NetworkingDsc and ComputerManagementDsc back to "Advised". So recommend using "Advised" for your internal resources. If you want to use "Auto-documentation" in an "Advised" module structure, see StorageDsc or CertificateDsc.

HTH?

mrhockeymonkey commented 5 years ago

Ah, I just so happened to choose the last two ha ha. Thank you for explaining. I'll close this off :+1: