The backstage/community-plugins repository is designed as a collaborative space for Backstage community members to host and manage their plugins for Backstage. This repository will provide plugin maintainers with tools for plugin management and publication. By contributing a plugin to this repository, maintainers agree to adhere to specific guidelines and a standardized release process detailed in this guide.
If you have questions or feedback regarding Community Plugins, you can visit the Community Plugins #general channel in the Backstage Discord.
By contributing to Backstage Community Plugins you agree to adhere to the CNCF Code of Conduct.
The community plugins repository is under Apache 2.0 license. All plugins added & moved to the repository will be kept under the same license. If you are moving a plugin over make sure that no other license file is in the plugin workspace & all package.json files either have no version defined or explicitly use “Apache 2.0”.
See SECURITY.
So...feel ready to jump in? Let's do this. 👏🏻 💯
Ok. So you're gonna want some code right? Go ahead and fork the repository into your own GitHub account and clone that code to your local machine. GitHub's Fork a repo documentation has a great step by step guide if you are not sure how to do this.
If you cloned a fork, you can add the upstream dependency like so:
git remote add upstream git@github.com:backstage/community-plugins.git
git pull upstream mainAfter you have cloned the Community Plugins repository, you should run the following commands once to set things up for development:
# jump in to the community-plugins repo that you cloned
cd community-plugins
# install the root dependencies so that you can create workspaces if needed
yarn install
# navigate to a workspace that you're working on
cd workspaces/linguist
# install the workspace dependencies
yarn installFrontend and Backend plugins come with a standalone runner that you should be able to utilize in order to develop on your plugins in isolation. You can navigate to a workspace and a plugin inside the plugin folder and run yarn start which should kick off the development standalone server for that plugin. It's also possible that this might not be setup for plugins that were migrated from the backstage/backstage repository, in which case you can set them up following some prior art in the backstage/backstage repository. backend plugin dev and frontend plugin dev examples.
There could be times when there is a need for a more rich development environment for a workspace. Say that the workspace and it's plugin depend on a full catalog, and maybe the kubernetes plugin already running too, that could be a bit of a pain to set up. In that case, there might be a full Backstage environment that you can run with yarn dev in the workspace root, which will start up a full Backstage environment located in $WORKSPACE_ROOT/packages/app and $WORKSPACE_ROOT/packages/backend.
Important
This full Backstage environment is not setup by default, and is setup on a per workspace basis. Check out the workspace README.md for more information on how to get a dev environment setup for each plugin.
All code is formatted with prettier using the configuration in the repo. If possible we recommend configuring your editor to format automatically, but you can also use the yarn prettier --write <file> command to format files.
For the versioning all packages in this repository are following the semantic versioning standard enforced through Changesets. This is the same approach as in the main “backstage/backstage” repository. If this is your first time working with Changesets checkout this documentation or read a quick summary below.
We use changesets to help us prepare releases. They help us make sure that every package affected by a change gets a proper version number and an entry in its CHANGELOG.md. To make the process of generating releases easy, it helps when contributors include changesets with their pull requests. These changesets can be created by going into a workspace directory and running yarn changeset and following the prompts.
cd community-plugins
cd workspaces/linguist
yarn changeset # follow the promptsAs soon as a plugin is part of the community plugins repository every PR with a change is expected to contain a changeset. As soon as the PR is merged a follow up PR will be created called “Version Packages (your-plugin-name)”. This version packages PR will remove the merged changeset & add it to the changelog for the specific plugin. Additionally the version in the package.json is adjusted.
A release is automatically triggered by merging the plugins “Version Packages” PR.
For workspaces the name should reflect the name of the plugins contained in a simple manner (e.g. for the plugins todo & todo-backend the workspace would be called todo).
For plugins we will continue to follow the naming pattern suggested by the ADR on the main repository: https://backstage.io/docs/architecture-decisions/adrs-adr011.
You can create a workspace by running the following:
# jump in to the community-plugins repo that you cloned
cd community-plugins
# install the root dependencies so that you can create workspaces
yarn install
# create a workspace and follow the prompt
yarn create-workspaceFrom there, once the script has finished, you should have a new yarn workspace with it's own changesets and releases. You can navigate to the workspace and start developing your plugin.
Once you have a workspace setup, the creation of new plugins and packages is just like any other Backstage repository. You can use the yarn new command to run the prompt for creating new plugins or packages.
cd workspaces/adr
yarn newBackstage Community Plugins has adopted a Developers Certificate of Origin (DCO) - refer to the Backstage CONTRIBUTING.md#developer-certificate-of-origin for more information on the DCO and guidance on signing commits.