Skip to content

Commit 3793e2e

Browse files
docs: add Module Bootstrap pattern page
$Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 6bf69bd commit 3793e2e

1 file changed

Lines changed: 38 additions & 0 deletions

File tree

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Module Bootstrap
2+
3+
A brand-new module often needs several interdependent functions before it is usable at all — for example a TOML module needs `ConvertFrom-Toml`, `ConvertTo-Toml`, `Import-Toml`, and `Export-Toml` together before any of them is meaningful on its own. A single feature PR cannot carry that much scope and still be small and focused, so bootstrap uses one integration branch instead.
4+
5+
## Pattern
6+
7+
1. Cut one long-lived branch from the default branch for the initial release, named for the outcome, e.g. `build-toml-module`.
8+
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).
9+
3. Once the foundational set of functions is coherent and complete, open the pull request that merges the integration branch into `main`. This becomes the module's first real release.
10+
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.
11+
12+
```mermaid
13+
gitGraph
14+
commit id: "main"
15+
branch build-toml-module
16+
checkout build-toml-module
17+
commit id: "ConvertFrom-Toml"
18+
commit id: "ConvertTo-Toml"
19+
commit id: "Import-Toml / Export-Toml"
20+
checkout main
21+
merge build-toml-module id: "first release"
22+
```
23+
24+
## Example
25+
26+
[PSModule/Toml](https://github.com/PSModule/Toml) bootstrapped this way:
27+
28+
| PR | Targets | Contents |
29+
| --- | --- | --- |
30+
| [#15](https://github.com/PSModule/Toml/pull/15) | `main` | `build-toml-module` branch, the foundational `ConvertFrom-Toml`, `ConvertTo-Toml`, `Import-Toml`, `Export-Toml` release |
31+
| [#20](https://github.com/PSModule/Toml/pull/20) | `build-toml-module` | `Format-Toml`, a follow-up feature added before the integration branch merged |
32+
33+
## When to use this
34+
35+
- The module has no usable release yet, and no single function is meaningful without the others.
36+
- 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.
37+
38+
For the general branching and merge model, see [MSX Branching and Merging](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/).

0 commit comments

Comments
 (0)