PSModule simplifies how to go from idea to having a module published with decent standards and practices. This is done using a collection of GitHub Actions and PowerShell modules that build, test and publish PowerShell modules. The framework sets standard when it comes to code structure and quality so that its easy to build automation around it to handles the tedious tasks, and as a developer you can focus on the code.

• Everything as code
• Simplify by automating everything
• Standardize and enforce good practices

1. Create a repository based on the template PSModuleTemplate. The module will by default use the name of the repository. See Process-PSModule for more info on choosing another name than the repository name.
2. Create a repository or organization secret called APIKEY, holding the API key for the PowerShell Gallery.
3. Configure the settings you want for the repository including a branch policy for the main branch.
4. On a topic branch:
   1. develop the code you want to add to your module.
   2. delete the parts you do not need.
   3. update the tests in the tests folder.
5. Create a PR. Add a label to the PR depending on what you want to do.
   • "Major" - Will create a major release (vX.0.0) when merged. If specified with "Prerelease", a major version will be created using the prerelease tag (vX.0.0-<branchName>).
   • "Minor" - Will create a minor release (vX.Y.0) when merged. If specified with "Prerelease", a minor version will be created using the prerelease tag (vX.Y.0-<branchName>).
   • "Patch" - Will create a minor release (vX.Y.Z) when merged. If specified with "Prerelease", a minor version will be created using the prerelease tag (vX.Y.Z-<branchName>). A patch version bump is the default if nothing is specified for the PR.
   • "Prerelease" - CI will create a prerelease of the module using the branch name as a prerelease tag in the version. This will create both a repository release and a prerelease version of the module on the PowerShell Gallery.
6. Once the PR is created, the Process-PSModule workflow will trigger.
7. When the PR is merged, a release will be created and the module will be published to the PowerShell Gallery with a stable version based on the version bump indicator the PR was was labeled with. Prerelease tags will be cleaned up on the repository.

PSModule on the GitHub Marketplace

Name	Description	Version
Auto‑Release	Handles release of a GitHub repo using PR based triggered Actions and labels in the PR.
Process‑PSModule	A GitHub workflow that is used as a template in PowerShell module repos to build, test and publish the module using the PSModule framework.
Initialize‑PSModule	An action that is used to prepare the GitHub runner for the PSModule framework.
Test‑PSModule	Runs static code analysis and pester tests on source code or a built module. The tests are some framework specific tests and tests from within the module repo.
Build‑PSModule	Build the project from different files and structures dynamically based on the defaults defined in the framework. The results of the build should be a module that runs and is ready to be published to PowerShell Gallery with documentation ready to be published on GitHub Pages.
Publish‑PSModule	Calculates the version number, updates module files with version, create a repo release and finally publish module to PowerShell Gallery and documentation to GitHub Pages.

Name	Description	Version
Admin	A PowerShell module working with the admin role.
AST	A PowerShell module for using the Abstract Syntax Tree (AST) to analyze any PowerShell code.
AzureDevOps	A PowerShell module to interact with the Azure DevOps REST API.
DynamicParams	A PowerShell module that makes it easier to use dynamic params.
Fonts	A PowerShell module for managing fonts.
GitHub	A PowerShell module to interact with the GitHub API.
GoogleFonts	A PowerShell module to download and install fonts from GoogleFonts.
NerdFonts	A PowerShell module to download and install fonts from NerdFonts.
PATH	A PowerShell module to manage the PATH environment variable on Windows.
PowerShellGallery	A PowerShell module for interacting with the PowerShell Gallery.
PSSemVer	A PowerShell module adding a SemVer compatible class and functions.
PublicIP	A PowerShell module that helps getting info about your public IP.
Store	A PowerShell module that manages a store of secrets and variables.
Utilities	A PowerShell module with a collection of functions that should have been in PowerShell to start with.
WoW	A PowerShell module containing utilities for World of Warcraft.

• A repository manages ONE module.
• A repository has releases that are in line with the version of the published package.
• The version of a repository follows semver 2.0.0 based on the changes to the module, and not the framework or any other external factor from the module.

