📖 [Docs]: Update to docs (#113)

MariusStorhaug · Copilot · web-flow · commit 3f9d3e84ad22 · 2025-04-19T13:03:48.000+02:00
## Description This pull request updates the `README.md` file to improve documentation for a PowerShell module build process. The changes include adding a new step to the build process, clarifying repository structure expectations, and renaming a section for better clarity. ### Documentation Updates: * **Added a new step to the build process:** Documented the step that uploads the module artifact for use in subsequent workflow steps. (`README.md`, [README.mdR25](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R25)) * **Defined expected repository structure:** Added a section describing the expected repository structure, referencing the `Template-PSModule` repository as an example. (`README.md`, [README.mdR40-R43](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R40-R43)) * **Renamed "Sources" section to "References":** Updated the section title to better reflect its purpose. (`README.md`, [README.mdL154-R159](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L154-R159)) ## Type of change  - [x] 📖 [Docs] - [ ] 🪲 [Fix] - [ ] 🩹 [Patch] - [ ] ⚠️ [Security fix] - [ ] 🚀 [Feature] - [ ] 🌟 [Breaking change] ## Checklist  - [x] I have performed a self-review of my own code - [x] I have commented my code, particularly in hard-to-understand areas --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
diff --git a/README.md b/README.md
@@ -22,6 +22,7 @@ This step lets you add custom build logic to process or modify the module conten
 1. **Copies the source code** of the module to an output folder.
 1. **Builds the module manifest file** based on information from the GitHub repository and the source code. For more information, please read the [Module Manifest](#module-manifest) section.
 1. **Builds the root module (.psm1) file** by combining source code and adding automation into the root module file. For more information, please read the [Root module](#root-module) section.
+1. **Uploads the module artifact** so that it can be used in the next steps of the workflow.
 
 ## Usage
 
@@ -36,6 +37,9 @@ This step lets you add custom build logic to process or modify the module conten
 | `Prerelease`        | Allow prerelease versions if available.                                                         | `false`  | `'false'`         |
 | `WorkingDirectory`  | The working directory where the script runs.                                                    | `false`  | `'.'`             |
 
+## Expected repository structure
+
+The action expects the module repository to be structured similarly to [Template-PSModule](https://github.com/PSModule/Template-PSModule).
 ## Root module
 
 The `src` folder may contain a 'root module' file. If present, the build function will disregard this file and build a new root module file based on the source code in the module folder.
@@ -90,49 +94,50 @@ During the module manifest build process the following steps are performed:
 1. `ExternalModuleDependencies` is not automated. If specified in the source manifest, that value is used.
 1. `HelpInfoURI` is not automated. If specified in the source manifest, that value is used.
 1. Create a new manifest file in the output folder with the gathered information, which also generates a new `GUID` for the module.
-1. Format the manifest file using the `Set-ModuleManifest` function from the [Utilities](https://github.com/PSModule/Utilities) module.
 
-Linking the description to the module manifest file might show more how this works:
+### Sources for properties in the manifest file
+
+Below is a list of properties in the module manifest file and their sources:
 
 ```powershell
 @{
-    RootModule             = 'Utilities.psm1' # Generated from the module name, <moduleName>.psm1
-    ModuleVersion          = '0.0.1'          # Set during release using Publish-PSModule.
-    CompatiblePSEditions   = @()              # Get from source files, requires -PSEdition <PSEdition-Name>, null if not provided.
-    GUID                   = '<GUID>'         # Generated when saving the manifest using New-ModuleManifest.
-    Author                 = 'PSModule'       # Derived from the GitHub Owner, unless specified in the source manifest.
-    CompanyName            = 'PSModule'       # Derived from the GitHub Owner, unless specified in the source manifest.
-    Copyright              = '(c) 2024 PSModule. All rights reserved.'
+    RootModule             = 'Utilities.psm1' # Generated as <ModuleName>.psm1 from the module name; can be overridden in the source manifest.
+    ModuleVersion          = '0.0.1'          # Temporary version set during the build; updated by Publish‑PSModule during the release process.
+    CompatiblePSEditions   = @()              # Determined from #Requires -PSEdition statements in source files.; defaults to @('Core','Desktop') if none found.
+    GUID                   = '<GUID>'         # New GUID generated by New‑ModuleManifest when the manifest is created.
+    Author                 = 'PSModule'       # Derived from the GitHub owner unless specified in the source manifest.
+    CompanyName            = 'PSModule'       # Derived from the GitHub owner unless specified in the source manifest.
+    Copyright              = '(c) 2024 PSModule. All rights reserved.' # Default template; overridden if specified in the source manifest.
     Description            = 'This is a module.' # Taken from the repository description or the source manifest.
-    PowerShellVersion      = ''               # Derived from source files, requires -Version <N>[.<n>], null if not provided.
-    PowerShellHostName     = ''               # Taken from the manifest file, null if not provided.
-    PowerShellHostVersion  = ''               # Taken from the manifest file, null if not provided.
-    DotNetFrameworkVersion = ''               # Taken from the manifest file, null if not provided.
-    ClrVersion             = ''               # Taken from the manifest file, null if not provided.
-    ProcessorArchitecture  = ''               # Taken from the manifest file, null if not provided.
-    RequiredModules        = @()              # Derived from source files, ensuring required modules are installed.
-    RequiredAssemblies     = @()              # Collected from assemblies\*.dll and modules\*.dll.
-    ScriptsToProcess       = @()              # Collected from scripts\*.ps1 and classes\*.ps1 ordered by name.
-    TypesToProcess         = @()              # Collected from *.Types.ps1xml files in the source folder.
-    FormatsToProcess       = @()              # Collected from *.Format.ps1xml files in the source folder.
-    NestedModules          = @()              # Collected from modules\*.psm1, modules\*.ps1, and modules\*.dll.
-    FunctionsToExport      = @()              # Collected from public\*.ps1 files.
-    CmdletsToExport        = @()              # Taken from the manifest file, or empty if not provided.
-    VariablesToExport      = @()              # Collected from variables\public\*.ps1.
-    AliasesToExport        = '*'              # Derived from functions\public\*.ps1.
-    DscResourcesToExport   = @()              # Collected from resources\*.psm1.
-    ModuleList             = @()              # A listing of all .\*.psm1 files (informational only).
-    FileList               = @()              # A listing of all .\* files (informational only).
+    PowerShellVersion      = ''               # Derived from #Requires -Version statements in source files; blank if none.
+    PowerShellHostName     = ''               # Preserved from the source manifest if provided; otherwise omitted.
+    PowerShellHostVersion  = ''               # Preserved from the source manifest if provided; otherwise omitted.
+    DotNetFrameworkVersion = ''               # Preserved from the source manifest if provided; otherwise omitted.
+    ClrVersion             = ''               # Preserved from the source manifest if provided; otherwise omitted.
+    ProcessorArchitecture  = ''               # Preserved from the source manifest if provided; otherwise omitted.
+    RequiredModules        = @()              # Gathered from #Requires -Modules statements in source files.
+    RequiredAssemblies     = @()              # Collected from assemblies/*.dll and modules/*.dll (depth = 1).
+    ScriptsToProcess       = @()              # Collected from scripts/*.ps1, loaded alphabetically into the caller session.
+    TypesToProcess         = @()              # Collected from *.Types.ps1xml files anywhere in the source folder.
+    FormatsToProcess       = @()              # Collected from *.Format.ps1xml files anywhere in the source folder.
+    NestedModules          = @()              # Collected from modules/* (.psm1, .ps1 or .dll one level down).
+    FunctionsToExport      = @()              # Collected from functions/public/*.ps1 files.
+    CmdletsToExport        = @()              # Preserved from the source manifest if provided; empty otherwise.
+    VariablesToExport      = @()              # Collected from variables/public/*.ps1 files.
+    AliasesToExport        = '*'              # Generated from functions/public/*.ps1.
+    DscResourcesToExport   = @()              # Collected from resources/*.psm1 files.
+    ModuleList             = @()              # Informational list of all additional *.psm1 files in the module.
+    FileList               = @()              # Informational list of all files in the module source folder.
     PrivateData            = @{
         PSData = @{
-            Tags                       = @() # Derived from repository topics and compatibility tags.
-            LicenseUri                 = ''  # Generated public link to .\LICENSE.
-            ProjectUri                 = ''  # Generated public link to the GitHub Repository.
-            IconUri                    = ''  # Derived from .\icon\icon.png.
-            ReleaseNotes               = ''  # To be updated during release.
-            Prerelease                 = ''  # Normalized version of the branch name, updated during release.
-            RequireLicenseAcceptance   = $false
-            ExternalModuleDependencies = @()
+            Tags                       = @()    # Generated from repository topics plus compatibility tags.
+            LicenseUri                 = ''     # Public link to LICENSE file (or value from source manifest).
+            ProjectUri                 = ''     # Public link to the GitHub repository (or value from source manifest).
+            IconUri                    = ''     # Public link to icon\icon.png (or value from source manifest).
+            ReleaseNotes               = ''     # Not automated; supply via PR or release description.
+            Prerelease                 = ''     # Managed by Publish‑PSModule; populated during release.
+            RequireLicenseAcceptance   = $false # Defaults to $false unless specified in the source manifest.
+            ExternalModuleDependencies = @()    # Not automated; preserved if present in the source manifest.
             ExperimentalFeatures       = @(
                 @{
                     Name        = "SomeExperimentalFeature"
@@ -142,16 +147,16 @@ Linking the description to the module manifest file might show more how this wor
         }
         OtherKeys = @{}
     }
-    HelpInfoURI            = ''  # Taken from the source manifest if provided.
-    DefaultCommandPrefix   = ''  # Taken from the source manifest if provided.
+    HelpInfoURI            = ''  # Not automated; preserved if provided in the source manifest.
+    DefaultCommandPrefix   = ''  # Not automated; preserved if provided in the source manifest.
 }
 ```
 
 ## Permissions
 
 This action does not require any special permissions.
 
-## Sources
+## References
 
 **Module manifest:**
 
