Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
405 lines (272 loc) · 24.8 KB

CONTRIBUTING.md

File metadata and controls

405 lines (272 loc) · 24.8 KB

Contributing to redhat-developer/rhdh-plugins

The redhat-developer/rhdh-plugins repository is designed as a collaborative space to host and manage plugins developed by Red Hat. 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.

Table of Contents

License

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

Get Started

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:redhat-developer/rhdh-plugins.git
git pull upstream main

After you have cloned the RHDH Plugins repository, you should run the following commands once to set things up for development:

cd rhdh-plugins
yarn install
cd workspaces/noop
yarn install

Developing Plugins in Workspaces

Most 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 some plugins, 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

Both the full Backstage environment and standalone runners are configured on a per-workspace basis. Be sure to check the workspace README.md for specific instructions on setting up the development environment 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 “backstage/community-plugins" 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 scorecard plugin then you should be on workspaces/scorecard 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 rhdh 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.

Important

Please note that plugins with the private property set to 'true' will not be published upon merging the "Version Packages" PR. If you want full autonomy over the release process, you can mark your plugin as private. In this case, the release process will be managed by the plugin maintainer.

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 backstage repository: https://backstage.io/docs/architecture-decisions/adrs-adr011.

You can create a workspace by running the following:

# jump in to the rhdh-plugins repo that you cloned
cd rhdh-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/scorecard
yarn install
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 @red-hat-developer-hub npm 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.

Manual migration steps

  1. Prepare your environment by cloning both the repository you are migrating from and the redhat-developer/rhdh-plugins repository:
git clone https://github.com/source-repo/existing-plugins.git
git clone https://github.com/redhat-developer/rhdh-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 redhat-developer/rhdh-plugins repository create a new branch for your changes:

git checkout -b migrate-workspace
  1. Create a new workspace in the rhdh plugins repository.
yarn create-workspace
  1. Copy the plugin files from the source repository to the redhat-developer/rhdh-plugins repository.
cd your-workspace-name
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 you are a member of the Red Hat Developer GitHub organization. However, it is still useful to add CODEOWNERS at 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 redhat-developer/rhdh-plugins repository.

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

Using the cli to migrate plugins from janus-idp/backstage-plugins

  1. Prepare your environment by cloning a fork of both the janus-idp/backstage-plugins and the backstage/rhdh-plugins repositories

  2. In both repositories, create a new branch:

    • For janus-idp/backstage-plugins:

      git checkout -b "deprecate-workspace-name"

    • For backstage/rhdh-plugins:

      git checkout -b "migrate-workspace-name"

  3. In the backstage/rhdh-plugins repository, execute the janus-plugin migrate command.- Usage:yarn rhdh-cli janus-plugin migrate --monorepo-path [path_to_backstage_plugins]--workspace-name [workspace_name] --branch [branch_name] --maintainers [maintainer1],[maintainer2],[maintainer3],...

    • The path_to_backstage_plugins is the path to the backstage-plugins project where the plugin(s) you want to migrate live.

    • The workspace-name is the name of the workspace you wish to create in the rhdh-plugins project. All plugins in the backstage-plugins that either are exactly or start with @janus-idp/backstage-plugin-[workspace_name] will be migrated to this new workspace.

    • The branch_name is the name of the branch in the backstage-plugins project where the changes to add a deprecate note for the migrated plugins will be made.

    • The maintainers array of arguments is the github usernames of those individuals that should be listed as the maintainers for the migrated plugins. Please separate each maintainer by a comma while supplying this value.

    • example usage:

       yarn rhdh-cli janus-plugin migrate --monorepo-path ../backstage-plugins --workspace-name workspace-name --branch deprecate-workspace-name --maintainers @maintainer1,@maintainer2,@maintainer3

  4. The script will generate changesets in both repositories. Be sure to commit these changes and open pull requests.

Important

