community-plugins 🔧 Repository: enhance workspace-level READMEs

📜 Description

Many workspaces currently contain the default autogenerated README.md containing 'This is your newly scaffolded Backstage App, Good Luck!'. It is not always obvious that you may need to step into the plugins/ directory to reach documentation for the specific plugin.

I believe it would be helpful if these workspace-level READMEs, at a minimum, included:

A brief description of the workspace and its purpose.
List the plugins within the workspace (could link to the individual plugin READMEs, if they exist)

Some examples of populated workspace READMEs include: announcements/README.md and linkerd/README.md.

As suggested structure:

# [Workspace Name]

This workspace contains plugins for [brief description of purpose, e.g. exposing data from a service ].

## Plugins

- [plugin-backend](./plugins/plugin-backend/README):  Backend plugin that provides...

Plugins with the default README:

[x] 3scale
[ ] adr
[ ] airbrake
[ ] allure
[ ] analytics
[ ] apache-airflow
[ ] apollo-explorer
[ ] azure-devops
[ ] azure-sites
[ ] azure-storage-explorer
[ ] badges
[ ] bitrise
[ ] blackduck
[ ] cicd-statistics
[ ] cloudbuild
[ ] code-climate
[ ] code-coverage
[ ] codescene
[x] copilot
[ ] cost-insights
[ ] dynatrace
[ ] entity-feedback
[ ] entity-validation
[ ] explore
[ ] firehydrant
[ ] fossa
[ ] gcalendar
[ ] gcp-projects
[ ] git-release-manager
[ ] github-deployments
[ ] github-issues
[ ] gitops-profiles
[ ] gocd
[ ] grafana
[ ] graphiql
[ ] graphql-voyager
[ ] ilert
[ ] kafka
[ ] lighthouse
[ ] linguist
[ ] mend
[ ] microsoft-calendar
[ ] newrelic
[ ] nomad
[ ] octopus-deploy
[ ] opencost
[ ] periskop
[ ] playlist
[ ] puppetdb
[ ] rollbar
[x] scaffolder-relation-processor
[ ] shortcuts
[ ] splunk
[ ] stack-overflow
[ ] stackstorm
[ ] tech-radar
[ ] todo
[ ] xcmetrics

May 27 '25 16:05 BethGriggs

Yes, totally agree, there's a lost opportunity to help those looking to use plugins in the various workspaces. I wonder if we could generate some of this? Given say this workspace - https://github.com/backstage/community-plugins/tree/main/workspaces/azure-devops - we should be able to infer somethings. 🤔

May 27 '25 16:05 awanlin

Could definitely generate the plugin section from announcements example.

Jun 19 '25 16:06 kurtaking

Documentation regarding community plugins (in this repo and out in the wild) have been a pain point for a while. Would a CI step that warns contributors no documentation was found be useful?

"We noticed your readme still has the auto-generated text. Consider updating with proper documentation to provide users a better experience."

Jun 19 '25 17:06 kurtaking

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

Oct 08 '25 00:10 github-actions[bot]

We should also look at updating this - https://github.com/backstage/community-plugins/blob/main/workspaces/repo-tools/packages/cli/src/lib/workspaces/templates/workspace/README.md - with some suggested text so that way it stays up to date.

Oct 21 '25 14:10 awanlin

We should also look at updating this - https://github.com/backstage/community-plugins/blob/main/workspaces/repo-tools/packages/cli/src/lib/workspaces/templates/workspace/README.md - with some suggested text so that way it stays up to date.

This says file not found ?

Nov 24 '25 05:11 Ayushmore1214

@Ayushmore1214 it was renamed in #5995, it can now be found at https://github.com/backstage/community-plugins/blob/main/workspaces/repo-tools/packages/cli/src/lib/workspaces/templates/workspace/README.md.hbs

Dec 02 '25 16:12 hopehadfield