Skip to content

Latest commit

 

History

History
304 lines (196 loc) · 19.1 KB

CONTRIBUTING.md

File metadata and controls

304 lines (196 loc) · 19.1 KB
Raw

Contributing to backstage/community-plugins

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.

Table of Contents

Code of Conduct

By contributing to Backstage Community Plugins you agree to adhere to the CNCF Code of Conduct.

License

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”.

Security Issues

See SECURITY.

Get Started!

So...feel ready to jump in? Let's do this. 👏🏻 💯

Forking the Repository

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 main

After 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 install

Developing Plugins in Workspaces

Frontend 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.

Coding Guidelines

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.

Versioning

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.

Creating Changesets

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:

  1. 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 adr plugin then you should be on workspaces/adr dir

  2. Run the following command to create a new changeset:

    $ yarn changeset

  3. You will be prompted to select the packages and the type of change you are making.

  4. Enter a short description of the change when prompted. Refer to backstage/backstage CONTRIBUTING.md#writing-changesets for additional guidance on writing changesets.

  5. Review the changeset file that was created. It should be located in the .changeset directory of your plugin's workspace.

  6. 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.

Release

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.

Creating a new Workspace

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-workspace

From 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.

Creating new plugins or packages in a Workspace

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 new

Migrating a plugin

Before 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-community npm scope.
  • Adopt the Changesets workflow for releasing new plugin versions.
  • Adhere to the repository security process for handling security-related issues.
  • Agree to commit to the responsibilities and requirements listed in the Plugin Maintainer's role .
  • Plugins moved to the repository should be licensed under Apache 2.0.

Manual migration steps

  1. Prepare your environment by cloning both the repository you are migrating from and the backstage/community-plugins repository:
git clone https://github.com/source-repo/existing-plugins.git
git clone https://github.com/backstage/community-plugins.git

  1. Identify the plugin(s) you wish to migrate. If you're migrating multiple plugins, is recommended to group the migration of these by workspace.

  2. Within the backstage/community-plugins repository create a new branch for your changes:

git checkout -b migrate-workspace

  1. Create a new workspace in the community plugins repository.

  2. Copy the plugin files from the source repository to the backstage/community-plugins repository.

cp -r ../existing-plugins/plugins/plugin-name plugins/

  1. Ensure all metadata files (package.json) are updated to reflect the new repository. This includes updating repository URLs, issues URLs, and other references.

  2. Add maintainers to the CODEOWNERS file for the new workspace.

Note: The CODEOWNERS file will have errors until the Organization Membership Request for CODEOWNERS has been approved. However, it is still useful to add CODEOWNERS as this point as it provides a documented reference as to who owns/maintains the plugin.

  1. Create a new pull request from your branch.

  2. Update external references to the old plugin location such as documentation to point to the new location in the backstage/community-plugins repository.

  3. In the original repository, update the plugin to indicate that it has been moved to the backstage/community-plugins repository. You may wish to deprecate the old version on npm.

Organization Membership Request for CODEOWNERS

This section outlines the process for plugin maintainers to request organization membership in the Backstage community, which is necessary for efficiently managing CODEOWNERS in this repository.

Plugin maintainers can request organization membership by submitting a request through this link and filling out the provided form. In the request, they should:

  • List the plugins they have contributed and/or maintain within the 'Highlighted Contributions' section.
  • Ping the Community Plugins Area Maintainers for review and support of the request.

As becoming an organization member provides elevated permissions, addition of new organization members follows a vetting process, while hoping not to create unnecessary barriers for new plugin maintainers. The following criteria are often used for the vetting process:

  • Is the individual a member of other teams in Backstage?
  • What is the length and consistency of their involvement with Backstage plugins and/or the Backstage community?
  • Are there other contributors or plugin maintainers who work with the individual and can vouch for them?
  • Do they have an employer with a vested interest in the Backstage community?