This script updates metadata commonly found across all plugins. Please review your migrated plugins to ensure that all references to "janus" have been updated to point to "rhdh-plugins."

  1. If you run into CI issues take a look at this github gist which outlines the process taken to migrate argocd plugins in great detail.

  2. Check if the migrated plugins need to be added to janus-idp/backstage-showcase. If they do, create a wrapper for them following the steps below:

  • In dynamic-plugins> wrappers create a directory, name it based on your plugin (eg: backstage-community-plugin-3scale-backend)
  • Create a src directory within it
  • Add a index.ts file to this src directory and export from the plugin package here. Eg: export * from '@backstage-community/plugin-3scale-backend';
  • In dynamic-plugins> wrappers > backstage-community-plugin-3scale-backend (or whatever you named your wrapper directory), add a package.json file. Add your plugin package in dependencies.
  • run yarn export-dynamic to generate dist-dynamic directory

Next steps

Once PRs are merged in the new repo, you should mark the old plugins deprecated, and delete the content - leaving only a README.md.

Maintenance of older versions

As only a single version will be migrated to the new repo, maintenance of older plugins for previous RHDH releases should continue to be done in the older repo, as the migrated versions will be aligned to newer versions of Backstage and may not be compatible.

API Reports

This repository uses API Extractor and TSDoc comments to generate API Reports in Markdown format, similar to those used in Backstage. If you make changes to the API or add 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 than one file updated or created depending on your changes. These changes will then need to be committed as well.

Submitting a Pull Request for a New Workspace

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.

For new plugins, it is recommended that your initial PR simply creates the workspace for your plugins. In this PR, be sure to add maintainers to the CODEOWNERS file for the new workspace. This will streamline the approval process, and also ensure that you have full autonomy over further development of your plugin.

Please ping @rhdh-cope in #rhdh-plugins-ecosystem on Slack when the PR is ready for review. We will do our best to complete an initial review within 5 working days, and address any subsequent updates within 2 working days. We will not begin this process until the CI is passing or CI failures are explicitly justified.

Checklist to Ensure your Plugin is Ready to Merge

  • Workspace package.json
    • private: true
    • Use the correct repository url
    • Keep workspace-level dependencies minimal
  • Plugin package.json
    • For publishable plugins:
      • Omit private: true
      • Set publishConfig.access to "public"
    • Include a valid backstage config with role, pluginId, and pluginPackages
    • Use the correct repository URL
  • Required files
    • Changeset is present
    • README files with relevant documentation
    • backstage.json specifying a compatible Backstage version
  • Configuration (if applicable)
    • Include config.d.ts at the package level
    • Add proper visibility annotations
  • Ownership
    • Update .github/CODEOWNERS with appropriate maintainers

Plugin Owner Responsibilities

Note

To carry out your responsibilities as a plugin owner, you will need write access to the repository. If you are a plugin owner and do not have write access, please reach out to one of the repository maintainers.

As a plugin owner, you are responsible for the ongoing health and maintenance of your plugin(s) in this repository.

Responsibilities

  • Review, approve, and merge PRs opened against your plugin, including:
  • Keep your workspace(s) up to date with the latest Backstage version supported by RHDH. See Keeping Workspaces Up to Date.
  • Manage security updates and patches: Work with your security team to address vulnerabilities according to SLA and product lifecycle requirements. Since this repository does not maintain release branches, Renovate only opens PRs against the latest code. If your plugin is used in multiple product versions, you are responsible for backporting critical patches.
  • Justify Dependency-Related PR closures: If you choose not to merge a Renovate or dependency-related PR, include a brief explanation when closing it.

Keeping Workspaces Up to Date with Backstage

To keep plugins in the various workspaces up to date with Backstage we have a Version Bump Workflow in place, similar to the one that is used in the backstage/community-plugins repository.

Process

