|
1 | 1 | # Process-PSModule |
2 | 2 |
|
3 | | -Process-PSModule is an end-to-end GitHub Actions workflow that automates the entire lifecycle of a PowerShell module — from build and test to |
4 | | -documentation and publication. It is part of the PSModule framework and provides a unified, standards-based process for developing PowerShell modules |
5 | | -that adhere to consistent testing, linting, and release practices. |
6 | | - |
7 | | -The workflow builds the PowerShell module, runs multi-platform tests, enforces code quality and coverage requirements, generates documentation, and |
8 | | -publishes both the module to the PowerShell Gallery and its documentation site to GitHub Pages. It is the core workflow used across all PowerShell |
9 | | -modules in the [PSModule organization](https://github.com/PSModule), ensuring reliable, automated, and maintainable delivery of PowerShell projects. |
| 3 | +Process-PSModule is the corner-stone of the PSModule framework. It is an end-to-end GitHub Actions workflow that automates the entire lifecycle of a |
| 4 | +PowerShell module. The workflow builds the PowerShell module, runs cross-platform tests, enforces code quality and coverage requirements, generates |
| 5 | +documentation, and publishes module to the PowerShell Gallery and its documentation site to GitHub Pages. It is the core workflow used across all |
| 6 | +PowerShell modules in the [PSModule organization](https://github.com/PSModule), ensuring reliable, automated, and maintainable delivery of PowerShell |
| 7 | +projects. |
10 | 8 |
|
11 | 9 | ## How to get started |
12 | 10 |
|
13 | 11 | 1. [Create a repository from the Template-Module](https://github.com/new?template_name=Template-PSModule&template_owner=PSModule&description=Add%20a%20description%20(required)&name=%3CModule%20name%3E). |
14 | 12 | 1. Configure the repository: |
15 | 13 | 1. Enable GitHub Pages in the repository settings. Set it to deploy from **GitHub Actions**. |
16 | 14 | 1. This will create an environment called `github-pages` that GitHub deploys your site to. |
17 | | - <details><summary>Within the **github-pages** environment, remove the branch protection for <code>main</code>.</summary> |
18 | | - <img src="./media/pagesEnvironment.png" alt="Remove the branch protection on main"> |
19 | | - </details> |
20 | | - 1. [Create an API key on the PowerShell Gallery](https://www.powershellgallery.com/account/apikeys). Give it permission to manage the module you |
| 15 | + > [!IMPORTANT] |
| 16 | + > Within the **github-pages** environment, remove the branch protection for `main` |
| 17 | + >  |
| 18 | + 2. [Create an API key on the PowerShell Gallery](https://www.powershellgallery.com/account/apikeys). Give it permission to manage the module you |
21 | 19 | are working on. |
22 | | - 1. Create a new secret in the repository called `APIKEY` and set it to the API key for the PowerShell Gallery. |
23 | | - 1. If you are planning on creating many modules, you could use a glob pattern for the API key permissions and store the secret on the organization. |
24 | | -1. Clone the repo locally, create a branch, make your changes, push the changes, create a PR and let the workflow run. |
25 | | -1. When merging to `main`, the workflow automatically builds, tests, and publishes your module to the PowerShell Gallery and maintains the |
| 20 | + 3. Create a new secret in the repository called `APIKEY` and set it to the API key for the PowerShell Gallery. |
| 21 | + 4. If you are planning on creating many modules, you could use a glob pattern for the API key permissions and store the secret on the organization. |
| 22 | +2. Clone the repo locally, create a branch, make your changes, push the changes, create a PR and let the workflow run. |
| 23 | +3. When merging to `main`, the workflow automatically builds, tests, and publishes your module to the PowerShell Gallery and maintains the |
26 | 24 | documentation on GitHub Pages. By default the process releases a patch version, which you can change by applying labels like `minor` or `major` on |
27 | 25 | the PR to bump the version accordingly. |
28 | 26 |
|
29 | 27 | ## How it works |
30 | 28 |
|
| 29 | +Everything is packaged into this single workflow to simplify full configuration of the workflow via this repository. Simplifying management and |
| 30 | +operations across all PowerShell module projects. A user can configure how it works by simply configuring settings using a single file. |
| 31 | + |
| 32 | +### Workflow overview |
| 33 | + |
31 | 34 | The workflow is designed to be triggered on pull requests to the repository's default branch. |
32 | 35 | When a pull request is opened, closed, reopened, synchronized (push), or labeled, the workflow will run. |
33 | 36 | Depending on the labels in the pull requests, the workflow will result in different outcomes. |
34 | 37 |
|
35 | 38 |  |
36 | 39 |
|
37 | | -- [Get settings](./.github/workflows/Get-Settings.yml) |
38 | | - - Reads the settings file from a file in the module repository to configure the workflow. |
39 | | - - Gathers tests and creates test configuration based on the settings and the tests available in the module repository. |
40 | | - - This includes the selection of what OSes to run the tests on. |
| 40 | +- [Get settings](#get-settings) |
| 41 | + - Reads the settings file `github/PSModule.yml` in the module repository to configure the workflow. |
| 42 | + - 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 |
| 43 | + to setup testing infrastructure and what operating systems to run the tests on. |
41 | 44 | - [Build module](./.github/workflows/Build-Module.yml) |
42 | 45 | - Compiles the module source code into a PowerShell module. |
43 | 46 | - [Test source code](./.github/workflows/Test-SourceCode.yml) |
@@ -78,6 +81,10 @@ Depending on the labels in the pull requests, the workflow will result in differ |
78 | 81 | - Publishes the module to the PowerShell Gallery. |
79 | 82 | - Creates a release on the GitHub repository. |
80 | 83 |
|
| 84 | +### Get-Settings |
| 85 | + |
| 86 | +### Lint-Repository |
| 87 | + |
81 | 88 | ## Usage |
82 | 89 |
|
83 | 90 | To use the workflow, create a new file in the `.github/workflows` directory of the module repository and add the following content. |
@@ -453,7 +460,26 @@ This is useful for reviewing what was checked even when no issues are found. |
453 | 460 |
|
454 | 461 | For a complete list of available environment variables and configuration options, see the [super-linter environment variables documentation](https://github.com/super-linter/super-linter#environment-variables). |
455 | 462 |
|
456 | | -## Specifications and practices |
| 463 | +## Repository structure |
| 464 | + |
| 465 | +Repo highlevel |
| 466 | + |
| 467 | +## Module source code structure |
| 468 | + |
| 469 | +How the module is built. |
| 470 | + |
| 471 | +## Principles and practices |
| 472 | + |
| 473 | +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 |
| 474 | +back to patch and update old versions of the modules. This means that if we are on version `2.1.3` of a module and there is a security issue, we only |
| 475 | +patch the latest version with a fix, not releasing new versions based on older versions of the module, i.e. not updating the latest 1.x with the |
| 476 | +patch. |
| 477 | + |
| 478 | +If you need to work forth a bigger release, create a branch representing the release (a release branch) and open a PR towards `main` for this branch. |
| 479 | +For each topic or feature to add to the release, open a new branch representing the feature (a feature branch) and open a PR towards the release |
| 480 | +branch. Optionally add the `Prerelease` label on the PR for the release branch, to release preview versions before merging and releasing a published |
| 481 | +version of the PowerShell module. |
| 482 | + |
457 | 483 |
|
458 | 484 | The process is compatible with: |
459 | 485 |
|
|
0 commit comments