@@ -77,6 +77,7 @@ lines show SDK tooling dependencies between bands*
7777## Understanding Bootstrap vs Sequential Build
7878
7979### Bootstrap Process (Two-Stage)
80+
8081Bootstrapping is required when you don't have suitable source-built artifacts
8182to build a release. It's a two-stage process:
8283
@@ -105,6 +106,7 @@ flowchart TD
105106See [ Bootstrapping Guidelines] ( bootstrapping-guidelines.md ) for more info.
106107
107108### Sequential Build (Single-Stage)
109+
108110When you have appropriate source-built artifacts from previous builds, you can
109111build directly without bootstrapping. This is the typical workflow for ongoing
110112releases.
@@ -125,15 +127,19 @@ When building feature bands, you'll work with two types of source-built
125127artifacts:
126128
127129### Previously Source-Built (PSB) Artifacts
130+
128131These are artifacts from previous servicing releases or bootstrap builds:
132+
129133- Used as build dependencies but not redistributed in outputs
130134- Come from previous monthly .NET releases (e.g., 8.0.1 artifacts when
131135 building 8.0.2)
132136- Subject to [ poison detection] ( leak-detection.md ) to ensure no Microsoft
133137 binaries leak into outputs
134138
135139### Shared Component Artifacts
140+
136141These are shared runtime and foundational components from the 1xx band:
142+
137143- Come from the 1xx band build in the same release cycle
138144- Can be used as dependencies AND redistributed in outputs
139145- Include shared runtime and foundational components that all feature bands
@@ -142,7 +148,9 @@ These are shared runtime and foundational components from the 1xx band:
142148## Feature Band Characteristics
143149
144150### 1xx Band (GA/Non-breaking)
151+
145152The foundational feature band that ships with .NET GA releases:
153+
146154- ** Content** : Contains the complete VMR with .NET runtime, core libraries,
147155 and SDK tooling
148156- ** Purpose** : Provides the stable runtime foundation that all other bands
@@ -152,7 +160,9 @@ The foundational feature band that ships with .NET GA releases:
152160- ** Compatibility** : Non-breaking changes only during servicing
153161
154162### 2xx Band (Stable/Enhanced)
163+
155164Enhanced SDK tooling that ships with Visual Studio updates:
165+
156166- ** Content** : Contains only SDK tooling differences from 1xx band (subset
157167 VMR)
158168- ** Purpose** : Adds enhanced developer tooling and Visual Studio integration
@@ -163,7 +173,9 @@ Enhanced SDK tooling that ships with Visual Studio updates:
163173- ** Dependencies** : Always uses shared runtime components from 1xx band
164174
165175### 3xx Band (Preview/Insiders)
176+
166177Cutting-edge SDK features for early adopters and insiders:
178+
167179- ** Content** : Contains only SDK tooling differences from 2xx band (subset
168180 VMR)
169181- ** Purpose** : Delivers latest experimental features and early access
@@ -181,6 +193,7 @@ Cutting-edge SDK features for early adopters and insiders:
181193Each feature band has specific requirements for SDKs and artifacts:
182194
183195### 1xx Band Build Requirements
196+
184197- ** Bootstrap (any version)** : Two-stage process using Microsoft source-built
185198 1xx artifacts + Microsoft SDK + script
186199- ** Servicing (N.0.101+)** : Source-built SDK and artifacts from the previous
@@ -189,6 +202,7 @@ Each feature band has specific requirements for SDKs and artifacts:
189202Note: Only the 1xx SDK is guaranteed to build the shared runtime components
190203
191204### 2xx Band Build Requirements
205+
192206- ** Bootstrap (any version)** : Two-stage process using Microsoft source-built
193207 2xx artifacts + Microsoft 2xx SDK + prep script
194208- ** Initial Release (N.0.200)** : Latest source-built 1xx artifacts + Latest
@@ -197,6 +211,7 @@ Note: Only the 1xx SDK is guaranteed to build the shared runtime components
197211 2xx release + Latest released 1xx artifacts
198212
199213### 3xx Band Build Requirements
214+
200215- ** Bootstrap (any version)** : Two-stage process using Microsoft source-built
201216 2xx artifacts + Microsoft 2xx SDK + prep script
202217- ** Initial Release (N.0.300)** : Latest source-built 1xx artifacts + Latest
@@ -205,6 +220,7 @@ Note: Only the 1xx SDK is guaranteed to build the shared runtime components
205220 Latest released 1xx artifacts + Latest released 2xx artifacts
206221
207222### Feature Band Key Points
223+
208224- Release schedules across branches are not necessarily aligned.
209225- 1xx band produces the shared runtime that all bands use.
210226- Not all 3xx check-ins flow to 2xx (changes are cherry-picked as needed).
@@ -232,48 +248,51 @@ The following sections describe the workflows for different scenarios.
232248### Input Artifacts Summary
233249
234250** For 1xx band builds:**
251+
235252- ** Bootstrap** :
236- - PSB artifacts: Microsoft-built previous N.0.1xx release
237- - SDK: Microsoft-built previous N.0.1xx release
253+ - PSB artifacts: Microsoft-built previous N.0.1xx release
254+ - SDK: Microsoft-built previous N.0.1xx release
238255- ** Servicing** :
239- - PSB artifacts: Source-built previous N.0.1xx release
240- - SDK: Source-built previous N.0.1xx release
256+ - PSB artifacts: Source-built previous N.0.1xx release
257+ - SDK: Source-built previous N.0.1xx release
241258
242259** For 2xx band builds:**
260+
243261- ** Initial release (N.0.200)** :
244- - Shared component artifacts: Source-built current N.0.1xx release
245- - PSB artifacts: Source-built previous N.0.1xx release
246- - SDK: Source-built previous N.0.1xx release
262+ - Shared component artifacts: Source-built current N.0.1xx release
263+ - PSB artifacts: Source-built previous N.0.1xx release
264+ - SDK: Source-built previous N.0.1xx release
247265- ** Bootstrap initial release (N.0.200)** :
248- - Shared component artifacts: Source-built current N.0.1xx release
249- - PSB artifacts: Microsoft-built previous N.0.1xx release
250- - SDK: Microsoft-built previous N.0.1xx release
266+ - Shared component artifacts: Source-built current N.0.1xx release
267+ - PSB artifacts: Microsoft-built previous N.0.1xx release
268+ - SDK: Microsoft-built previous N.0.1xx release
251269- ** Bootstrap (N.0.201+)** :
252- - Shared component artifacts: Source-built current N.0.1xx release
253- - PSB artifacts: Microsoft-built previous N.0.2xx release
254- - SDK: Microsoft-built previous N.0.2xx release
270+ - Shared component artifacts: Source-built current N.0.1xx release
271+ - PSB artifacts: Microsoft-built previous N.0.2xx release
272+ - SDK: Microsoft-built previous N.0.2xx release
255273- ** Servicing (N.0.201+)** :
256- - Shared component artifacts: Source-built current N.0.1xx release
257- - PSB artifacts: Source-built previous N.0.2xx release
258- - SDK: Source-built previous N.0.2xx release
274+ - Shared component artifacts: Source-built current N.0.1xx release
275+ - PSB artifacts: Source-built previous N.0.2xx release
276+ - SDK: Source-built previous N.0.2xx release
259277
260278** For 3xx band builds:**
279+
261280- ** Initial release (N.0.300)** :
262- - Shared component artifacts: Source-built current N.0.1xx release
263- - PSB artifacts: Source-built previous N.0.2xx release
264- - SDK: Source-built previous N.0.2xx release
281+ - Shared component artifacts: Source-built current N.0.1xx release
282+ - PSB artifacts: Source-built previous N.0.2xx release
283+ - SDK: Source-built previous N.0.2xx release
265284- ** Bootstrap (N.0.300)** :
266- - Shared component artifacts: Source-built current N.0.1xx release
267- - PSB artifacts: Microsoft-built previous N.0.2xx release
268- - SDK: Microsoft-built previous N.0.2xx release
285+ - Shared component artifacts: Source-built current N.0.1xx release
286+ - PSB artifacts: Microsoft-built previous N.0.2xx release
287+ - SDK: Microsoft-built previous N.0.2xx release
269288- ** Bootstrap (N.0.301+)** :
270- - Shared component artifacts: Source-built current N.0.1xx release
271- - PSB artifacts: Microsoft-built previous N.0.2xx release
272- - SDK: Microsoft-built previous N.0.2xx release
289+ - Shared component artifacts: Source-built current N.0.1xx release
290+ - PSB artifacts: Microsoft-built previous N.0.2xx release
291+ - SDK: Microsoft-built previous N.0.2xx release
273292- ** Servicing (N.0.301+)** :
274- - Shared component artifacts: Source-built current N.0.1xx release
275- - PSB artifacts: Source-built previous N.0.2xx release
276- - SDK: Source-built previous N.0.2xx release
293+ - Shared component artifacts: Source-built current N.0.1xx release
294+ - PSB artifacts: Source-built previous N.0.2xx release
295+ - SDK: Source-built previous N.0.2xx release
277296
278297### Scenario 1: 1xx Band Bootstrap
279298
@@ -351,7 +370,8 @@ flowchart LR
351370For ongoing 1xx servicing builds.
352371
353372Required inputs:
354- * source-built SDK and artifacts from the previous 1xx release
373+
374+ - source-built SDK and artifacts from the previous 1xx release
355375
356376``` bash
357377git clone -b < 1xx-release-branch> https://github.com/dotnet/dotnet.git
@@ -394,8 +414,9 @@ flowchart LR
394414Initial release of the 2xx band.
395415
396416Required inputs:
397- * source-built artifacts of the current 1xx release
398- * source-built SDK artifacts from the previous 1xx release
417+
418+ - source-built artifacts of the current 1xx release
419+ - source-built SDK artifacts from the previous 1xx release
399420
400421``` bash
401422git clone -b < 2xx-release-branch> https://github.com/dotnet/dotnet.git
@@ -446,7 +467,8 @@ flowchart LR
446467For 2xx releases that require bootstrap (two-stage process).
447468
448469Required inputs:
449- * source-built artifacts of the current 1xx release
470+
471+ - source-built artifacts of the current 1xx release
450472
451473``` bash
452474git clone -b < 2xx-release-branch> https://github.com/dotnet/dotnet.git
@@ -527,8 +549,9 @@ flowchart LR
527549For ongoing 2xx servicing builds.
528550
529551Required inputs:
530- * source-built artifacts of the current 1xx release
531- * source-built SDK and artifacts from the previous 2xx release
552+
553+ - source-built artifacts of the current 1xx release
554+ - source-built SDK and artifacts from the previous 2xx release
532555
533556``` bash
534557git clone -b < 2xx-release-branch> https://github.com/dotnet/dotnet.git
@@ -579,8 +602,9 @@ flowchart LR
579602For the initial 3xx release.
580603
581604Required inputs:
582- * source-built artifacts from the current 1xx release
583- * source-built SDK and artifacts from the previous 2xx release
605+
606+ - source-built artifacts from the current 1xx release
607+ - source-built SDK and artifacts from the previous 2xx release
584608
585609``` bash
586610git clone -b < 3xx-release-branch> https://github.com/dotnet/dotnet.git
@@ -631,7 +655,8 @@ flowchart LR
631655For 3xx releases that require bootstrap (two-stage process).
632656
633657Required inputs:
634- * source-built artifacts from the current 1xx release
658+
659+ - source-built artifacts from the current 1xx release
635660
636661``` bash
637662git clone -b < 3xx-release-branch> https://github.com/dotnet/dotnet.git
@@ -712,8 +737,9 @@ flowchart LR
712737For ongoing 3xx servicing builds:
713738
714739Required inputs:
715- * source-built SDK and artifacts from the previous 2xx release
716- * source-built artifacts from the current 1xx release
740+
741+ - source-built SDK and artifacts from the previous 2xx release
742+ - source-built artifacts from the current 1xx release
717743
718744``` bash
719745# Ensure you have latest source-built 1xx, 2xx artifacts and 2xx SDK from previous builds
@@ -764,6 +790,7 @@ flowchart LR
764790
765791** Error** : `Shared components cannot be provided as input to a build which
766792produces shared components`
793+
767794- ** Explanation** : You're building the 1xx band (` main ` or ` N.0.1xx ` branch)
768795 and providing shared component artifacts as input. The 1xx band produces
769796 shared components, so it doesn't consume them as inputs.
@@ -772,6 +799,7 @@ produces shared components`
772799
773800** Error** : `Shared components must be provided as input to a build which does
774801not produce shared components`
802+
775803- ** Explanation** : You're building a 2xx or 3xx band and not providing shared
776804 component artifacts as input. These bands require shared components from the
777805 1xx band because they provide the necessary runtime and foundational
0 commit comments