-
Notifications
You must be signed in to change notification settings - Fork 55
Plugin Owner Guide
As a plugin owner, you are responsible for maintaining the health and compatibility of your plugin within this dynamic plugins ecosystem. This guide outlines your obligations and best practices.
You are a plugin owner if you:
- Maintain the source plugin in upstream repositories (backstage/backstage, backstage/community-plugins, rhdh-plugins, etc.)
- Created or modified the overlay configuration for your plugin
- Are assigned as maintainer by your organization
| Area | Frequency | Criticality |
|---|---|---|
| Metadata synchronization | Every release | 🔴 High |
| Backstage version updates | When compatibility signals appear | 🔴 High |
| Patch maintenance | As needed | 🟡 Medium |
| Test validation | Every PR | 🔴 High |
| Deprecation communication | As needed | 🟡 Medium |
Your plugin exists in two places that must stay in sync:
| Location | Files | Owner Updates |
|---|---|---|
| Source Repo |
package.json, src/
|
When you release new versions |
| Overlay Repo |
source.json, metadata/*.yaml
|
When source changes |
What must match:
| Field | Source Location | Overlay Location |
|---|---|---|
| Version | package.json:version |
metadata/*.yaml:spec.version |
| Package name | package.json:name |
metadata/*.yaml:spec.packageName |
| Backstage deps | package.json:dependencies |
metadata/*.yaml:spec.backstage.supportedVersions |
| Description | package.json:description |
metadata/*.yaml:metadata.title |
⚠️ Warning: Metadata drift causes build failures, incorrect catalog entries, and compatibility issues.
See 04 - Metadata Synchronization for detailed procedures.
The target platform tracks Backstage releases. Your plugin must remain compatible with the version declared in versions.json.
Rather than following a fixed calendar cadence, watch for concrete signals that an update is needed:
- The Backstage Compatibility Report shows your workspace as incompatible
- A new platform release branch is being created and your plugin blocks it
- Automated discovery PRs fail the compatibility check for your workspace
- Upstream has released a version built against the current target Backstage version
When any of these signals appear:
- Check the target Backstage version in
versions.json - Find a plugin release compatible with that version
- Update
repo-refandrepo-backstage-versioninsource.json - Update
supportedVersionsin metadata files - Test with
/publishand/smoketest, and run workspace E2E validation when available for that workspace
See 01 - Getting Started: Testing Your Plugin for test workflow details.
See 05 - Version Updates for detailed procedures.
If your plugin requires patches:
| Task | When | Action |
|---|---|---|
| Verify patches apply | Every source update | Ensure patches don't conflict |
| Re-roll patches | When context changes | Update line numbers/context |
| Remove patches | When fix is upstream | Delete obsolete patches |
| Document patches | Always | Explain why each patch exists |
⚠️ Warning: Stale patches cause silent failures or unexpected behavior.
See 06 - Patch Management for detailed procedures.
When automated workflows fail on your workspace:
- Investigate immediately – Failures block releases
-
Check the error type:
- Build failure → Fix source or add patch
- Integrity failure → Sync metadata
- Test failure → Verify plugin loads correctly
- Open a PR with the fix
-
Validate with
/publishand/smoketestcommands
Notify downstream users when:
| Change | Communication |
|---|---|
| Breaking API changes | Update metadata, document migration |
| Deprecation | Add deprecation notice, timeline |
| New dependencies | Update plugins-list.yaml with embed args |
| Configuration changes | Update appConfigExamples in metadata |
Use this checklist when updating your plugin (triggered by a compatibility signal, a new upstream release, or a platform version bump):
## Plugin Maintenance - [Plugin Name] - [Date]
### Version Check
- [ ] Checked target Backstage version in versions.json
- [ ] Found a plugin release compatible with the target version
- [ ] Updated `source.json:repo-ref` and `repo-backstage-version`
- [ ] Updated `metadata/*.yaml:spec.version` and `spec.backstage.supportedVersions`
### Metadata Check
- [ ] Verified `spec.packageName` matches source `package.json:name`
- [ ] Reviewed and updated `appConfigExamples` if configuration changed
- [ ] Updated metadata links (source, issues, docs) if needed
### Patch Check
- [ ] Verified all patches apply cleanly to current source
- [ ] Removed any patches that are now in upstream
- [ ] Documented any new patches required
### Test Validation
- [ ] PR created with updates
- [ ] `/publish` completed successfully
- [ ] `/smoketest` passed or manual testing completed
- [ ] PR mergedWhen deprecating a plugin:
spec:
lifecycle: deprecated # Changed from 'active'
# Add deprecation notice- Open an issue documenting the deprecation
- Provide migration path to replacement plugin
- Set a timeline for removal (typically 2 release cycles)
When the grace period ends, remove the workspace entirely:
- Delete the workspace folder (including
source.json,plugins-list.yaml, metadata files, and any patches) - Document removal in release notes
Important: Simply commenting out entries in
plugins-list.yamlor removing metadata files while keeping the workspace folder is not sufficient. If the workspace folder andsource.jsonremain, automatic discovery will detect the plugin again and propose re-adding it. To permanently remove a plugin, delete the entire workspace directory.
| Issue | Where to Go |
|---|---|
| Build failures | Check workflow logs, open issue |
| Patch conflicts | See 06 - Patch Management |
| Compatibility questions | Check the Backstage Compatibility Report |
| Process questions | Open a discussion or issue |
- 04 - Metadata Synchronization – Detailed sync procedures
- 05 - Version Updates – Version update guide
- 06 - Patch Management – Patch maintenance
- 66 workspaces
- 6 with patches