1# BOM Migration Guide
2 
3How to add or upgrade `azure-sdk-bom` and clean up redundant versions across all supported build configurations.
4 
5## Prerequisite — Python availability check
6 
7The Maven and plain-Gradle flows are automated by `scripts/upgrade_bom.py` (Python 3.8+). Before picking a guide, verify Python is available:
8 
9The following check works in both **bash** and **PowerShell 7+** (the `||` operator is supported in both):
10 
11```bash
12python3 --version || python --version
13```
14 
15For Windows PowerShell 5.1, use:
16 
17```powershell
18python3 --version; if ($LASTEXITCODE -ne 0) { python --version }
19```
20 
21- **Python available** → use the script as documented in [bom-maven.md](./bom-maven.md) / [bom-gradle.md](./bom-gradle.md).
22- **Python NOT available** → follow the **Manual Fallback** section in the same guide. Do not attempt to install Python; perform the edits by hand.
23 
24The TOML and programmatic-catalog guides ([bom-gradle-toml.md](./bom-gradle-toml.md), [bom-gradle-settings.md](./bom-gradle-settings.md)) are manual-only and unaffected by Python availability.
25 
26## Determine the latest BOM version
27 
28Resolve the target `azure-sdk-bom` version from the Azure SDK for Java source of truth before editing build files. This is mandatory: do not hardcode, guess, or reuse an illustrative version from another example. Versions below `1.3.0` are invalid for this migration flow.
29 
30The following invocation works identically in **bash** and **PowerShell** (no shell-specific syntax):
31 
32```bash
33# Path is relative to the skill directory (plugin/skills/azure-upgrade/)
34python3 ./references/languages/java/scripts/upgrade_bom.py --get-latest-version
35# or: python ./references/languages/java/scripts/upgrade_bom.py --get-latest-version
36```
37 
38If Python is not available, fetch `https://raw.githubusercontent.com/Azure/azure-sdk-for-java/main/sdk/boms/azure-sdk-bom/pom.xml` directly and use the `<version>` value declared in that BOM `pom.xml`.
39 
40Do not continue until you have resolved that latest stable version explicitly.
41 
42## Decision Tree
43 
44```
45Is the project Maven?
46├─ YES → Maven projects (bom-maven.md)
47└─ NO (Gradle)
48     ├─ Does gradle/libs.versions.toml exist with Azure entries?
49     │    └─ YES → TOML catalog steps (bom-gradle-toml.md)
50     ├─ Does settings.gradle define a programmatic versionCatalogs block with Azure entries?
51     │    └─ YES → Programmatic catalog steps (bom-gradle-settings.md)
52     └─ Neither (plain build.gradle dependencies)
53          └─ Plain Gradle projects (bom-gradle.md)
54```
55 
56> 💡 **Tip:** To check which artifacts are managed by the BOM, fetch
57> `https://repo1.maven.org/maven2/com/azure/azure-sdk-bom/{bom_version}/azure-sdk-bom-{bom_version}.pom`
58> and look for `<dependency>` entries.
59 
60## Build-System Guides
61 
62| Build system | Guide |
63|---|---|
64| Maven | [bom-maven.md](./bom-maven.md) |
65| Gradle (no version catalog) | [bom-gradle.md](./bom-gradle.md) |
66| Gradle + TOML version catalog | [bom-gradle-toml.md](./bom-gradle-toml.md) |
67| Gradle + programmatic catalog | [bom-gradle-settings.md](./bom-gradle-settings.md) |
68 
69## Validation
70 
71See the [Validation Checklist](./bom-validation.md) — covers all build systems including TOML and programmatic `settings.gradle` catalogs.
72