≈2.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.
<!--
This is the upgrade progress tracker for Azure SDK migration.
Each step from plan.md should be tracked here with status, changes, verification results, and TODOs.
## EXECUTION RULES
!!! DON'T REMOVE THIS COMMENT BLOCK BEFORE UPGRADE IS COMPLETE AS IT CONTAINS IMPORTANT INSTRUCTIONS.
### Success Criteria
- **Goal**: All legacy Azure SDK dependencies (com.microsoft.azure.*) replaced with modern equivalents (com.azure.*)
- **Compilation**: Both main source code AND test code compile = `mvn clean test-compile` succeeds
- **Test**: 100% test pass rate = `mvn clean test` succeeds (or ≥ baseline with documented pre-existing flaky tests)
### Strategy
- **Uninterrupted run**: Complete execution without pausing for user input
- **NO premature termination**: Token limits, time constraints, or complexity are NEVER valid reasons to skip fixing.
- **Automation tools**: Use OpenRewrite etc. for efficiency; always verify output
### Verification Expectations
- **Steps 1-N (Setup/Upgrade)**: Focus on COMPILATION SUCCESS (both main and test code).
- On compilation success: Commit and proceed (even if tests fail - document count)
- On compilation error: Fix IMMEDIATELY and re-verify until both main and test code compile
- **NO deferred fixes** (for compilation): "Fix post-merge", "TODO later", "can be addressed separately" are NOT acceptable. Fix NOW or document as genuine unfixable limitation.
- **Final Validation Step**: Achieve COMPILATION SUCCESS + 100% TEST PASS.
- On test failure: Enter iterative test & fix loop until 100% pass or rollback to last-good-commit after exhaustive fix attempts
- **NO deferring test fixes** - this is the final gate
- **NO categorical dismissals**: "Test-specific issues", "doesn't affect production", "sample/demo code" are NOT valid reasons to skip. ALL tests must pass.
- **NO "close enough" acceptance**: 95% is NOT 100%. Every failing test requires a fix attempt with documented root cause.
- **NO blame-shifting**: "Known framework issue", "migration behavior change" require YOU to implement the fix or workaround.
### Review Code Changes (MANDATORY for each step)
After completing changes in each step, review code changes BEFORE verification to ensure:
1. **Sufficiency**: All changes required for the upgrade goal are present — no missing modifications that would leave the upgrade incomplete.
- All dependencies/plugins listed in the plan for this step are updated
- All required code changes (API migrations, import updates, config changes) are made
- All compilation and compatibility issues introduced by the upgrade are addressed
2. **Necessity**: All changes are strictly necessary for the upgrade — no unnecessary modifications, refactoring, or "improvements" beyond what's required. This includes:
- **Functional Behavior Consistency**: Original code behavior and functionality are maintained:
- Business logic unchanged
- API contracts preserved (inputs, outputs, error handling)
- Expected outputs and side effects maintained
- **Security Controls Preservation** (critical subset of behavior):
- **Authentication**: Login mechanisms, session management, token validation, MFA configurations
- **Authorization**: Role-based access control, permission checks, access policies, security annotations (@PreAuthorize, @Secured, etc.)
- **Password handling**: Password encoding/hashing algorithms, password policies, credential storage
- **Security configurations**: CORS policies, CSRF protection, security headers, SSL/TLS settings, OAuth/OIDC configurations
- **Audit logging**: Security event logging, access logging
**Review Code Changes Actions**:
- Review each changed file for missing upgrade changes, unintended behavior or security modifications
- If behavior must change due to framework requirements, document the change, the reason, and confirm equivalent functionality/protection is maintained
- Add missing changes that are required for the upgrade step to be complete
- Revert unnecessary changes that don't affect behavior or security controls
- Document review results in progress.md and commit message
### Commit Message Format
- First line: `Step <x>: <title> - Compile: <result>` or `Step <x>: <title> - Compile: <result>, Tests: <pass>/<total> passed`
- Body: Changes summary + concise known issues/limitations (≤5 lines)
- **Security note**: If any security-related changes were made, include "Security: <change description and justification>"
### Efficiency (IMPORTANT)
- **Targeted reads**: Use `grep` over full file reads; read specific sections, not entire files. Template files are large - only read the section you need.
- **Quiet commands**: Use `-q`, `--quiet` for build/test commands when appropriate
- **Progressive writes**: Update progress.md incrementally after each step, not at end
-->Upgrade Progress: <PROJECT_NAME> (<RUN_ID>)
- Started: <timestamp> <!-- replace with actual start timestamp -->
- Plan Location:
.github/java-upgrade/<RUN_ID>/plan.md
- Total Steps: <number of steps from plan.md>
Step Details
<!--
For each step in plan.md, track progress using this bullet list format:
- **Step N: <Step Title>**
- **Status**: <status emoji>
- 🔘 Not Started - Step has not been started yet
- ⏳ In Progress - Currently working on this step
- ✅ Completed - Step completed successfully
- ❗ Failed - Step failed after exhaustive attempts
- **Changes Made**: (≤5 bullets, keep each ≤20 words)
- Focus on what changed, not how
- **Review Code Changes**:
- Sufficiency: ✅ All required changes present / ⚠️ <list missing changes added, short and concise>
- Necessity: ✅ All changes necessary / ⚠️ <list unnecessary changes reverted, short and concise>
- Functional Behavior: ✅ Preserved / ⚠️ <list unavoidable changes with justification, short and concise>
- Security Controls: ✅ Preserved / ⚠️ <list unavoidable changes with justification and equivalent protection, short and concise>
- **Verification**:
- Command: <actual command executed>
- JDK: <JDK path used>
- Build tool: <Path of build tool used>
- Result: <SUCCESS/FAILURE with details>
- Notes: <any skipped checks, excluded modules, known issues>
- **Deferred Work**: List any deferred work, temporary workarounds (or "None")
- **Commit**: <commit hash> - <commit message first line>
---
SAMPLE UPGRADE STEP:
- **Step X: Migrate Azure Management Dependencies**
- **Status**: ✅ Completed
- **Changes Made**:
- Added azure-sdk-bom to dependencyManagement
- Replaced com.microsoft.azure:azure-mgmt-* with com.azure.resourcemanager
- Replaced azure-client-authentication with azure-identity
- **Review Code Changes**:
- Sufficiency: ✅ All required changes present
- Necessity: ✅ All changes necessary
- Functional Behavior: ✅ Preserved - API contracts and business logic unchanged
- Security Controls: ✅ Preserved - authentication pattern updated with equivalent protection
- **Verification**:
- Command: `mvn clean test-compile -q`
- JDK: /usr/lib/jvm/java-8-openjdk
- Build tool: /usr/local/maven/bin/mvn
- Result: ✅ Compilation SUCCESS | ⚠️ Tests: 10/12 passed (2 failures deferred to Final Validation)
- Notes: 2 test failures related to auth mock setup
- **Deferred Work**: Fix 2 test failures in Final Validation step (TestAuthHelper, TestResourceCreation)
- **Commit**: abc1234 - Step X: Migrate Azure Management Dependencies - Compile: SUCCESS, Tests: 10/12 passed
---
SAMPLE FINAL VALIDATION STEP:
- **Step X: Final Validation**
- **Status**: ✅ Completed
- **Changes Made**:
- Verified no legacy com.microsoft.azure.* dependencies remain
- Resolved 2 TODOs from Step 3
- Fixed 2 test failures (auth mock setup, resource assertion)
- **Review Code Changes**:
- Sufficiency: ✅ All required changes present
- Necessity: ✅ All changes necessary
- Functional Behavior: ✅ Preserved - all business logic and API contracts maintained
- Security Controls: ✅ Preserved - all authentication, authorization unchanged
- **Verification**:
- Command: `mvn clean test -q`
- JDK: /usr/lib/jvm/java-8-openjdk
- Build tool: /usr/local/maven/bin/mvn
- Result: ✅ Compilation SUCCESS | ✅ Tests: 12/12 passed (100% pass rate achieved)
- **Deferred Work**: None - all TODOs resolved
- **Commit**: xyz3456 - Step X: Final Validation - Compile: SUCCESS, Tests: 12/12 passed
-->
Notes
<!--
Additional context, observations, or lessons learned during execution.
Use this section for:
- Unexpected challenges encountered
- Deviation from original plan
- Performance observations
- Recommendations for future upgrades
SAMPLE:
- azure-sdk-bom simplified version management significantly
- Authentication migration required adding jackson-databind for file-based auth
- Modern SDK fluent API method names differ from legacy — migration guide was essential
-->