• The output folder = .\outputs on the root of the repo.
• The module that is build is stored under the output folder in a folder with the same name as the module.

The test and build process is based on the following repository structure. The PSModule framework is expecting the modules to follow this structure as some of the paths and calculations are based on this structure. Not following this might result in the build process not working as expected.

.
├─ .github/
│  └- workflows/
│     └- Process-PSModule.yml              # The workflow file based on [Process-PSModule](https://github.com/PSModule/Process-PSModule) template.
├─ .vscode/                                # The settings for the Visual Studio Code aligned with the PSModule framework formatting and linting practices.
├─ icon/
|  └- <icon>.png                           # Icon file automatically used in the module manifest file if nothing else is specified.
├─ outputs/                                # The output folder created during build. This is a temporary folder that should not be committed to the repository.
|  ├─ docs/                                # The output folder for the documentation.
|  |  └─ ModuleName/                       # The output folder for the module.
|  └─ modules/                             # The output folder for the module.
|     └─ ModuleName/                       # The output folder for the module.
├─ src/                                    # The source code for the module.
│  ├─ ModuleName/                          # The source code folder for the module. Kept like this for ease of testing. This folder can be loaded as a module.
│  │  ├─ assembly/                         # All .dll files are collected to RequiredAssemblies
│  │  │  └─ <dlls>                         # loaded during import via RequiredAssemblies
│  │  ├─ classes/                          # All .ps1 files are collected to ScriptsToProcess and loaded to the caller session (parent of module session)
│  │  │  ├─ <ClassName>.ps1                # loaded during import via ScritsToProcess
│  │  │  ├─ <ClassName>.Format.ps1xml      # loaded during import via FormatsToProcess (collected based on *.Formats.ps1xml files in the root of the folder)
│  │  │  └─ <ClassName>.Types.ps1xml       # loaded during import via TypesToProcess (collected based on *.Types.ps1xml files in the root of the folder)
│  │  ├─ data/                             # Loads .psd1 files into the module session.
│  │  ├─ en/
│  │  |  ├─ en-US/                         # Search here first for OS = en-US, then parent, en. Get-Help and platyPS reads this.
│  │  │  └─ about_<ComponentName>.help.txt
│  │  ├─ init/                             # All .ps1 files are added to the root module and can contain scripts that run during import before functions are loaded.
│  │  ├─ modules/                          # All .dll, psm1 and ps1 files are collected to NestedModules and loaded to the module session.
│  │  ├─ private/                          # All .ps1 files are added to the root module, but not exported to the caller session.
│  │  ├─ public/                           # All .ps1 files are added to the root module, and exported to the caller session.
|  |  ├─ resources/                        # All .psm1 files are collected to DscResourcesToExport and loaded to the module session.
│  │  ├─ scripts/                          # All .ps1 files are collected to ScriptsToProcess and loaded to the caller session (parent of module session)
|  |  ├─ <ScriptName>.ps1                  # All *.ps1 files are added to the root module last and can contain scripts that run during import after functions are loaded.
|  |  ├─ header.ps1                        # Added to the root module first. Typically for Pester supressions and [CmdletBinding()].
│  │  ├─ ModuleName.psd1                   # The module manifest file, if not present, it is generated.
│  │  └- ModuleName.psm1                   # The root module file, if not present, it is generated from the source files.
├─ tests/
│  └- ModuleName/
│     └- ModuleName.Tests.ps1
├─ .gitattributes
├─ .gitignore
├─ LICENSE                                 -> The license file for the module. Used in the module manifest file.
└─ README.md

To be filled later.

...

• Documentation uses comment-based documentation, placed first in the function block.
• Documentations contains synopsis, description (not copy paste from synopsis), atleast one example.
  • If the function generates outputs, the output should be documented using the .OUTPUT <OutputType> doc tag.
  • If the function takes input by pipeline, the input should be documented using the .INPUT <InputType> doc tag.
• Parameter documentation that are not dynamic, exists inside the param() block, above the function.

