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.
- Contributing to
backstage/community-plugins
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 [email protected]: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.
To create a changeset, follow these steps:
- Make sure you are in the root directory of the workspace for the plugin you want to create a changeset for. For ex: if you are making changes on the
adrplugin then you should be onworkspaces/adrdir
+2. Run the following command to create a new changeset:
$ yarn changeset-
You will be prompted to select the packages and the type of change you are making.
-
Enter a short description of the change when prompted. Refer to backstage/backstage CONTRIBUTING.md#writing-changesets for additional guidance on writing changesets.
-
Review the changeset file that was created. It should be located in the
.changesetdirectory of your plugin's workspace. -
Commit the changeset file to your branch/PR.
Once the changeset is merged, it will trigger the release process for the plugin and create a "Version packages ($workspace_name)" PR. Once the PR is merged, a new version of the plugin will be published based on the type of change made.
+Note: It's important to create a changeset for each individual change you make to a plugin. This ensures that the release process is properly managed and that dependencies between plugins are correctly updated.
As 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 newBefore proceeding with migrating a plugin, please review the following sections of the README:
By migrating a plugin to this repository you will need to ensure you can meet certain requirements and adhere to some specific guidelines:
- Agree to publish the plugin to the
@backstage-communitynpm scope. - Adopt the Changesets workflow for releasing new plugin versions.
- Adhere to the repository security process for handling security-related issues.
- Plugins moved to the repository should be licensed under Apache 2.0.
- Prepare your environment by cloning both the repository you are migrating from and the
backstage/community-pluginsrepository:
git clone https://github.com/source-repo/existing-plugins.git
git clone https://github.com/backstage/community-plugins.git-
Identify the plugin(s) you wish to migrate. If you're migrating multiple plugins, is recommended to group the migration of these by workspace.
-
Within the
backstage/community-pluginsrepository create a new branch for your changes:
git checkout -b migrate-workspace-
Create a new workspace in the community plugins repository.
-
Copy the plugin files from the source repository to the
backstage/community-pluginsrepository.
cp -r ../existing-plugins/plugins/plugin-name plugins/-
Ensure all metadata files (
package.json) are updated to reflect the new repository. This includes updating repository URLs, issues URLs, and other references. -
Add maintainers to the
CODEOWNERSfile for the new workspace. -
Create a new pull request from your branch.
-
Update external references to the old plugin location such as documentation to point to the new location in the
backstage/community-pluginsrepository. -
In the original repository, update the plugin to indicate that it has been moved to the
backstage/community-pluginsrepository. You may wish to deprecate the old version on npm.
Backstage 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.