Problem Statement

The current plugin discovery workflow has several limitations that prevent it from making optimal upgrade decisions:

• Rigid Version Matching:
  The process can only identify plugins that are an Exact Match for a target Backstage version. It fails to propose upgrades for plugins that are older but still compatible ("Best-Effort" matches), causing many plugins to be left behind on older versions.

• No Awareness of Manual Overrides:
  The workflow is blind to the manual backstage.json overrides configured within the overlay repository's workspace folders. This causes two major issues:
  1. It fails to propose PRs on branches where an override makes a plugin compatible.
  2. It cannot make intelligent decisions that respect the manual configuration that these overrides represent.

Proposed Solution & Goals

The goal is to re-architect the discovery logic to be more intelligent, context-aware, and informative. This will be achieved through the following enhancements:

• Introduce "Best-Effort" Matching
  The workflow will be updated to identify not just "Exact Matches," but also "Best-Effort Matches." This involves finding the newest available plugin version that is older than or equal to the target Backstage version.
  • Benefit: This will significantly increase the number of valid upgrade paths the system can discover and propose.

• Acknowledge Manual Overrides
  The script will now read the optional, per-workspace backstage.json file in the overlay. The existence of this file will be used to classify the currently installed version as having an "Overridden" match quality. This gives us a clear quality hierarchy: Exact Match > Overridden Match > Best-Effort Match.
  • Benefit: The system can now respect the manual configuration done by the team, using this information to make smarter future decisions.

• Generate Context-Aware Pull Requests The system will generate PRs with additional dynamic, informative mentions, as well as optional label, based on the nature of the upgrade in the 2 following cases:
  1. Celebrate Cleanup Opportunities. When an upgrade moves from an Overridden version to a true Exact Match, the PR body will be decorated with a "🎉 Override Can Be Removed!" message. This will prompt the developer to delete the now-obsolete override file, reducing technical debt.
  2. Flag Risky Upgrades. When an upgrade moves from an Overridden version to a Best-Effortone, the PR will still be created, but the body will include a prominent "⚠️ Manual Approval Required"warning. This ensures full automation while maintaining critical human oversight for changes that need re-testing.