1<!--
2  This is the upgrade plan template for Azure SDK migration.
3  RUN_ID should be replaced with the actual run identifier.
4 
5  ## PLANNING RULES
6 
7  !!! DON'T REMOVE THIS COMMENT BLOCK BEFORE FINAL PLAN IS GENERATED AS IT CONTAINS IMPORTANT INSTRUCTIONS.
8 
9  ### Strategy
10  - **Incremental upgrades**: Stepwise dependency upgrades to avoid large jumps breaking builds
11  - **Minimal changes**: Only upgrade dependencies essential for compatibility
12  - **Risk-first**: Handle EOL/challenging deps early in isolated steps
13  - **Necessary/Meaningful steps only**: Each step MUST change code/config. NO steps for pure analysis/validation. Merge small related changes.
14 
15  ### Mandatory Steps
16  - **Step 1 (MANDATORY)**: Setup Baseline - Run compile/test with current JDK, document results.
17  - **Steps 2-N**: Upgrade steps - dependency order, high-risk early, isolated breaking changes
18  - **Final step (MANDATORY)**: Final Validation - verify all goals met, all TODOs resolved, 100% tests pass
19 
20  ### Verification Expectations
21  - **Steps 1-N (Setup/Upgrade)**: Focus on COMPILATION SUCCESS. Tests may fail during intermediate steps.
22  - **Final Validation**: COMPILATION SUCCESS + 100% TEST PASS
23 
24  ### Efficiency (IMPORTANT)
25  - **Targeted reads**: Use `grep` over full file reads; read specific sections, not entire files. Template files are large - only read the sections you need.
26  - **Quiet commands**: Use `-q`, `--quiet` for build/test commands when appropriate
27  - **Progressive writes**: Update plan.md incrementally, not at end
28-->
29 
30# Upgrade Plan: <PROJECT_NAME> (<RUN_ID>)
31 
32- **Generated**: <datetime> <!-- replace with actual date and time when generating -->
33- **HEAD Branch**: <current_branch> <!-- replace with actual head branch when generating -->
34- **HEAD Commit ID**: <current_commit_id> <!-- replace with actual head commit id when generating -->
35 
36## Available Tools
37 
38<!--
39  List ONLY the JDKs and build tools that are required/used during the upgrade (not all discovered ones).
40  Use the environment detection results from Precheck to check availability.
41  Mark build tools that need upgrading for JDK compatibility as "**<TO_BE_UPGRADED>**".
42  If a wrapper (mvnw/gradlew) is present, also check the wrapper-defined version in
43  `.mvn/wrapper/maven-wrapper.properties` or `gradle/wrapper/gradle-wrapper.properties`.
44 
45  NOTE: This section is finalized during Upgrade Path Design (after step sequence is known), not during Environment Analysis.
46 
47  SAMPLE:
48  **JDKs**
49  - JDK 1.8.0: /path/to/jdk-8 (current project JDK, used by step 1)
50 
51  **Build Tools**
52  - Maven 3.9.6: /path/to/maven
53  - Maven Wrapper: 3.8.1 → **<TO_BE_UPGRADED>** to 3.9.6+ (current version incompatible with project requirements)
54-->
55 
56## Guidelines
57 
58<!--
59  User-specified guidelines or constraints in bullet points for this upgrade.
60  Extract these from the user's prompt if provided, or leave empty if none specified.
61  These guidelines take precedence over default upgrade strategies.
62-->
63 
64> Note: You can add any specific guidelines or constraints for the upgrade process here if needed, bullet points are preferred. <!-- this note is for users, NEVER remove it -->
65 
66## Upgrade Goals
67 
68<!--
69  The primary goal is to replace all legacy Azure SDK dependencies (com.microsoft.azure.*) with their
70  modern equivalents (com.azure.*). List any additional user-specified goals below.
71 
72  SAMPLE:
73  - Replace all `com.microsoft.azure.*` dependencies with `com.azure.*` equivalents
74  - Migrate source code to use modern Azure SDK APIs (builder pattern, Azure Identity)
75-->
76 
77### Technology Stack
78 
79<!--
80  Table of core dependencies and their compatibility with upgrade goals.
81  IMPORTANT: Analyze ALL modules in multi-module projects, not just the root module.
82  Only include: direct dependencies + those critical for upgrade compatibility.
83 
84  Columns:
85  - Technology/Dependency: Name of the dependency
86  - Current: Version currently in use
87  - Modern Equivalent: The com.azure.* replacement (or N/A if not an Azure SDK dep)
88  - Migration Notes: Notes on migration approach
89 
90  IMPORTANT: Include build tools (Maven/Gradle), wrappers, and key build plugins in this table.
91 
92  SAMPLE:
93  | Technology/Dependency                    | Current | Modern Equivalent                          | Migration Notes                              |
94  | ---------------------------------------- | ------- | ------------------------------------------ | -------------------------------------------- |
95  | com.microsoft.azure:azure-mgmt-resources | 1.41.4  | com.azure.resourcemanager:azure-resourcemanager | Use azure-sdk-bom for version management |
96  | com.microsoft.azure:azure-mgmt-storage   | 1.41.4  | com.azure.resourcemanager:azure-resourcemanager | Included in azure-resourcemanager        |
97  | com.microsoft.azure:azure-client-authentication | 1.7.14 | com.azure:azure-identity             | Use ClientSecretCredential or DefaultAzureCredential |
98  | Maven (wrapper)                          | 3.6.3   | -                                          | Check compatibility with project JDK         |
99-->
100 
101| Technology/Dependency | Current | Modern Equivalent | Migration Notes |
102| --------------------- | ------- | ----------------- | --------------- |
103 
104### Derived Upgrades
105 
106<!--
107  Required upgrades inferred from the Azure SDK migration.
108  Each derived upgrade must have a justification explaining WHY it's required.
109  Common derivations:
110  - Legacy auth (azure-client-authentication) → azure-identity
111  - Legacy management (azure-mgmt-*) → azure-resourcemanager or specific azure-resourcemanager-* modules
112  - Legacy data plane SDKs → modern com.azure equivalents
113  - Add azure-sdk-bom for version management
114 
115  SAMPLE:
116  - Add azure-sdk-bom for centralized version management of com.azure.* dependencies
117  - Replace azure-client-authentication with azure-identity (modern authentication library)
118  - Add jackson-databind if file-based authentication is used and Jackson is not already present
119-->
120 
121## Upgrade Steps
122 
123<!--
124  Step-by-step upgrade plan. Each step should follow this format:
125  - **Step N: <Descriptive Title>**
126    - **Rationale**: Why this step is needed and why at this position
127    - **Changes to Make**: ≤5 bullet points (concise)
128    - **Verification**: Command, JDK, Expected Result
129 
130  VERIFICATION EXPECTATIONS:
131  - Steps 1-N (Setup and Upgrade steps): Focus on COMPILATION SUCCESS. Tests may fail during intermediate steps.
132  - Final step: COMPILATION SUCCESS + TEST PASS through iterative fix loop.
133 
134  MANDATORY FIRST STEP:
135  The first step MUST always be Setup Baseline.
136 
137  MANDATORY SETUP BASELINE STEP SAMPLE:
138 
139  - Step 1: Setup Baseline
140    - **Rationale**: Establish pre-upgrade compile and test results to measure upgrade success against.
141    - **Changes to Make**:
142      - [ ] Run baseline compilation with current JDK
143      - [ ] Run baseline tests with current JDK
144    - **Verification**:
145      - Command: `mvn clean compile test-compile -q && mvn clean test -q`
146      - JDK: <current project JDK path>
147      - Expected: Document SUCCESS/FAILURE, test pass rate (forms acceptance criteria)
148 
149  ---
150 
151  SAMPLE STEP (dependency migration):
152 
153  - Step N: Migrate Azure Management Dependencies
154    - **Rationale**: Replace legacy com.microsoft.azure management dependencies with modern com.azure.resourcemanager equivalents.
155    - **Changes to Make**:
156      - [ ] Add azure-sdk-bom to dependencyManagement
157      - [ ] Replace com.microsoft.azure:azure-mgmt-* with com.azure.resourcemanager:azure-resourcemanager
158      - [ ] Remove com.microsoft.azure:azure-client-authentication, add com.azure:azure-identity
159      - [ ] Fix compilation errors from API changes
160    - **Verification**:
161      - Command: `mvn clean test-compile -q`
162      - JDK: <JDK path>
163      - Expected: Compilation SUCCESS (tests may fail - will be fixed in Final Validation)
164 
165  ---
166 
167  MANDATORY FINAL STEP (must always be the last step):
168 
169  - Step N: Final Validation
170    - **Rationale**: Verify all upgrade goals met, project compiles successfully, all tests pass.
171    - **Changes to Make**:
172      - [ ] Verify no legacy com.microsoft.azure.* dependencies remain
173      - [ ] Resolve ALL TODOs and temporary workarounds from previous steps
174      - [ ] Clean rebuild with current JDK
175      - [ ] Fix any remaining compilation errors
176      - [ ] Run full test suite and fix ALL test failures (iterative fix loop until 100% pass)
177    - **Verification**:
178      - Command: `mvn clean test -q`
179      - JDK: <JDK path>
180      - Expected: Compilation SUCCESS + 100% tests pass
181-->
182 
183## Key Challenges
184 
185<!--
186  Document high-risk areas that require special attention during upgrade.
187  Each challenge should have a mitigation strategy. Be concise.
188  Common challenges for Azure SDK migration:
189  - Authentication pattern changes (file-based auth, service principal)
190  - API surface changes (fluent builder patterns differ between legacy and modern)
191  - Async/reactive pattern differences
192  - Package structure changes (com.microsoft.azure.management.* → com.azure.resourcemanager.*)
193 
194  SAMPLE:
195  - **Authentication Migration**
196     - **Challenge**: Legacy code uses file-based authentication via Azure.authenticate(credentialFile). Modern SDK requires explicit credential construction.
197     - **Strategy**: Read credential file with Jackson ObjectMapper, construct ClientSecretCredential, use AzureProfile for subscription context.
198  - **Fluent API Changes**
199     - **Challenge**: Method names and builder patterns differ between legacy and modern Azure Resource Manager.
200     - **Strategy**: Follow the migration guide at https://aka.ms/java-track2-migration-guide for method-level mappings.
201-->
202