fortify-dependency-upgrade

Dependency upgrades often break more than the manifest line. Follow the workflow below completely before reporting migration complete.

Resources

Analysis workflow: references/dependency-analysis.md

Ecosystem command references:

Ecosystem	Reference
.NET / NuGet	references/dotnet.md
Node.js	references/nodejs.md
Python / pip/poetry	references/python.md
JVM / Maven	references/maven.md
JVM / Gradle	references/gradle.md
Go	references/go.md
Rust / Cargo	references/rust.md
Ruby / Bundler	references/ruby.md
PHP / Composer	references/php.md
C++ / CMake/Conan/vcpkg	references/cpp.md
iOS / macOS	references/ios-macos.md
Scala / sbt/Mill	references/scala.md

Mandatory Workflow

Complete each step before proceeding. Do not skip steps.

Step 1: Preparation & Baseline

Read: your ecosystem reference from the Resources table above, references/dependency-analysis.md §1-2

1. Identify all manifest files (use ecosystem command)
2. Confirm current version, verify target version exists (STOP if not published)
3. Run full test suite against the unmodified codebase, record baseline (MANDATORY - use ecosystem command)
   • Capture total tests, passes, failures, errors, and skips
   • If any tests fail before any changes are made:
     • Identify each failing test and classify it:
       • Upgrade-adjacent: directly imports or exercises the package being upgraded
       • Unrelated: fails for reasons independent of the target dependency
     • Report all pre-existing failures to the user immediately, with the classification above, before continuing
     • Do NOT assume pre-existing failures are acceptable — the user must acknowledge them
4. Identify which test files import or exercise the package(s) being upgraded (see ecosystem reference "Find Affected Tests")
   • Search for direct imports of the package and for imports of modules that transitively depend on it
   • Record this list as the affected test scope for use in Step 7
   • If the affected test scope is empty (no tests exercise the package or its transitive dependencies):
     • State this explicitly in the baseline report and in the final report
     • Do NOT treat a passing/unchanged test run as confirmation the upgrade is safe — it only confirms no regression in unrelated code
     • Note the verification gap in Step 8
5. Run dependency tree (use ecosystem command)
6. Create reports/{package}-{old}-to-{new}-dependency-analysis.md with §1-2

Deliver: Baseline test results (including pre-existing failures reported to user) + affected test scope (or explicit statement that scope is empty) + dependency tree documented STOP: Do not proceed until baseline documented and any pre-existing failures reported to the user. If tests cannot run, document why.

Step 2: Proposed Dependency Graph

Read: your ecosystem reference from the Resources table above, references/dependency-analysis.md §3

1. Update manifest files with new versions (do NOT commit)
2. Regenerate dependency graph (use ecosystem command)

   Dependency graph resolution is independent of compilation. Run the dependency tree command even if the build is currently broken.

3. Document §3 from references/dependency-analysis.md
4. Identify related packages needing upgrades

Deliver: Proposed dependency graph for ALL projects STOP: Do not proceed until graph documented. A broken build does not exempt you from completing this step — do not substitute external research (Step 4) for the dependency graph comparison (Steps 2–3).

Step 3: Conflict Resolution

Read: your ecosystem reference from the Resources table above, references/dependency-analysis.md §4-5

1. Compare graphs: list added/removed/upgraded/downgraded packages (§4)
2. Build compatibility matrix: verify versions satisfy all dependency ranges (§5)
3. Resolve ALL conflicts or justify acceptance

Deliver: Compatibility matrix with conflicts resolved STOP: Do not proceed with unresolved conflicts.

Step 4: External Resource Research Report

Before researching breaking changes, fetch and record all relevant data from official external sources into a dedicated report file that every subsequent step will reference.

1. Collect the following for the target package (official sources only — URLs required):

   • Release notes / changelog (GitHub Releases, CHANGELOG.md, PyPI release history, npm changelog)
   • Official migration guide for the specific version range
   • Deprecation notices, removed APIs, and behavioral changes documented in release artifacts
   • Security advisories or CVEs fixed in the new version (if any)

   Fortify SCA integration: If this upgrade was triggered by Fortify SCA / open source findings, use the fortify-fod or fortify-ssc skill (whichever platform applies) before populating the Security Fixes section to query the open source issues for the affected component. Retrieve the complete set of CVE identifiers, affected version ranges, and minimum safe version recommendations from the Fortify issue data. Record that output here under Security Fixes — do not rely solely on external advisory sites when Fortify issue data is available.

