From 278ca801e97cecc75c70beca67bf4297df285339 Mon Sep 17 00:00:00 2001 From: blam Date: Tue, 30 Apr 2024 10:27:51 +0200 Subject: [PATCH 1/3] chore: added some more docs for the repo Signed-off-by: blam --- CONTRIBUTING.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 ++ 2 files changed, 105 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d792e86fa6..c6f6b03937 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,15 @@ If you have questions or feedback regarding Community Plugins, you can visit the - [Contributing to `backstage/community-plugins`](#contributing-to-backstagecommunity-plugins) - [Table of Contents](#table-of-contents) - [Code of Conduct](#code-of-conduct) + - [License](#license) - [Security Issues](#security-issues) + - [Get Started!](#get-started) + - [Coding Guidelines](#coding-guidelines) + - [Versioning](#versioning) + - [Creating Changesets](#creating-changesets) + - [Creating a new Workspace](#creating-a-new-workspace) + - [Creating new plugins or packages in a Workspace](#creating-new-plugins-or-packages-in-a-workspace) + - [Release](#release) - [Developer Certificate of Origin](#developer-certificate-of-origin) ## Code of Conduct @@ -18,10 +26,103 @@ By contributing to Backstage Community Plugins you agree to adhere to the [CNCF [code-of-conduct]: https://github.com/cncf/foundation/blob/main/code-of-conduct.md +## License + +The community plugins repository is under [Apache 2.0](../LICENSE) 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](SECURITY.md). +## Get Started! + +So...feel ready to jump in? Let's do this. 👏🏻 💯 + +### Cloning 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](https://docs.github.com/en/get-started/quickstart/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: + +```bash +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: + +```bash +# 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. + +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 ` 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](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md#creating-changesets) or read a quick summary below. + +## Creating Changesets + +We use [changesets](https://github.com/atlassian/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. + +```bash +cd community-plugins +cd workspaces/linguist +yarn changeset # follow the prompts +``` + +## 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: + +```bash +# 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. + +```bash +cd workspaces/adr +yarn new +``` + ## Developer Certificate of Origin Backstage Community Plugins has adopted a [Developers Certificate of Origin (DCO)](https://developercertificate.org/) - refer to the Backstage [CONTRIBUTING.md#developer-certificate-of-origin](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md#developer-certificate-of-origin) for more information on the DCO and guidance on signing commits. diff --git a/README.md b/README.md index 659a631736..5be0a6583d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # Backstage Community Plugins +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![CNCF Status](https://img.shields.io/badge/cncf%20status-incubation-blue.svg)](https://www.cncf.io/projects) +[![Discord](https://img.shields.io/discord/687207715902193673?logo=discord&label=Discord&color=5865F2&logoColor=white)](https://discord.gg/backstage-687207715902193673) + ## What is the community-plugins repository? The `community-plugins` repository is a place where members of the community can host a plugin or a set of plugins. The goal of community-plugins is to reduce the amount of pull requests and issues from `backstage/backstage`, which has become too big with the time. From 5d1632bf611bbf11782c3b19ed63e1e1677490f1 Mon Sep 17 00:00:00 2001 From: blam Date: Tue, 30 Apr 2024 14:41:54 +0200 Subject: [PATCH 2/3] chore: added some notes about the dev setyup Signed-off-by: blam --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6f6b03937..939bfa702f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,7 +64,7 @@ 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. +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](https://github.com/backstage/backstage/blob/e46d3fe011fe19821b2556f0164442cc0b825363/plugins/auth-backend/dev/index.ts#L4) and [frontend plugin dev](https://github.com/backstage/backstage/blob/e46d3fe011fe19821b2556f0164442cc0b825363/plugins/home/dev/index.tsx) 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`. From eeff0f87d6897c4e8e4c51035aa89bd74df90911 Mon Sep 17 00:00:00 2001 From: blam Date: Tue, 30 Apr 2024 14:50:55 +0200 Subject: [PATCH 3/3] chore: fix Signed-off-by: blam --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 939bfa702f..3763bd15bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,7 +64,7 @@ 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](https://github.com/backstage/backstage/blob/e46d3fe011fe19821b2556f0164442cc0b825363/plugins/auth-backend/dev/index.ts#L4) and [frontend plugin dev](https://github.com/backstage/backstage/blob/e46d3fe011fe19821b2556f0164442cc0b825363/plugins/home/dev/index.tsx) examples. +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](https://github.com/backstage/backstage/blob/e46d3fe011fe19821b2556f0164442cc0b825363/plugins/auth-backend/dev/index.ts) and [frontend plugin dev](https://github.com/backstage/backstage/blob/e46d3fe011fe19821b2556f0164442cc0b825363/plugins/home/dev/index.tsx) 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`.