backstage / backstage/community-plugins

🚀 tech-insights-maturity: Make the "Maturity" label and help link configurable (currently requires a yarn patch)

Open
#9,773 3 comments 0 reactions 0 assignees View on GitHub
enhancement help wanted workspace/tech-insights
Dominant language
TypeScript
Stars
422
Forks
697
Avg merge
2d 6h
Merged PRs (30d)
286

Description

### Workspace

tech-insights

### 🔖 Feature description

The `@backstage-community/plugin-tech-insights-maturity` plugin hardcodes the
word **"Maturity"** and the help **"(?)" tooltip link** across the whole UI.
There is currently no prop or `app-config.yaml` option to override either of
them, so adopters who want to present the feature under a different name (e.g.
"Scorecards") or point the help icon at their own internal documentation have
to fork the plugin or maintain a `yarn patch`.

We would like first-class, supported customization for:

1. **Renaming the "Maturity" label at every level** it is rendered:
- the overview entity card (`EntityMaturitySummaryCard`),
- the dedicated Component tab content (`EntityMaturityScorecardContent`) and its table,
- the System / Domain / Group summary tab (`EntityMaturitySummaryContent`) and its table,
- the standalone global `MaturityPage`,
2. **Customizing the "(?)" help tooltip** so the link URL (and ideally the
tooltip text) can be customized and point to our own docs instead of the plugin README.

Any link that is affected by a rename (e.g. deep-links to the maturity tab)
must keep working after the rename — see the Context section, this is the part
that currently makes patching brittle.

### 🎤 Context

We run the maturity plugin internally but present it to our developers under a
different product name and link the "learn more" icon to our internal
handbook. Today the only way to achieve this is a `yarn patch`, because the
strings and URL are hardcoded with no override:

| Where it renders | Hardcoded location |
| --- | --- |
| Overview card title `Maturity` | `src/components/MaturitySummaryInfoCard/MaturitySummaryInfoCard.tsx` (~L44) |
| Summary table title `Component Maturity` + subtitle | `src/components/MaturitySummaryTable/MaturitySummaryTable.tsx` (~L238–L239) |
| Standalone page header `` | `src/components/MaturityPage/MaturityPage.tsx` (~L35) |
| New frontend system tab titles `Maturity` / `Maturity Summary` | `src/alpha/entityContent.tsx` (~L29), `src/alpha/entitySummaryContent.tsx` (~L29) | |
| Public component extensions | `src/plugin.ts` — `EntityMaturityScorecardContent`, `EntityMaturitySummaryContent`, `EntityMaturitySummaryCard`, `MaturityPage` accept no `title` prop |
| Help "(?)" tooltip text + URL | `src/helpers/MaturityHelp.tsx` (~L21–L22) — hardcoded README link |

For comparison, the base `@backstage-community/plugin-tech-insights` plugin's
`EntityTechInsightsScorecardContent` and `EntityTechInsightsScorecardCard`
already accept `title` / `description` props, so the maturity plugin is
inconsistent here.

We believe this is generally useful (not just for us): white-labeling the
feature name and linking to internal onboarding docs are common enterprise
needs, and the rank titles/descriptions are already customizable via
`techInsights.maturity.rank.*`, so extending that pattern to the feature label
and help link would be consistent.

### ✌️ Possible Implementation

Not obligatory, but some ideas:

- **`app-config.yaml` options** (consistent with the existing `techInsights.maturity.rank.*` config), e.g.:

```yaml
techInsights:
maturity:
# Custom display name used for card titles, tab titles, page header, table titles
label: 'Scorecards'
help:
# Custom "(?)" tooltip target + text
url: 'https://internal.example.com/docs/maturity'
tooltip: 'Learn more about our Scorecards'
```

These would be read once and applied by `MaturitySummaryInfoCard`,
`MaturitySummaryTable`, `MaturityPage`, `MaturityHelp` (, and the
`src/alpha/*` extension params).
- **and/or component props** on the public extensions (mirroring
`EntityTechInsightsScorecardContent`'s `title`/`description`), e.g.
``,
``.
- Make `MaturityLink` resolve the tab path from the plugin's route ref instead
of the hardcoded `/maturity` string so renamed/remounted routes keep working.

### 👀 Have you spent some time to check if this feature request has been raised before?

- [x] I checked and didn't find similar issue

### 🏢 Have you read the Code of Conduct?

- [x] I have read the [Code of Conduct](https://github.com/backstage/community-plugins/blob/main/CODE_OF_CONDUCT.md)

### Are you willing to submit PR?

No, but I'm happy to collaborate on a PR with someone else

Contributor guide

Open the contributing guide

Research direction

Start by reading src/plugin.ts and the named components in src/components, src/helpers/MaturityHelp.tsx, and src/alpha/*. Trace how titles, help links, and MaturityLink paths are supplied and compare the base tech-insights extension props. Done means the label and help URL/text are configurable across all listed surfaces while affected links continue to resolve correctly.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
developer-experience, frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.