The Community Plugins Area Maintainers will review the request. While the request is being processed, plugin maintainers are encouraged to review and approve PRs related to their plugins, even though it will not yet show up as a formal review in the GitHub UI.

Form Details:

  • Name: Organization Membership Request
  • Description: A request to become a Backstage organization member
  • Title: Org Member: <your-github-login>
  • Labels: org-member-request

The form includes fields to confirm adherence to the Code of Conduct, list highlighted contributions, and more. Please ensure you provide:

  1. The plugins you maintain within the community plugins section.
  2. Links to your notable contributions (PRs, issues, etc.).
  3. A list of other plugin maintainers who can vouch for your request.

Once the form is submitted, the plugin maintainers will review your request and provide feedback or support as needed.

Developer Certificate of Origin

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.

API Reports

Backstage uses API Extractor and TSDoc comments to generate API Reports in Markdown format. These reports are what drive the API Reference documentation. What this means is that if you are making changes to the API or adding a new plugin then you will need either generate a new API Report or update an existing API Report. If you don't do this the CI build will fail when you create your Pull Request.

There are two ways you can do this:

  1. You can run yarn build:api-reports from the root of the project and it will go through all of the existing API Reports and update them or create new ones as needed. This may take a while but is generally the best method if you are new to this.
  2. You can run yarn build:api-reports plugins/<your-plugin-with-changes> from the workspace root and it will update the existing API Report or create a new one.

Note: the above commands assume you've run yarn install before hand or recently

Each plugin/package has its own API Report which means you might see more then one file updated or created depending on your changes. These changes will then need to be committed as well.

Submitting a Pull Request

When you've got your contribution working, tested, and committed to your branch it's time to create a Pull Request (PR). If you are unsure how to do this GitHub's Creating a pull request from a fork documentation will help you with that. Once you create your PR you will be presented with a template in the PR's description that looks like this:

## Hey, I just made a Pull Request!

<!-- Please describe what you added, and add a screenshot if possible.
     That makes it easier to understand the change so we can :shipit: faster. -->

#### :heavy_check_mark: Checklist

<!--- Please include the following in your Pull Request when applicable: -->

- [ ] A changeset describing the change and affected packages. ([more info](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md#creating-changesets))
- [ ] Added or updated documentation
- [ ] Tests for new functionality and regression tests for bug fixes
- [ ] Screenshots attached (for UI changes)
- [ ] All your commits have a `Signed-off-by` line in the message. ([more info](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md#developer-certificate-of-origin))

From here all you need to do is fill in the information as requested by the template. Please do not remove this as it helps both you and the reviewers confirm that the various tasks have been completed.

Here are some examples of good PR descriptions:

Review Process

Once you've submitted a Pull Request (PR) the various bots will come out and do their work:

  • assigning reviewers from the various areas impacted by changes in your PR
  • adding labels to help make reviewing PRs easier
  • checking for missing changesets or confirming them
  • checking for commits for their DCO (Developer Certificate of Origin)
  • kick off the various CI builds

Once these have been completed it's just a matter of being patient as the reviewers have time they will begin to review your PR. When the review begins there may be a few layers to this but the general rule is that you need approval from one of the core maintainers and one from the specific area impacted by your PR. You may also have someone from the community review your changes, this can really help speed things up as they may catch some early items making the review for the maintainers simpler. Once you have the two (2) approvals it's ready to be merged, this task is also done by the maintainers.

Review Tips

Here are a few things that can help as you go through the review process:

  • You'll want to make sure all the automated checks are passing as generally the PR won't get a review if something like the CI build is failing
  • PRs get automatically assigned so you don't need to ping people, they will be notified and have a process of their own for this
  • If you are waiting for a review or mid-review and your PR goes stale one of the easiest ways to clear the stale bot is by simply rebasing your PR
  • There are times where you might run into conflict with the yarn.lock during a rebase, to help with that make sure your main branch is up to date and then in your branch run git checkout master yarn.lock from the workspace too and then run yarn install, this will get you a conflict free yarn.lock file you can commit