• The ModuleVersion is generated from the Publish-PSModule function, based on available version and lables on PRs, not from the module manifest.
• The basis of the module manifest comes from the source manifest file.
• Values that are not defined in the module manifest file are generated from reading the module files and github repository properties.
• If no RootModule is defined in the manifest file, a file with the name of the folder is searched for with a compatible file extension.
• A new module manifest file is created every time to get a new GUID, so that the specific version of the module can be imported.

• Use the composite action to load prerequisite modules. I.e., 'Utilities'.
• Run the main functionality from a main.ps1 file located in a scripts folder.
• The action inputs are written in PascalCase and uses the natural language name of the input.
• Use envvironment variables to pass data between the composite action and the main.ps1 file.
• Prefix the environment variable with GITHUB_ACTION_INPUT_ followed by the name of the action input to avoid collision with other environment variables.
• Have a readme.md file in the action folder that explains the action and how to use it.
• Have a Action-Test workflow file that tests the action.
• Use the Auto-Release action for automating the release of the action via pull requeusts.
• Actions versions must be available as vX, vX.Y and vX.Y.Z tags, where they get the updates on their respective version.
  • vX automatically gets all the feature and patch updates until a breaking change is introduced.
  • vX.Y automatically gets all the patch updates until a new feature is introduced.
  • vX.Y.Z is locked to the exact version and will not get any updates.
• Older version of the action are not updates on their given track. i.e., if an older version of the action has bugs or a security issue, the fix will be implemented on the latest version and the user will have to update to the latest version to get the fix.

• Actions should have parameters to configure the action with smart default values.
• Actions should also be able to take a configuration file as a yaml file, that is stored in the repository's .github folder.
• The configuration should also be able to be stored in the organizations .github repository, to simplify configuration control for all the repositories in the organization.
• The configuration should be called the name of the action/workflow and be a yaml file.
• Configuration precedence is as follows:
  1. Action inputs, over
  2. Repository configuration, over
  3. Organization configuration, over
  4. Action inputs default values.
• Configuration processing is as follows:
  1. Start with defaults from the action.
  2. Load the configuration from the organization .github repository, overwriting defined values only.
  3. Load the configuration from the repository .github folder, overwriting defined values only.
  4. Load the configuration from the action inputs, overwriting defined values only.

• PowerShell Practices and Style
• PowerShell Best Practices and Style Guide
• Code With Engineering Playbook
  • Docs
  • GitHub repo
• Microsoft Writing Style Guide

1. Question all requirements. Make sure the requirements are valid and necessary.
2. Remove things that should not be there. Delete the part or process, if things are not added back in, you are not deleting enough.
3. Simplify or optimize, most common error is to optimize something that should not exist.
4. Streamline and improve the cycle time.
5. Automate.

Feel free to submit issues, PRs what have you. Also feel free to use as you like; be that the functions or modules we maintain here.

This project is not intented to be plagerising or stealing code from anyone without giving credit where credit is due. If any of these projects get recognition, it was achieved [by standing on the shoulders of giants]. Credit regarding pieces of the framework will be listed here, and the module specific credits will be added in the different module repos. If you think you should be mentioned, create an issue.

• cgadmin@microsoft.com
• https://github.com/PowerShell/PowerShellGallery/issues

• Awsome-Powershell
• PowerShell Module Browser | Microsoft Learn
  • Azure PowerShell
    • Namespace: Az & Az.* namespace
    • Docs | Microsoft Learn
    • PowerShell | GitHub
    • CLI | GitHub
  • Microsoft Graph PowerShell
    • Namespace: Microsoft.Graph & Microsoft.Graph.*
    • Microsoft Docs
    • PowerShell | GitHub
    • CLI | GitHub
• gaelcolas/Sampler | GitHub - Inspiration on bits and pieces that should be included in a generic PowerShell module repo, and best practices to follow (even though not all are followed here).
• FriedrichWeinmann | GitHub
• PowershellFrameworkCollective | GitHub
• PoshCode | GitHub
• PoshCode Actions | GitHub - Did not know this existed untill i started making my own. Approaches are different however.
• PoshCode ModuleBuilder | GitHub
• Evotec | GitHub

• psake, A build automation tool written in PowerShell | GitHub
• http://ramblingcookiemonster.github.io/
• https://github.com/RamblingCookieMonster/