Skip to content

Commit e4175f8

Browse files
Add comprehensive documentation for Process-PSModule
- Introduced a new settings reference document detailing all available settings in `.github/PSModule.yml` with defaults. - Created a workflow inputs reference outlining the inputs, secrets, and permissions for the Process-PSModule reusable workflow. - Developed a design specification document explaining the architecture and workflow of Process-PSModule. - Established a specification document that outlines the requirements for the PowerShell module pipeline, including functional and non-functional requirements. - Added principles and practices documentation to guide versioning, branching, and development practices. - Removed outdated quickstart and workflow overview documents, consolidating information into new structured guides. - Updated navigation and references in the documentation to reflect the new structure and removed obsolete links. - Revised links to external coding standards to point to the updated MSX documentation.
1 parent 5e8ece6 commit e4175f8

36 files changed

Lines changed: 1212 additions & 1019 deletions

docs/content/Modules/Module-Types.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Module types
22

33
Most PSModule modules fall into one of a few archetypes. The general rules in
4-
[PowerShell module standard](Standards.md) and [PowerShell Standards](../PowerShell/Standard/index.md) always apply; this
4+
[PowerShell module standard](Standards.md) and [MSX PowerShell Standards](https://msxorg.github.io/docs/Coding-Standards/PowerShell/) always apply; this
55
page adds the conventions that are specific to a module's type so that modules of the same kind feel
66
the same to use.
77

docs/content/Modules/Process-PSModule/build-test-pack-publish.md

Lines changed: 0 additions & 21 deletions
This file was deleted.

docs/content/Modules/Process-PSModule/design.md

Lines changed: 0 additions & 218 deletions
This file was deleted.
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Get started
3+
description: Create a module repository from the PSModule template and get the Process-PSModule pipeline running.
4+
---
5+
6+
# Get started
7+
8+
Start new modules from the PSModule template repository:
9+
[Template-PSModule](https://github.com/PSModule/Template-PSModule).
10+
11+
## Quickstart
12+
13+
1. [Create a new repository from the template](https://github.com/new?template_name=Template-PSModule&template_owner=PSModule&description=Add%20a%20description%20(required)&name=%3CModule%20name%3E).
14+
2. [Configure the repository](repository-setup.md) — GitHub Pages, the PowerShell Gallery API key, and the caller workflow.
15+
3. Replace placeholder metadata and remove scaffold sample files.
16+
4. Add your first public command and tests.
17+
5. Validate `.github/PSModule.yml` defaults for your module.
18+
6. [Open a draft pull request](your-first-release.md) and run the full pipeline.
19+
20+
If the module needs several interdependent commands before it is usable at all, see
21+
[Module bootstrap](module-bootstrap.md) instead of shipping them as one command per step.
22+
23+
## Expected outcomes
24+
25+
- The repository follows the [expected structure](../guides/structuring-your-module.md).
26+
- The module can be built and tested in CI.
27+
- The release strategy is ready when functionality is implemented.
28+
29+
## In this section
30+
31+
| Page | Description |
32+
| --- | --- |
33+
| [Repository setup](repository-setup.md) | GitHub Pages, the PowerShell Gallery API key, permissions, and the caller workflow. |
34+
| [Your first release](your-first-release.md) | The pull request flow, version labels, and what happens on merge. |
35+
| [Module bootstrap](module-bootstrap.md) | Getting a brand-new module to its first release with an integration branch. |
36+
37+
For framework-level practices, refer to [MSX Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/).

docs/content/Modules/Process-PSModule/module-bootstrap.md renamed to docs/content/Modules/Process-PSModule/get-started/module-bootstrap.md

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
1-
# Module Bootstrap
1+
---
2+
title: Module bootstrap
3+
description: How to get a brand-new module to its first release using a single integration branch for the load-bearing core.
4+
---
5+
6+
# Module bootstrap
27

38
A brand-new module usually has a small **load-bearing core**: the piece(s) every other function will depend on, without which nothing else in the module can work at all. A single feature PR cannot carry that much scope and still be small and focused, so bootstrap uses one integration branch instead.
49

510
## Identify the load-bearing core first
611

7-
What counts as "load-bearing" follows the module's archetype from [Module types](../Module-Types.md):
12+
What counts as "load-bearing" follows the module's archetype from [Module types](../../Module-Types.md):
813

914
- **Data modules** — the conversion pivot: `ConvertFrom-<Format>` / `ConvertTo-<Format>` (and whatever parser/serializer they wrap). Every other function (`Import-`, `Export-`, `Format-`, `Merge-`, ...) is built on top of this pivot and is meaningless without it.
1015
- **Integration (API) modules** — a [`Context`](https://github.com/PSModule/Context)-backed credential/config store, the client setup that uses it, and at least one API function that consumes the context end-to-end. Every other API function needs the same context and client to do anything.
@@ -20,7 +25,7 @@ Scope the integration branch to exactly that core, not to everything planned for
2025

2126
## After the core lands
2227

23-
Once the core has merged as `v1.0.0`, ordinary [SemVer](../Versioning.md) applies: a new function built on the stable core is a **minor** bump, a fix is a **patch** bump, and only a change to the core's own contract (signature, exported class shape, behavior) is a **major** bump. No special versioning exception is needed once the core is in place — the bootstrap phase exists only to get that core to a first release quickly.
28+
Once the core has merged as `v1.0.0`, ordinary [SemVer](../../Versioning.md) applies: a new function built on the stable core is a **minor** bump, a fix is a **patch** bump, and only a change to the core's own contract (signature, exported class shape, behavior) is a **major** bump. No special versioning exception is needed once the core is in place — the bootstrap phase exists only to get that core to a first release quickly.
2429

2530
```mermaid
2631
gitGraph

0 commit comments

Comments
 (0)