2. Create reports/{package}-{old}-to-{new}-external-research.md using this template:

   # External Research Report: {Package} {OldVersion} → {NewVersion}
   
   **Date:** {Current Date}
   **Package Manager / Registry:** {PyPI / npm / Maven Central / etc.}
   
   ## Sources Consulted
   
   | # | Resource | URL | Accessed |
   |---|----------|-----|----------|
   | 1 | Official Changelog / Release Notes | {URL} | {Date} |
   | 2 | Migration Guide | {URL} | {Date} |
   | 3 | GitHub Releases page | {URL} | {Date} |
   | 4 | Security advisories | {URL or "None"} | {Date} |
   
   ## Breaking Changes & Removals
   
   > Items confirmed to affect this codebase are flagged ⚠️.
   
   | # | Type | Description | Affected Versions | Source (row #) |
   |---|------|-------------|-------------------|----------------|
   | 1 | API removed | `OldClass.method()` removed | ≥ {NewVersion} | #1 |
   | 2 | Import path changed | `from old.path import X` → `from new.path import X` | ≥ {NewVersion} | #2 |
   | 3 | Config key renamed | `OLD_SETTING` → `NEW_SETTING` | ≥ {NewVersion} | #1 |
   
   ## Deprecations (not yet removed)
   
   | # | Symbol / Feature | Replacement | Deprecated Since | Source |
   |---|-----------------|-------------|-----------------|--------|
   
   ## Security Fixes
   
   | CVE / Advisory | Severity | Description | Fixed In | Source |
   |---------------|----------|-------------|----------|--------|
   
   ## Migration Checklist
   
   - [ ] {action item derived from above}
   
   ## Raw Notes / Excerpts
   
   > {Paste relevant changelog or migration guide sections verbatim}
   

   • Record the source URL for every item
   • Summarise deprecated/removed APIs, config key renames, import path changes, and behavioral shifts under clearly labelled headings
   • Flag items that are confirmed to affect this codebase with ⚠️

3. All subsequent steps (5–8) must cite this file rather than re-fetching external URLs.

Deliver: reports/{package}-{old}-to-{new}-external-research.md with all external data captured and URL-cited STOP: Do not proceed to Step 5 without this file. All external research must be recorded here first.

Step 5: Breaking Changes

Read: reports/{package}-{old}-to-{new}-external-research.md (Step 4)

1. Identify breaking changes from the external research report (no new external fetches needed — cite the report)
2. Find affected code: imports, APIs, configs, tests
3. Create breaking change table with source URLs (reference the external research report for each URL)

Deliver: Breaking change table with source URL for each item

Step 6: Apply Changes

Read: your ecosystem reference from the Resources table above, references/dependency-analysis.md §6, reports/{package}-{old}-to-{new}-external-research.md

1. Create snapshot: reports/{package}-{old}-to-{new}-snapshot.md (include link to external research report)
2. Update manifests, code, configs, tests
3. Never delete failing tests - update to new behavior
4. Restore packages, build project (use ecosystem commands)

Deliver: Updated code + successful build STOP: If build fails, fix before proceeding.

Step 7: Verification - MANDATORY

Read: your ecosystem reference from the Resources table above — use the Run Tests section

1. Run full test suite (use ecosystem command)
2. Check whether the affected test scope (from Step 1) is empty:
   • If empty: state explicitly that no tests exercise the upgraded package or its transitive dependencies. The identical result vs baseline confirms no regression in unrelated code only — it is NOT evidence the upgrade is safe for the package's own behaviour. Record this as a verification gap in the final report.
   • If non-empty: continue with the steps below.
3. Identify affected tests — from the affected test scope recorded in Step 1, confirm which of those tests now pass, still fail, or are newly failing
4. Compare all results to the Step 1 baseline using this classification:
   • Newly failing (upgrade-related): passes in baseline, fails now, in the affected test scope → must be fixed
   • Newly failing (unexpected): passes in baseline, fails now, outside affected test scope → investigate and fix
   • Pre-existing / baseline failures: already failing in Step 1 — do NOT count these as regressions; they were reported to the user in Step 1
   • Fixed by upgrade: failing in baseline but now pass → note as improvement
5. Tell the user:
   • Whether the affected test scope is empty and what that means for confidence in the upgrade
   • How many tests are in the affected scope (if non-empty) and what their post-upgrade status is
   • Any newly failing tests, with root cause
   • Which pre-existing failures remain (reference the Step 1 report — do not re-classify)
6. Document results in dependency-analysis.md §6
7. If tests fail: analyze, fix, return to Step 6, re-test

Report:

• Pass: baseline → current (e.g., "100/100 → 100/100")
• Fail: document each failure, root cause, upgrade-caused or pre-existing
• Cannot run: state why, run only unit tests if possible
• Empty scope: state this explicitly and record as a verification gap

Deliver: Test results ≥ baseline STOP: Migration NOT complete if tests fail/skipped.

Step 8: Final Report

Read: references/dependency-analysis.md §7

1. Complete dependency-analysis.md §7
2. Create reports/{package}-{old}-to-{new}.md with:
   • Link to reports/{package}-{old}-to-{new}-external-research.md (Step 4 research report)
   • Test baseline vs final comparison
   • Breaking changes fixed (cross-referenced with external research report)
   • Files modified, dependencies updated
   • Iterations and verification gaps

Status:

• COMPLETE: Tests pass, all documented
• INCOMPLETE: Tests couldn't run (state why)
• FAILED: Tests fail (state cause)

DO NOT report "complete" if tests not run or failed.

Fortify SCA integration: If this upgrade was triggered by Fortify SCA / open source findings, use the fortify-fod or fortify-ssc skill after this step to confirm the open source issues are resolved (e.g., re-scan or re-query the component) and to handle any required audit/closure actions in FoD or SSC.

Output

Breaking Change Table

Create during Step 5, include in reports/{package}-{old}-to-{new}-snapshot.md in Step 6 step 1:

#	Path	From	To	Old	New	Source
1	src/Foo.java:12	1.x	2.0	OldClass (removed)	NewClass	https://...

Migration Summary

Include in final report:

• Breaking changes found/fixed
• Files modified
• Dependencies updated (transitive/peer)
• Breaking changes researched but not applicable
• Pre-existing test failures
• Affected test scope — list the test files that exercise the upgraded package; if none exist, state "empty scope" and record as a verification gap
• Verification gaps