1# BOM Migration — Gradle Projects (No Version Catalogs)
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 Gradle and performs:
8 
91. **Set/upgrade the BOM** — adds `enforcedPlatform("com.azure:azure-sdk-bom:...")` if missing, or upgrades the version.
102. **Remove redundant explicit versions** — strips inline version strings from Azure dependencies 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- `--gradle <cmd>` — override the Gradle command (default: auto-detects `gradlew` or `gradle`).
21 
22Under the hood (OpenRewrite recipes):
23- **Add BOM**: `AddPlatformDependency` ([docs](https://docs.openrewrite.org/recipes/gradle/addplatformdependency))
24- **Upgrade BOM**: `UpgradeDependencyVersion` ([docs](https://docs.openrewrite.org/recipes/gradle/upgradedependencyversion))
25- **Remove redundant versions**: `RemoveRedundantDependencyVersions` ([docs](https://docs.openrewrite.org/recipes/gradle/removeredundantdependencyversions))
26 
27> ⚠️ **Warning:** The script does **not** support Gradle version catalogs — neither TOML files nor programmatic `settings.gradle` catalogs. If the project uses either, follow [TOML catalog steps](./bom-gradle-toml.md) or [programmatic catalog steps](./bom-gradle-settings.md) instead.
28 
29## Expected build.gradle after migration
30 
31Groovy DSL (`build.gradle`):
32```groovy
33dependencies {
34    implementation enforcedPlatform("com.azure:azure-sdk-bom:{bom_version}")
35 
36    implementation "com.azure:azure-identity"
37    implementation "com.azure.resourcemanager:azure-resourcemanager"
38}
39```
40 
41Kotlin DSL (`build.gradle.kts`):
42```kotlin
43dependencies {
44    implementation(enforcedPlatform("com.azure:azure-sdk-bom:{bom_version}"))
45 
46    implementation("com.azure:azure-identity")
47    implementation("com.azure.resourcemanager:azure-resourcemanager")
48}
49```
50 
51## Manual Fallback (no Python)
52 
53When Python is unavailable, edit `build.gradle` (or `build.gradle.kts`) directly. Apply the same two steps as the script.
54 
55### Step 1 — Add or upgrade the BOM platform
56 
57Inside the `dependencies { }` block, add or update the `enforcedPlatform` line for `azure-sdk-bom`:
58 
59Groovy DSL:
60```groovy
61dependencies {
62    implementation enforcedPlatform("com.azure:azure-sdk-bom:{bom_version}")
63    // ...other dependencies...
64}
65```
66 
67Kotlin DSL:
68```kotlin
69dependencies {
70    implementation(enforcedPlatform("com.azure:azure-sdk-bom:{bom_version}"))
71    // ...other dependencies...
72}
73```
74 
75- **If the line exists**: update only the version to `{bom_version}`.
76- **If the line is missing**: insert it at the top of the `dependencies` block.
77- Use the same configuration (`implementation`, `api`, `compileOnly`, etc.) the project already uses for Azure deps. Repeat the platform line per configuration if needed.
78- **Multi-project build**: add the platform line in every subproject that declares Azure dependencies, or apply it once via a shared `subprojects { }` / convention plugin.
79 
80### Step 2 — Remove redundant explicit versions
81 
82For every Azure dependency whose group starts with `com.azure` and is managed by the BOM (verify against `https://repo1.maven.org/maven2/com/azure/azure-sdk-bom/{bom_version}/azure-sdk-bom-{bom_version}.pom`), strip the version coordinate.
83 
84Groovy DSL — string notation:
85```groovy
86// Before
87implementation "com.azure:azure-identity:1.13.0"
88// After
89implementation "com.azure:azure-identity"
90```
91 
92Groovy DSL — map notation:
93```groovy
94// Before
95implementation group: "com.azure", name: "azure-identity", version: "1.13.0"
96// After
97implementation group: "com.azure", name: "azure-identity"
98```
99 
100Kotlin DSL:
101```kotlin
102// Before
103implementation("com.azure:azure-identity:1.13.0")
104// After
105implementation("com.azure:azure-identity")
106```
107 
108Do **not** strip versions from artifacts that are not managed by the BOM.
109 
110### Step 3 — Verify
111 
112Run the Gradle wrapper to inspect the resolved classpath. Use the form appropriate for your shell:
113 
114```bash
115# bash / macOS / Linux
116./gradlew dependencies --configuration runtimeClasspath
117```
118 
119```powershell
120# PowerShell on Windows
121.\gradlew.bat dependencies --configuration runtimeClasspath
122```
123 
124Then confirm:
125- The platform `com.azure:azure-sdk-bom:{bom_version}` appears.
126- All BOM-managed Azure artifacts resolve to versions sourced from the BOM.
127 
128Then continue with the validation checklist in [bom-validation.md](./bom-validation.md).
129