backstage / backstage/community-plugins

🔧 Repository: enhance workspace-level READMEs

Open
#4,056 9 comments 5 reactions 0 assignees View on GitHub
do-not-stale enhancement good first issue help wanted
Dominant language
TypeScript
Stars
422
Forks
697
Avg merge
2d 6h
Merged PRs (30d)
286

Description

### 📜 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](https://github.com/backstage/community-plugins/blob/main/workspaces/announcements/README.md) and [linkerd/README.md](https://github.com/backstage/community-plugins/blob/main/workspaces/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
- [x] adr
- [x] airbrake
- [x] allure
- [x] analytics
- [x] apache-airflow
- [x] apollo-explorer
- [x] azure-devops
- [x] azure-sites
- [x] azure-storage-explorer
- [x] badges
- [ ] bitrise
- [ ] blackduck
- [ ] cicd-statistics
- [ ] cloudbuild
- [ ] code-climate
- [ ] code-coverage
- [ ] codescene
- [x] copilot
- [ ] cost-insights
- [ ] dynatrace
- [x] entity-feedback
- [ ] entity-validation
- [ ] explore
- [ ] firehydrant
- [ ] fossa
- [ ] gcalendar
- [ ] gcp-projects
- [ ] git-release-manager
- [ ] github-deployments
- [ ] github-issues
- [ ] gitops-profiles
- [ ] gocd
- [ ] grafana
- [x] graphiql
- [ ] graphql-voyager
- [ ] ilert
- [ ] kafka
- [ ] lighthouse
- [ ] linguist
- [ ] mend
- [ ] microsoft-calendar
- [ ] newrelic
- [ ] nomad
- [ ] octopus-deploy
- [ ] opencost
- [ ] periskop
- [x] playlist
- [ ] puppetdb
- [ ] rollbar
- [x] scaffolder-relation-processor
- [ ] shortcuts
- [ ] splunk
- [x] stack-overflow
- [ ] stackstorm
- [x] tech-radar
- [x] todo
- [ ] xcmetrics

Contributor guide

Open the contributing guide

Research direction

Start by comparing workspaces/announcements/README.md and workspaces/linkerd/README.md, then inspect the unchecked workspace-level README.md files and their plugins/ directories. Add each workspace's purpose and a Plugins list with links and descriptions where plugin READMEs exist; done means the listed default README workspaces have useful, consistent documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
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.