1# BOM Migration — Maven Projects
2 
3> **Python availability**: The script below requires Python 3.8+. If `python3 --version` (or `python --version`) fails, skip the script section and follow [Manual Fallback (no Python)](#manual-fallback-no-python) 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 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> <bom_version>
17```
18 
19Options:
20- `--mvn <cmd>` — override the Maven command (default: auto-detects `mvnw` or `mvn`).
21 
22Under the hood (OpenRewrite recipes):
23- **Add BOM**: `AddManagedDependency` ([docs](https://docs.openrewrite.org/recipes/maven/addmanageddependency))
24- **Upgrade BOM**: `UpgradeDependencyVersion` ([docs](https://docs.openrewrite.org/recipes/maven/upgradedependencyversion))
25- **Remove redundant versions**: `RemoveRedundantDependencyVersions` ([docs](https://docs.openrewrite.org/recipes/maven/removeredundantdependencyversions))
26 
27## Expected pom.xml after migration
28 
29```xml
30<dependencyManagement>
31    <dependencies>
32        <dependency>
33            <groupId>com.azure</groupId>
34            <artifactId>azure-sdk-bom</artifactId>
35            <version>{bom_version}</version>
36            <type>pom</type>
37            <scope>import</scope>
38        </dependency>
39    </dependencies>
40</dependencyManagement>
41 
42<dependencies>
43    <dependency>
44        <groupId>com.azure</groupId>
45        <artifactId>azure-identity</artifactId>
46    </dependency>
47    <dependency>
48        <groupId>com.azure.resourcemanager</groupId>
49        <artifactId>azure-resourcemanager</artifactId>
50    </dependency>
51</dependencies>
52```
53 
54## Manual Fallback (no Python)
55 
56When Python is unavailable, edit `pom.xml` directly. Apply the same two steps as the script:
57 
58### Step 1 — Add or upgrade `azure-sdk-bom`
59 
60Locate the `<dependencyManagement><dependencies>` block (create it inside `<project>` if absent). Add or update the BOM entry:
61 
62```xml
63<dependencyManagement>
64    <dependencies>
65        <dependency>
66            <groupId>com.azure</groupId>
67            <artifactId>azure-sdk-bom</artifactId>
68            <version>{bom_version}</version>
69            <type>pom</type>
70            <scope>import</scope>
71        </dependency>
72        <!-- keep any other managed dependencies here -->
73    </dependencies>
74</dependencyManagement>
75```
76 
77- **If the entry exists**: update only the `<version>` value to `{bom_version}`.
78- **If the entry is missing**: insert the full `<dependency>` block above. Preserve any other existing managed dependencies.
79- **Multi-module project**: add the BOM in the parent (aggregator) `pom.xml` only. Child modules inherit it.
80 
81### Step 2 — Remove redundant explicit versions
82 
83For 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:
84 
85- Remove the `<version>` element entirely.
86- Leave `<groupId>`, `<artifactId>`, `<scope>`, `<classifier>`, `<exclusions>`, etc. unchanged.
87 
88Before:
89```xml
90<dependency>
91    <groupId>com.azure</groupId>
92    <artifactId>azure-identity</artifactId>
93    <version>1.13.0</version>
94</dependency>
95```
96 
97After:
98```xml
99<dependency>
100    <groupId>com.azure</groupId>
101    <artifactId>azure-identity</artifactId>
102</dependency>
103```
104 
105Do **not** strip versions from artifacts not managed by the BOM (verify each one against the BOM POM).
106 
107### Step 3 — Verify
108 
109Run `mvn -q -DskipTests dependency:tree` (the same command works in both **bash** and **PowerShell**) and confirm:
110- `com.azure:azure-sdk-bom:pom:{bom_version}:import` appears in the managed dependencies.
111- All BOM-managed Azure artifacts resolve to versions from `{bom_version}`.
112 
113Then continue with the validation checklist in [bom-validation.md](./bom-validation.md).
114