diff --git a/README.md b/README.md index a43ce3f..048a291 100644 --- 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, .psm1 - ModuleVersion = '0.0.1' # Set during release using Publish-PSModule. - CompatiblePSEditions = @() # Get from source files, requires -PSEdition , null if not provided. - 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 .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 = '' # 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 [.], 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,8 +147,8 @@ 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. } ``` @@ -151,7 +156,7 @@ Linking the description to the module manifest file might show more how this wor This action does not require any special permissions. -## Sources +## References **Module manifest:**