Skip to content

Commit ea4a960

Browse files
docs: frame Module Bootstrap around the load-bearing core
$Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 1ec0314 commit ea4a960

1 file changed

Lines changed: 21 additions & 9 deletions

File tree

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,36 @@
11
# Module Bootstrap
22

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.
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 built in parallel — by different people or agents — as soon as the core is stable enough to build against, even before it merges.
413

514
## Pattern
615

716
1. Cut one long-lived branch from the default branch for the initial release, named for the outcome, e.g. `build-thing-module`.
817
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.
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`).
1019
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.
1120

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+
1225
```mermaid
1326
gitGraph
1427
commit id: "main"
1528
branch build-thing-module
1629
checkout build-thing-module
17-
commit id: "ConvertFrom-Thing"
18-
commit id: "ConvertTo-Thing"
19-
commit id: "Import-Thing / Export-Thing"
30+
commit id: "load-bearing core"
31+
commit id: "core, continued"
2032
checkout main
21-
merge build-thing-module id: "first release"
33+
merge build-thing-module id: "v1.0.0"
2234
```
2335

2436
## Example
@@ -27,12 +39,12 @@ A module bootstrapped this way:
2739

2840
| PR | Targets | Contents |
2941
| --- | --- | --- |
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 |
42+
| #1 | `main` | `build-thing-module` branch, the load-bearing core (e.g. conversion pivot, or context + client + first API function) |
43+
| #2 | `build-thing-module` | a follow-up function built on the core, added before the integration branch merged |
3244

3345
## When to use this
3446

35-
- The module has no usable release yet, and no single function is meaningful without the others.
47+
- The module has no usable release yet, and the load-bearing core hasn't landed.
3648
- 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.
3749

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