Skip to content

Commit 0b4b9e8

Browse files
πŸ“– [Docs]: Module bootstrap branching pattern documented (#89)
Modules that need several interdependent functions before a first release is usable now have a documented pattern to follow, instead of improvising it per repo. ## New: Module Bootstrap page `src/docs/Modules/Process-PSModule/module-bootstrap.md` documents the pattern: identify the module's **load-bearing core** first (the conversion pivot for data modules, or the Context-backed credential store + client + first API function for integration modules, per the existing [Module types](../Module-Types.md) archetypes), scope one long-lived integration branch to exactly that core, and open small focused PRs targeting that branch in parallel until it's coherent. Merging the integration branch into `main` becomes the module's `v1.0.0`. After that, ordinary SemVer applies β€” new functions on the stable core are minor/patch bumps unless they break the core's own contract. Follow-up feature PRs can keep targeting the integration branch before it merges. The page is linked from the `Process-PSModule` nav/index and cross-referenced from `template-quickstart.md` for modules that need this before the ordinary single-command quickstart applies. ## Technical Details - Added `src/docs/Modules/Process-PSModule/module-bootstrap.md`, cross-linking `Module-Types.md` and `Versioning.md`. - Registered it in `src/zensical.toml` nav and `Process-PSModule/index.md`. - Added a one-line cross-reference from `template-quickstart.md`. - No MSXOrg/docs changes: the existing "Stacked pull requests" / "Merge models" sections in `Branching-and-Merging.md` already cover the general framework; this page is a PSModule-specific application of it and links out for contrast rather than duplicating that content. Docs-only change, no issue required.
1 parent 6bf69bd commit 0b4b9e8

4 files changed

Lines changed: 64 additions & 0 deletions

File tree

β€Žsrc/docs/Modules/Process-PSModule/index.mdβ€Ž

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,6 @@ This section documents how module repositories are formed and how they move from
1010
- [Module Anatomy](module-anatomy.md)
1111
- [Build, Test, Pack, Publish](build-test-pack-publish.md)
1212
- [Template Quickstart](template-quickstart.md)
13+
- [Module Bootstrap](module-bootstrap.md)
1314

1415
For broader framework context, see [MSX Frameworks / Process-PSModule](https://msxorg.github.io/docs/Frameworks/Process-PSModule/).
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Module Bootstrap
2+
3+
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.
4+
5+
## Identify the load-bearing core first
6+
7+
What counts as "load-bearing" follows the module's archetype from [Module types](../Module-Types.md):
8+
9+
- **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.
10+
- **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.
11+
12+
Scope the integration branch to exactly that core, not to everything planned for v1. Keeping it to the minimum that "everyone needs" gets a usable release out faster, and lets independent follow-up functions be developed in parallel β€” by different people or agents β€” as soon as the core is stable enough to build against, even before it merges.
13+
14+
## Pattern
15+
16+
1. Cut one long-lived branch from the default branch for the initial release, named for the outcome, e.g. `build-thing-module`.
17+
2. Open one pull request per function (or small group of related functions) targeting that branch instead of `main`. These PRs can land in parallel β€” there is no strict order between them, unlike a [stacked pull request](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests).
18+
3. Once the load-bearing core is coherent and complete, open the pull request that merges the integration branch into `main`. This becomes the module's first real release (`v1.0.0`).
19+
4. Smaller follow-up features (one more function, a formatter, an alias) can keep targeting the integration branch before it lands, the same way they targeted it during bootstrap.
20+
21+
## After the core lands
22+
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.
24+
25+
```mermaid
26+
gitGraph
27+
commit id: "main"
28+
branch build-thing-module
29+
checkout build-thing-module
30+
commit id: "load-bearing core"
31+
branch function-a
32+
branch function-b
33+
checkout function-a
34+
commit id: "PR: function A"
35+
checkout function-b
36+
commit id: "PR: function B"
37+
checkout build-thing-module
38+
merge function-a
39+
merge function-b
40+
checkout main
41+
merge build-thing-module id: "v1.0.0"
42+
```
43+
44+
`function-a` and `function-b` are independent β€” both cut from `build-thing-module` and merged back in any order, unlike a stacked pull request where each layer depends on the one before it.
45+
46+
## Example
47+
48+
A module bootstrapped this way:
49+
50+
| PR | Targets | Contents |
51+
| --- | --- | --- |
52+
| #1 | `main` | `build-thing-module` branch, the load-bearing core (e.g. conversion pivot, or context + client + first API function) |
53+
| #2 | `build-thing-module` | a follow-up function built on the core, added before the integration branch merged |
54+
55+
## When to use this
56+
57+
- The module has no usable release yet, and the load-bearing core hasn't landed.
58+
- Use this only for the initial bootstrap. Once `main` has a first release, ongoing feature work targets `main` directly with ordinary topic branches, or a [stacked pull request](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests) when changes genuinely depend on each other.
59+
60+
For the general branching and merge model, see [MSX Branching and Merging](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/).

β€Žsrc/docs/Modules/Process-PSModule/template-quickstart.mdβ€Ž

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Start new modules from the PSModule template repository:
1212
4. Validate `.github/PSModule.yml` defaults for your module.
1313
5. Open a draft pull request and run the full pipeline.
1414

15+
If the module needs several interdependent commands before it is usable at all, see [Module Bootstrap](module-bootstrap.md) instead of shipping them as one command per step.
16+
1517
## Expected outcomes
1618

1719
- repository follows Process-PSModule structure

β€Žsrc/zensical.tomlβ€Ž

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ nav = [
3333
{"Module Anatomy" = "Modules/Process-PSModule/module-anatomy.md"},
3434
{"Build, Test, Pack, Publish" = "Modules/Process-PSModule/build-test-pack-publish.md"},
3535
{"Template Quickstart" = "Modules/Process-PSModule/template-quickstart.md"},
36+
{"Module Bootstrap" = "Modules/Process-PSModule/module-bootstrap.md"},
3637
]},
3738
]},
3839
{"Dictionary" = [

0 commit comments

Comments
Β (0)