When a Plugin Owner wants to upgrade their workspace(s) to the latest version of Backstage they will simply need to do the following:

  1. Navigate to the Version Bump workflow
  2. On the right hand side click on the "Run workflow" button
  3. In the menu that appears use the following:
    1. For "Use workflow from" use the default "Branch: main"
    2. For "Release Line" use the default "main"
    3. For "Workspace (this much be a JSON array)" you will enter the name(s) of the workspace(s). For example for a single workspace it would look like this: ["bulk-import"] and for multiple workspaces it would look like this: ["lightspeed", "homepage", "extensions"]
    4. For "Specifies the type of version update to apply" use the default "minor"
  4. Now click the "Run workflow" button
  5. The workflow will then run and create a PR to upgrade each of the specified workspaces to the latest main release of Backstage
  6. Review and merge the generated PR(s)

Updating Dependencies with Renovate

This repository uses Renovate to automatically manage dependency updates for your plugins.

Types of PRs

Dependency Updates
  • PRs will be created for dependencies that have patch or minor version updates.
  • Major version updates will require dashboard approval in order to generate a PR. Alternatively, the plugin owner can manually create their own PR to update to a major version.
Security Fixes
  • PRs can also be opened for security alerts. These PRs are distinguishable with a [security]suffix in its title and will also have a security label.

Opt-in to Knip Reports Check

Plugin owners can opt in to Knip reports check in CI by creating a bcp.json file in the root of their workspace (workspaces/${WORKSPACE}/bcp.json) and adding { "knip-reports": true }. This ensures that knip reports in your workspace stay up to date.

Knip is a tool that helps with clean-up and maintenance by identifying unused dependencies within workspaces. Regularly reviewing and addressing these reports can significantly improve code quality and reduce bloat.

Archiving a plugin or workspace

When a plugin is no longer maintained, archive it rather than leaving stale code in the default branch. The archive script records the last published version in .github/archived-plugins.json, documents it in ARCHIVED_WORKSPACES.md, and strips repository configuration that referenced the workspace when you archive an entire workspace. You then remove the workspace or plugin tree in the same PR (or a follow-up). After the PR merges, npm deprecation runs via .github/workflows/deprecate-archived-plugins.yml.

When to archive

Consider archiving when the plugin is unmaintained, has no owner, has unfixable security issues, has been superseded, or cannot be updated for current Backstage versions.

Steps

  1. From the repository root, run the archive script (use a branch based on current main):

    # Entire workspace (default reason: "No longer maintained")
node scripts/archive.js <workspace-name>

# Entire workspace with a custom reason
node scripts/archive.js <workspace-name> "Custom reason"

# Single plugin under workspaces/<workspace>/plugins/ (by plugin directory name or package suffix)
node scripts/archive.js <workspace-name> <plugin-dir-or-package-suffix> "Custom reason"

    The script only considers packages under the @red-hat-developer-hub scope. It updates:

    • .github/archived-plugins.json
    • ARCHIVED_WORKSPACES.md
    • .github/CODEOWNERS (full workspace only — removes the /workspaces/<name> line)
    • .github/renovate.json and .github/renovate-presets/workspace/rhdh-<workspace>-presets.json (full workspace only, when present)

    It does not delete source directories; do that in the next step.

  2. Dry-run npm deprecation (optional):

    ./scripts/ci/deprecate-archived-plugins.sh --dry-run

  3. Delete the workspace or plugin directory from the repository (workspaces/<name> for a full workspace, or workspaces/<workspace>/plugins/<plugin> when archiving specific plugins). Update any documentation that referenced the removed code.

  4. Run yarn install at the repository root if your tooling reports workspace or lockfile issues.

  5. Open a pull request including the script output and the deletion. Changes to .github/archived-plugins.json are sensitive because they drive automated npm deprecation after merge; ensure the usual repository reviewers (see .github/CODEOWNERS) approve the PR.

  6. After the PR merges, confirm the Deprecate Archived Plugins workflow ran successfully for the updated .github/archived-plugins.json.