1# BOM Migration — Maven Projects
2 
3> **Python/script availability**: The script below requires Python 3.10+. If `python3 --version` (or `python --version`) fails, or if `upgrade_bom.py` exits unsuccessfully, skip the script path and follow [Manual Fallback](#manual-fallback-no-python-or-script-failure) instead.
4 
5## Automated (Python available)
6 
7Run the `upgrade_bom.py` script located at `references/languages/java/scripts/upgrade_bom.py` (relative to this skill). It resolves the latest stable BOM version, auto-detects Maven, and performs two steps:
8 
91. **Set/upgrade the BOM** — adds `azure-sdk-bom` if missing, or upgrades the version if already present.
102. **Remove redundant explicit versions** — strips explicit `<version>` tags from individual Azure dependencies that are now managed by the BOM.
11 
12The following invocation works identically in **bash** and **PowerShell**:
13 
14```bash
15# Path is relative to the skill directory (plugin/skills/azure-upgrade/)
16python3 ./references/languages/java/scripts/upgrade_bom.py <project_dir>
17```
18 
19Options:
20- `--mvn <cmd>` — override the Maven command (default: auto-detects `mvnw` or `mvn`).
21 
22If the script fails after starting, treat that as an automation failure only: keep the resolved `TARGET_AZURE_SDK_BOM_VERSION`, manually apply the fallback steps below, and continue validation.
23 
24Under the hood (OpenRewrite recipes):
25- **Add BOM**: `AddManagedDependency` ([docs](https://docs.openrewrite.org/recipes/maven/addmanageddependency))
26- **Upgrade BOM**: `UpgradeDependencyVersion` ([docs](https://docs.openrewrite.org/recipes/maven/upgradedependencyversion))
27- **Remove redundant versions**: `RemoveRedundantDependencyVersions` ([docs](https://docs.openrewrite.org/recipes/maven/removeredundantdependencyversions))
28 
29## Expected pom.xml after migration
30 
31```xml
32<dependencyManagement>
33    <dependencies>
34        <dependency>
35            <groupId>com.azure</groupId>
36            <artifactId>azure-sdk-bom</artifactId>
37            <version>{bom_version}</version>
38            <type>pom</type>
39            <scope>import</scope>
40        </dependency>
41    </dependencies>
42</dependencyManagement>
43 
44<dependencies>
45    <dependency>
46        <groupId>com.azure</groupId>
47        <artifactId>azure-identity</artifactId>
48    </dependency>
49    <dependency>
50        <groupId>com.azure.resourcemanager</groupId>
51        <artifactId>azure-resourcemanager</artifactId>
52    </dependency>
53</dependencies>
54```
55 
56## Manual Fallback (no Python or script failure)
57 
58When Python is unavailable or `upgrade_bom.py` fails, edit `pom.xml` directly. Apply the same two steps as the script:
59 
60### Step 1 — Add or upgrade `azure-sdk-bom`
61 
62Locate the `<dependencyManagement><dependencies>` block (create it inside `<project>` if absent). Add or update the BOM entry:
63 
64```xml
65<dependencyManagement>
66    <dependencies>
67        <dependency>
68            <groupId>com.azure</groupId>
69            <artifactId>azure-sdk-bom</artifactId>
70            <version>{bom_version}</version>
71            <type>pom</type>
72            <scope>import</scope>
73        </dependency>
74        <!-- keep any other managed dependencies here -->
75    </dependencies>
76</dependencyManagement>
77```
78 
79- **If the entry exists**: update only the `<version>` value to `{bom_version}`.
80- **If the entry is missing**: insert the full `<dependency>` block above. Preserve any other existing managed dependencies.
81- **Multi-module project**: add the BOM in the parent (aggregator) `pom.xml` only. Child modules inherit it.
82 
83### Step 2 — Remove redundant explicit versions
84 
85For every `<dependency>` whose `<groupId>` starts with `com.azure` (e.g. `com.azure`, `com.azure.resourcemanager`, `com.azure.spring`), check whether the BOM manages it (see the BOM POM at `https://repo1.maven.org/maven2/com/azure/azure-sdk-bom/{bom_version}/azure-sdk-bom-{bom_version}.pom`). If managed:
86 
87- Remove the `<version>` element entirely.
88- Leave `<groupId>`, `<artifactId>`, `<scope>`, `<classifier>`, `<exclusions>`, etc. unchanged.
89 
90Before:
91```xml
92<dependency>
93    <groupId>com.azure</groupId>
94    <artifactId>azure-identity</artifactId>
95    <version>1.13.0</version>
96</dependency>
97```
98 
99After:
100```xml
101<dependency>
102    <groupId>com.azure</groupId>
103    <artifactId>azure-identity</artifactId>
104</dependency>
105```
106 
107Do **not** strip versions from artifacts not managed by the BOM (verify each one against the BOM POM).
108 
109### Step 3 — Verify
110 
111Run `mvn -q -DskipTests dependency:tree` (the same command works in both **bash** and **PowerShell**) and confirm:
112- `com.azure:azure-sdk-bom:pom:{bom_version}:import` appears in the managed dependencies and `{bom_version}` equals `TARGET_AZURE_SDK_BOM_VERSION`.
113- All BOM-managed Azure artifacts resolve to versions from `{bom_version}`.
114 
115Then continue with the validation checklist in [bom-validation.md](./bom-validation.md).
116