|
1 | 1 | # Module Bootstrap |
2 | 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. |
| 3 | +A brand-new module often needs several interdependent functions before it is usable at all — for example a module might need `ConvertFrom-Thing`, `ConvertTo-Thing`, `Import-Thing`, and `Export-Thing` 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 | 4 |
|
5 | 5 | ## Pattern |
6 | 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`. |
| 7 | +1. Cut one long-lived branch from the default branch for the initial release, named for the outcome, e.g. `build-thing-module`. |
8 | 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 | 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 | 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 | 11 |
|
12 | 12 | ```mermaid |
13 | 13 | gitGraph |
14 | 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" |
| 15 | + branch build-thing-module |
| 16 | + checkout build-thing-module |
| 17 | + commit id: "ConvertFrom-Thing" |
| 18 | + commit id: "ConvertTo-Thing" |
| 19 | + commit id: "Import-Thing / Export-Thing" |
20 | 20 | checkout main |
21 | | - merge build-toml-module id: "first release" |
| 21 | + merge build-thing-module id: "first release" |
22 | 22 | ``` |
23 | 23 |
|
24 | 24 | ## Example |
25 | 25 |
|
26 | | -[PSModule/Toml](https://github.com/PSModule/Toml) bootstrapped this way: |
| 26 | +A module bootstrapped this way: |
27 | 27 |
|
28 | 28 | | PR | Targets | Contents | |
29 | 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 | |
| 30 | +| #1 | `main` | `build-thing-module` branch, the foundational `ConvertFrom-Thing`, `ConvertTo-Thing`, `Import-Thing`, `Export-Thing` release | |
| 31 | +| #2 | `build-thing-module` | `Format-Thing`, a follow-up feature added before the integration branch merged | |
32 | 32 |
|
33 | 33 | ## When to use this |
34 | 34 |
|
|
0 commit comments