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.10+). The script resolves the latest BOM internally; do not pass or pin a literal BOM version. 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). If `upgrade_bom.py` fails for any reason, do not stop the migration; manually resolve the BOM version and follow the same guide's **Manual Fallback** section.
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, pin, or reuse an illustrative version from another example. Existing versions are accepted only when they exactly match the resolved latest stable version.
29Always perform this resolution at the time the migration plan is generated. Never derive `TARGET_AZURE_SDK_BOM_VERSION` from the application being migrated, from a previously generated plan, from package-specific examples, or from model memory. If a resolved version differs from an existing `azure-sdk-bom` in the project, the existing BOM is stale and must be upgraded.
30 
31The following invocation works identically in **bash** and **PowerShell** (no shell-specific syntax):
32 
33```bash
34# Path is relative to the skill directory (plugin/skills/azure-upgrade/)
35python3 ./references/languages/java/scripts/upgrade_bom.py --get-latest-version
36# or: python ./references/languages/java/scripts/upgrade_bom.py --get-latest-version
37```
38 
39If Python is not available or the `--get-latest-version` command fails, 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`.
40 
41Do not continue until you have resolved that latest stable version explicitly. Add only that value to the plan's `Guidelines` section as `TARGET_AZURE_SDK_BOM_VERSION = <resolved-version>`.
42 
43## Decision Tree
44 
45```
46Is the project Maven?
47├─ YES → Maven projects (bom-maven.md)
48└─ NO (Gradle)
49     ├─ Does gradle/libs.versions.toml exist with Azure entries?
50     │    └─ YES → TOML catalog steps (bom-gradle-toml.md)
51     ├─ Does settings.gradle define a programmatic versionCatalogs block with Azure entries?
52     │    └─ YES → Programmatic catalog steps (bom-gradle-settings.md)
53     └─ Neither (plain build.gradle dependencies)
54          └─ Plain Gradle projects (bom-gradle.md)
55```
56 
57> 💡 **Tip:** To check which artifacts are managed by the BOM, fetch
58> `https://repo1.maven.org/maven2/com/azure/azure-sdk-bom/{bom_version}/azure-sdk-bom-{bom_version}.pom`
59> and look for `<dependency>` entries.
60 
61## Build-System Guides
62 
63| Build system                  | Guide                                              |
64| ----------------------------- | -------------------------------------------------- |
65| Maven                         | [bom-maven.md](./bom-maven.md)                     |
66| Gradle (no version catalog)   | [bom-gradle.md](./bom-gradle.md)                   |
67| Gradle + TOML version catalog | [bom-gradle-toml.md](./bom-gradle-toml.md)         |
68| Gradle + programmatic catalog | [bom-gradle-settings.md](./bom-gradle-settings.md) |
69 
70## Validation
71 
72See the [Validation Checklist](./bom-validation.md) — covers all build systems including TOML and programmatic `settings.gradle` catalogs.
73