Skip to content

Commit 39224ab

Browse files
MariusStorhaugMariusStorhaug
committed
docs(readme): update workflow overview and repository structure for improved clarity and navigation
1 parent fedad44 commit 39224ab

File tree

1 file changed

+130
-40
lines changed

1 file changed

+130
-40
lines changed

‎README.md‎

Lines changed: 130 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -39,45 +39,50 @@ Depending on the labels in the pull requests, the [workflow will result in diffe
3939

4040
![Process diagram](./media/Process-PSModule.png)
4141

42-
- [Process-PSModule](#process-psmodule)
43-
- [How to get started](#how-to-get-started)
44-
- [How it works](#how-it-works)
45-
- [Workflow overview](#workflow-overview)
46-
- [Get-Settings](#get-settings)
47-
- [Lint-Repository](#lint-repository)
48-
- [Get settings](#get-settings-1)
49-
- [Build module](#build-module)
50-
- [Test source code](#test-source-code)
51-
- [Lint source code](#lint-source-code)
52-
- [Framework test](#framework-test)
53-
- [Test module](#test-module)
54-
- [Setup and Teardown Scripts](#setup-and-teardown-scripts)
55-
- [Setup - `BeforeAll.ps1`](#setup---beforeallps1)
56-
- [Example - `BeforeAll.ps1`](#example---beforeallps1)
57-
- [Teardown - `AfterAll.ps1`](#teardown---afterallps1)
58-
- [Example - `AfterAll.ps1`](#example---afterallps1)
59-
- [Get test results](#get-test-results)
60-
- [Get code coverage](#get-code-coverage)
61-
- [Publish module](#publish-module)
62-
- [Build docs](#build-docs)
63-
- [Build site](#build-site)
64-
- [Publish Docs](#publish-docs)
65-
- [Usage](#usage)
66-
- [Inputs](#inputs)
67-
- [Secrets](#secrets)
68-
- [Permissions](#permissions)
69-
- [Scenario Matrix](#scenario-matrix)
70-
- [Configuration](#configuration)
71-
- [Example 1 - Defaults with Code Coverage target](#example-1---defaults-with-code-coverage-target)
72-
- [Example 2 - Rapid testing](#example-2---rapid-testing)
73-
- [Example 3 - Configuring the Repository Linter](#example-3---configuring-the-repository-linter)
74-
- [Disabling the Linter](#disabling-the-linter)
75-
- [Configuring Linter Validation Rules](#configuring-linter-validation-rules)
76-
- [Additional Configuration](#additional-configuration)
77-
- [Showing Linter Summary on Success](#showing-linter-summary-on-success)
78-
- [Repository structure](#repository-structure)
79-
- [Module source code structure](#module-source-code-structure)
80-
- [Principles and practices](#principles-and-practices)
42+
43+
- [Get settings](#get-settings)
44+
- Reads the settings file `github/PSModule.yml` in the module repository to configure the workflow.
45+
- Gathers context for the process from GitHub and the repo files, configuring what tests to run, if and what kind of release to create, and wether
46+
to setup testing infrastructure and what operating systems to run the tests on.
47+
- [Build module](./.github/workflows/Build-Module.yml)
48+
- Compiles the module source code into a PowerShell module.
49+
- [Test source code](./.github/workflows/Test-SourceCode.yml)
50+
- Tests the source code in parallel (matrix) using:
51+
- [PSModule framework settings for style and standards for source code](https://github.com/PSModule/Test-PSModule?tab=readme-ov-file#sourcecode-tests)
52+
- This produces a JSON-based report that is used to later evaluate the results of the tests.
53+
- [Lint source code](./.github/workflows/Lint-SourceCode.yml)
54+
- Lints the source code in parallel (matrix) using:
55+
- [PSScriptAnalyzer rules](https://github.com/PSModule/Invoke-ScriptAnalyzer)
56+
- This produces a JSON-based report that is used to later evaluate the results of the linter.
57+
- [Framework test](./.github/workflows/Test-Module.yml)
58+
- Tests and lints the module in parallel (matrix) using:
59+
- [PSModule framework settings for style and standards for modules](https://github.com/PSModule/Test-PSModule?tab=readme-ov-file#module-tests)
60+
- [PSScriptAnalyzer rules](https://github.com/PSModule/Invoke-ScriptAnalyzer)
61+
- This produces a JSON-based report that is used to later evaluate the results of the tests.
62+
- [Test module](./.github/workflows/Test-ModuleLocal.yml)
63+
- Imports and tests the module in parallel (matrix) using Pester tests from the module repository.
64+
- Supports setup and teardown scripts executed via separate dedicated jobs:
65+
- `BeforeAll`: Runs once before all test matrix jobs to set up the test environment (e.g., deploy infrastructure, download test data).
66+
- `AfterAll`: Runs once after all test matrix jobs complete to clean up the test environment (e.g., remove test resources, clean up databases).
67+
- Setup/teardown scripts are automatically detected in test directories and executed with the same environment variables as the tests.
68+
- This produces a JSON-based report that is used to later evaluate the results of the tests.
69+
- [Get test results](./.github/workflows/Get-TestResults.yml)
70+
- Gathers the test results from the previous steps and creates a summary of the results.
71+
- If any tests have failed, the workflow will fail here.
72+
- [Get code coverage](./.github/workflows/Get-CodeCoverage.yml)
73+
- Gathers the code coverage from the previous steps and creates a summary of the results.
74+
- If the code coverage is below the target, the workflow will fail here.
75+
- [Build docs](./.github/workflows/Build-Docs.yml)
76+
- Generates documentation and lints the documentation using:
77+
- [super-linter](https://github.com/super-linter/super-linter).
78+
- [Build site](./.github/workflows/Build-Site.yml)
79+
- Generates a static site using:
80+
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
81+
- [Publish site](./.github/workflows/Publish-Site.yml)
82+
- Publishes the static site with the module documentation to GitHub Pages.
83+
- [Publish module](./.github/workflows/Publish-Module.yml)
84+
- Publishes the module to the PowerShell Gallery.
85+
- Creates a release on the GitHub repository.
8186

8287
### Get-Settings
8388

@@ -544,12 +549,97 @@ For a complete list of available environment variables and configuration options
544549

545550
## Repository structure
546551

547-
Repo highlevel
552+
Process-PSModule expects repositories to follow the staged layout produced by Template-PSModule. The workflow inspects this structure to decide what to compile, document, and publish.
553+
554+
```plaintext
555+
<ModuleName>/
556+
├── .github/ # Workflow config, doc/site templates, automation policy
557+
│ ├── linters/ # Rule sets applied by shared lint steps
558+
│ │ ├── .markdown-lint.yml # Markdown rules enforced via super-linter
559+
│ │ ├── .powershell-psscriptanalyzer.psd1 # Analyzer profile for test jobs
560+
│ │ └── .textlintrc # Text lint rules surfaced in Build Docs summaries
561+
│ ├── workflows/ # Entry points for the reusable workflow
562+
│ │ └── Process-PSModule.yml # Consumer hook into this workflow bundle
563+
│ ├── CODEOWNERS # Default reviewers enforced by Process-PSModule checks
564+
│ ├── dependabot.yml # Dependency update cadence handled by GitHub
565+
│ ├── mkdocs.yml # MkDocs config consumed during site builds
566+
│ ├── PSModule.yml # Settings parsed to drive matrices
567+
│ └── release.yml # Release automation template invoked on publish
568+
├── examples/ # Samples referenced in generated documentation
569+
│ └── General.ps1 # Example script ingested by Document-PSModule
570+
├── icon/ # Icon assets linked from manifest and documentation
571+
│ └── icon.png # Default module icon (PNG format)
572+
├── src/ # Module source, see "Module source code structure" below
573+
├── tests/ # Pester suites executed during validation
574+
│ ├── AfterAll.ps1 (optional) # Cleanup script for ModuleLocal runs
575+
│ ├── BeforeAll.ps1 (optional) # Setup script for ModuleLocal runs
576+
│ └── <ModuleName>.Tests.ps1 # Primary test entry point
577+
├── .gitattributes # Normalizes line endings across platforms
578+
├── .gitignore # Excludes build artifacts from source control
579+
├── LICENSE # License text surfaced in manifest metadata
580+
└── README.md # Repository overview rendered on GitHub and docs landing
581+
```
582+
583+
Key expectations:
584+
585+
- Keep at least one exported function under `src/functions/public/` and corresponding tests in `tests/`.
586+
- Optional folders (`assemblies`, `formats`, `types`, `variables`, and others) are processed automatically when present.
587+
- Markdown files in `src/functions/public` subfolders become documentation pages alongside generated help.
588+
- The build step compiles `src/` into a root module file and removes the original project layout from the artifact.
589+
- Documentation generation mirrors the `src/functions/public` hierarchy so help content always aligns with source.
548590

549591
## Module source code structure
550592

551593
How the module is built.
552594

595+
```
596+
├── src/ # Module source compiled and documented by the pipeline
597+
│ ├── assemblies/ # Bundled binaries copied into the build artifact
598+
│ ├── classes/ # Class scripts merged into the root module
599+
│ │ ├── private/ # Internal classes kept out of exports
600+
│ │ │ └── SecretWriter.ps1 # Example internal class implementation
601+
│ │ └── public/ # Public classes exported via type accelerators
602+
│ │ └── Book.ps1 # Example public class documented for consumers
603+
│ ├── data/ # Configuration loaded into `$script:` scope at runtime
604+
│ │ ├── Config.psd1 # Example config surfaced in generated help
605+
│ │ └── Settings.psd1 # Additional configuration consumed on import
606+
│ ├── formats/ # Formatting metadata registered during build
607+
│ │ ├── CultureInfo.Format.ps1xml # Example format included in manifest
608+
│ │ └── Mygciview.Format.ps1xml # Additional format loaded at import
609+
│ ├── functions/ # Function scripts exported by the module
610+
│ │ ├── private/ # Helper functions scoped to the module
611+
│ │ │ ├── Get-InternalPSModule.ps1 # Sample internal helper
612+
│ │ │ └── Set-InternalPSModule.ps1 # Sample internal helper
613+
│ │ └── public/ # Public commands documented and tested
614+
│ │ ├── Category/ # Optional: organize commands into categories
615+
│ │ │ ├── Get-CategoryCommand.ps1 # Command file within category
616+
│ │ │ └── Category.md # Category overview merged into docs output
617+
│ │ ├── Get-PSModuleTest.ps1 # Example command captured by Microsoft.PowerShell.PlatyPS
618+
│ │ ├── New-PSModuleTest.ps1 # Example command exported and tested
619+
│ │ ├── Set-PSModuleTest.ps1 # Example command exported and tested
620+
│ │ └── Test-PSModuleTest.ps1 # Example command exported and tested
621+
│ ├── init/ # Initialization scripts executed during module load
622+
│ │ └── initializer.ps1 # Example init script included in build output
623+
│ ├── modules/ # Nested modules packaged with the compiled output
624+
│ │ └── OtherPSModule.psm1 # Example nested module staged for export
625+
│ ├── scripts/ # Scripts listed in 'ScriptsToProcess'
626+
│ │ └── loader.ps1 # Loader executed when the module imports
627+
│ ├── types/ # Type data merged into the manifest
628+
│ │ ├── DirectoryInfo.Types.ps1xml # Type definition registered on import
629+
│ │ └── FileInfo.Types.ps1xml # Type definition registered on import
630+
│ ├── variables/ # Variable scripts exported by the module
631+
│ │ ├── private/ # Internal variables scoped to the module
632+
│ │ │ └── PrivateVariables.ps1 # Example private variable seed
633+
│ │ └── public/ # Public variables exported and documented
634+
│ │ ├── Moons.ps1 # Example variable surfaced in generated docs
635+
│ │ ├── Planets.ps1 # Example variable surfaced in generated docs
636+
│ │ └── SolarSystems.ps1 # Example variable surfaced in generated docs
637+
│ ├── finally.ps1 # Cleanup script appended to the root module
638+
│ ├── header.ps1 # Optional header injected at the top of the module
639+
│ ├── manifest.psd1 (optional) # Source manifest reused when present
640+
│ └── README.md # Module-level docs ingested by Document-PSModule
641+
```
642+
553643
## Principles and practices
554644
555645
The contribution and release process is based on the idea that a PR is a release, and we only maintain a single linear ancestry of versions, not going

0 commit comments

Comments
 (0)