|
| 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