From 2b8804f8d2c8b28b09096bfa399e9fb27a276b33 Mon Sep 17 00:00:00 2001 From: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Date: Thu, 31 Aug 2023 11:07:52 -0500 Subject: [PATCH 1/7] Refactored contributors guide Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> --- docs/getting-started/contributors.md | 206 ++++++++++++++++++++++----- 1 file changed, 170 insertions(+), 36 deletions(-) diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md index b6a12be013..c58bf65c34 100644 --- a/docs/getting-started/contributors.md +++ b/docs/getting-started/contributors.md @@ -11,12 +11,9 @@ repository. ## 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 or you can -grab the one for the origin like so: - -```bash -git clone git@github.com:backstage/backstage --depth 1 -``` +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: @@ -29,10 +26,10 @@ After you have cloned the Backstage repository, you should run the following commands once to set things up for development: ```bash -$ cd backstage # change to root directory of project +cd backstage # change to root directory of project -$ yarn install # fetch dependency packages - may take a while -$ yarn tsc # does a first run of type generation and checks +yarn install # fetch dependency packages - may take a while +yarn tsc # does a first run of type generation and checks ``` ## Serving the Example App @@ -41,7 +38,7 @@ Open a terminal window and start the web app by using the following command from the project root. Make sure you have run the above mentioned commands first. ```bash -$ yarn dev +yarn dev ``` This is going to start two things, the frontend (:3000) and the backend (:7007). @@ -78,7 +75,19 @@ serves the react app ([0]) and the backend ([1]); Visit http://localhost:3000 and you should see the bleeding edge of Backstage ready for contributions! -## Editor +## 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. + +A consistent coding style is included via [EditorConfig](https://editorconfig.org/) with the file [`.editorconfig`](.editorconfig) at the root of the repo. Depending on your editor of choice, it will either support it out of the box or you can [download a plugin](https://editorconfig.org/#download) for the config to be applied. + +If you're contributing to the backend or CLI tooling, be mindful of cross-platform support. [This](https://shapeshed.com/writing-cross-platform-node/) blog post is a good guide of what to keep in mind when writing cross-platform NodeJS. + +Also be sure to skim through our [ADRs](docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for. + +If there are any updates in `markdown` file please make sure to run `yarn run lint:docs`. Though it is checked on `lint-staged`. It is required to install [vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command. + +### Editor The Backstage development environment does not require any specific editor, but it is intended to be used with one that has built-in linting and type-checking. @@ -92,7 +101,7 @@ There are many commands to be found in the root [package.json](https://github.com/backstage/backstage/blob/master/package.json), here are some useful ones: -```python +```shell yarn start # Start serving the example app, use --check to include type checks and linting yarn storybook # Start local storybook, useful for working on components in @backstage/core-components @@ -104,6 +113,7 @@ yarn tsc:full # Run full type checking, for example without skipLibCheck, use in yarn build:backend # Build the backend package, depends on tsc yarn build:all # Build published versions of packages, depends on tsc +yarn build:api-reports # Build API Reports used for documentation yarn lint # lint packages that have changed since later commit on origin/master yarn lint:all # lint all packages @@ -142,7 +152,29 @@ default app configs. You can learn more about the local configuration in [Static Configuration in Backstage](../conf/) section. -## Writing changesets +## 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. + +### When to use a changeset? + +Any time a patch, minor, or major change aligning to [Semantic Versioning](https://semver.org) is made to any published package in `packages/` or `plugins/`, a changeset should be used. It helps to align your change to the [Backstage package versioning policy](https://backstage.io/docs/overview/versioning-policy#package-versioning-policy) for the package you are changing, for example, when to provide additional clarity on deprecation or impacting changes which will then be included into CHANGELOGs. + +In general, changesets are only needed for changes to packages within `packages/` or `plugins/` directories, and only for the packages that are not marked as `private`. Changesets are also not needed for changes that do not affect the published version of each package, for example changes to tests or in-line source code comments. + +Changesets **are** needed for new packages, as that is what triggers the package to be part of the next release. + +### How to create a changeset + +1. Run `yarn changeset` from the root of the repo +2. Select which packages you want to include a changeset for +3. Select impact of the change you're introducing. If the package you are changing is at version `0.x`, use `minor` for breaking changes and `patch` otherwise. If the package is at `1.0.0` or higher, use `major` for breaking changes, `minor` for backwards compatible API changes, and `patch` otherwise. See the [Semantic Versioning specification](https://semver.org/#semantic-versioning-specification-semver) for more details. +4. Explain your changes in the generated changeset. See [examples of well written changesets](#writing-changesets). +5. Add generated changeset to Git +6. Push the commit with your changeset to the branch associated with your PR +7. Accept our gratitude for making the release process easier on the maintainers + +### Writing changesets Changesets are an important part of the development process. They are used to generate Changelog entries for all changes to the project. Ultimately they are @@ -156,16 +188,17 @@ Here are some important do's and don'ts when writing changesets: #### Bad -``` +```md --- '@backstage/catalog': patch --- + Fixed table layout ``` #### Good -``` +```md --- '@backstage/catalog': patch --- @@ -177,7 +210,7 @@ Fixed bug in EntityTable component where table layout did not readjust properly #### Bad -``` +```md --- '@backstage/catalog': minor --- @@ -187,7 +220,7 @@ getEntity is now a function that returns a Promise. #### Good -``` +```md --- '@backstage/catalog': minor --- @@ -199,7 +232,7 @@ getEntity is now a function that returns a Promise. #### Bad -``` +```md --- '@backstage/catalog': patch --- @@ -209,24 +242,125 @@ getEntity is now a function that returns a Promise. #### Good - --- - '@backstage/catalog': patch - --- +````md +--- +'@backstage/catalog': patch +--- - **BREAKING** The catalog createRouter now requires that a `FluxCapacitor` is - passed to the router. +**BREAKING** The catalog createRouter now requires that a `FluxCapacitor` is +passed to the router. - These changes are **required** to `packages/backend/src/plugins/catalog.ts` +These changes are **required** to `packages/backend/src/plugins/catalog.ts` - ```diff - + import { FluxCapacitor } from '@backstage/time'; - + const fluxCapacitor = new FluxCapacitor(); - return await createRouter({ - entitiesCatalog, - locationAnalyzer, - locationService, - + fluxCapacitor, - logger: env.logger, - config: env.config, - }); - ``` +```diff ++ import { FluxCapacitor } from '@backstage/time'; ++ const fluxCapacitor = new FluxCapacitor(); + return await createRouter({ + entitiesCatalog, + locationAnalyzer, + locationService, ++ fluxCapacitor, + logger: env.logger, + config: env.config, + }); +``` +```` + +## Developer Certificate of Origin + +As with other CNCF projects, Backstage has adopted a [Developers Certificate of Origin (DCO)](https://developercertificate.org/). A DCO is a lightweight way for a developer to certify that they wrote or otherwise have the right to submit code or documentation to a project. + +To certify the code you submit to the repository you'll need to add a `Signed-off-by` line to your commits. + +`$ git commit -s -m 'Awesome commit message'` + +Which will look something like the following in the repo; + +```text +Awesome commit message + +Signed-off-by: Jane Smith +``` + +- In case you forgot to add it to the most recent commit, use `git commit --amend --signoff` +- In case you forgot to add it to the last N commits in your branch, use `git rebase --signoff HEAD~N` and replace N with the number of new commits you created in your branch. +- If you have a very deep branch with a lot of commits, run `git rebase -i --signoff $(git merge-base -a master HEAD)`, double check to make sense of the commits (keep all lines as `pick`) and save and close the editor. This should bulk sign all the commits in your PR. Do be careful though. If you have a complex flow with a lot of branching and re-merging of work branches and stuff, merge-base may not be the right solution for you. + +Note: If you have already pushed your branch to a remote, you might have to force push: `git push -f` after the rebase. + +### Using GitHub Desktop? + +If you are using the GitHub Desktop client, you need to manually add the `Signed-off-by` line to the Description field on the Changes tab before committing: + +```text +Awesome description (commit message) + +Signed-off-by: Jane Smith +``` + +In case you forgot to add the line to your most recent commit, you can amend the commit message from the History tab before pushing your branch (GitHub Desktop 2.9 or later). + +## API Reports + +Backstage uses [API Extractor](https://api-extractor.com/) and TSDoc comments to generate API Reports in Markdown format. These reports are what drive the [API Reference documentation](https://backstage.io/docs/reference/). 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/` from the 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/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: + +```md +## Hey, I just made a Pull Request! + + + +#### :heavy_check_mark: Checklist + + + +- [ ] 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 of 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 `master` branch is up to date and then in your branch run `git checkout master yarn.lock` and then run `yarn install`, this will get you a conflict free `yarn.lock` file you can commit +- If Vale finds issues with your documentation but it's a code reference you can fix it by putting backticks (`) around it. Now if it is a special word or maybe a name there are two ways you can fix that by adding it to the list of accepted words in the [accept.txt file](https://github.com/backstage/backstage/blob/master/.github/vale/Vocab/Backstage/accept.txt) and them committing that change From a75e4b909283d8830f040aebc7f5afc66ef19040 Mon Sep 17 00:00:00 2001 From: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Date: Thu, 31 Aug 2023 11:21:39 -0500 Subject: [PATCH 2/7] Added terms to accept Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> --- .github/vale/Vocab/Backstage/accept.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/vale/Vocab/Backstage/accept.txt b/.github/vale/Vocab/Backstage/accept.txt index 9fa7af5585..0229ed8e12 100644 --- a/.github/vale/Vocab/Backstage/accept.txt +++ b/.github/vale/Vocab/Backstage/accept.txt @@ -448,3 +448,5 @@ zoomable zsh Pulumi Lightsail +PR +rebasing \ No newline at end of file From 12d74fb108e52463fddac6dc3811013f32c2cb47 Mon Sep 17 00:00:00 2001 From: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Date: Fri, 1 Sep 2023 06:49:03 -0500 Subject: [PATCH 3/7] Fixed broken links Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> --- docs/getting-started/contributors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md index c58bf65c34..ece4e7b13f 100644 --- a/docs/getting-started/contributors.md +++ b/docs/getting-started/contributors.md @@ -79,11 +79,11 @@ ready for contributions! 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. -A consistent coding style is included via [EditorConfig](https://editorconfig.org/) with the file [`.editorconfig`](.editorconfig) at the root of the repo. Depending on your editor of choice, it will either support it out of the box or you can [download a plugin](https://editorconfig.org/#download) for the config to be applied. +A consistent coding style is included via [EditorConfig](https://editorconfig.org/) with the file [`.editorconfig`](https://github.com/backstage/backstage/blob/master/.editorconfig) at the root of the repo. Depending on your editor of choice, it will either support it out of the box or you can [download a plugin](https://editorconfig.org/#download) for the config to be applied. If you're contributing to the backend or CLI tooling, be mindful of cross-platform support. [This](https://shapeshed.com/writing-cross-platform-node/) blog post is a good guide of what to keep in mind when writing cross-platform NodeJS. -Also be sure to skim through our [ADRs](docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for. +Also be sure to skim through our [ADRs](../architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](../architecture-decisions/adr006-avoid-react-fc.md) is one to look out for. If there are any updates in `markdown` file please make sure to run `yarn run lint:docs`. Though it is checked on `lint-staged`. It is required to install [vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command. From 6a9950ca2290a72821c0659199bbc04b838732c1 Mon Sep 17 00:00:00 2001 From: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Date: Fri, 1 Sep 2023 06:58:30 -0500 Subject: [PATCH 4/7] Updated based on feedback Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> --- docs/getting-started/contributors.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md index ece4e7b13f..8ef0fec9fc 100644 --- a/docs/getting-started/contributors.md +++ b/docs/getting-started/contributors.md @@ -72,7 +72,7 @@ $ backstage-cli backend:dev You'll see how you get both logs for the frontend `webpack-dev-server` which serves the react app ([0]) and the backend ([1]); -Visit http://localhost:3000 and you should see the bleeding edge of Backstage +Visit and you should see the bleeding edge of Backstage ready for contributions! ## Coding Guidelines @@ -85,7 +85,7 @@ If you're contributing to the backend or CLI tooling, be mindful of cross-platfo Also be sure to skim through our [ADRs](../architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](../architecture-decisions/adr006-avoid-react-fc.md) is one to look out for. -If there are any updates in `markdown` file please make sure to run `yarn run lint:docs`. Though it is checked on `lint-staged`. It is required to install [vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command. +If there are any updates in any Markdown files please make sure to run `yarn run lint:docs`. (Though it is also checked by `lint-staged` when you commit via [Husky](https://github.com/typicode/husky).) It is required to install [Vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command. ### Editor @@ -117,6 +117,7 @@ yarn build:api-reports # Build API Reports used for documentation yarn lint # lint packages that have changed since later commit on origin/master yarn lint:all # lint all packages +yarn lind:docs # lint all the Markdown files yarn lint:type-deps # verify that @types/* dependencies are placed correctly in packages yarn test # test packages that have changed since later commit on origin/master @@ -307,7 +308,7 @@ Backstage uses [API Extractor](https://api-extractor.com/) and TSDoc comments to 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/` from the root and it will update the existing API Report or create a new one +2. You can run `yarn build:api-reports plugins/` from the 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 From 444aa3b4caf5b8dd7d5a4c7e33f70680f9af2a6a Mon Sep 17 00:00:00 2001 From: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Date: Fri, 8 Sep 2023 13:47:30 -0500 Subject: [PATCH 5/7] Consolidated into CONTRIBUTING.md Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> --- CONTRIBUTING.md | 318 +++++++++++++++++++--- docs/getting-started/contributors.md | 367 -------------------------- docs/getting-started/create-an-app.md | 2 +- microsite/docusaurus.config.js | 4 + 4 files changed, 292 insertions(+), 399 deletions(-) delete mode 100644 docs/getting-started/contributors.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ed1baa133a..6c645ab524 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,11 +10,83 @@ Backstage is released under the Apache 2.0 License, and original creations contr You can find out more about the types of contributions over at [getting involved](https://backstage.io/docs/getting-started/getting-involved)! +If you need help, just jump into our [Discord chatroom](https://discord.gg/backstage-687207715902193673). + +## Code of Conduct + +This project adheres to the [CNCF Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code. + +[code-of-conduct]: https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md + +## Security Issues? + +See [SECURITY](SECURITY.md). + +## Accessibility + +We encourage you to catch any accessibility issues already in the development phase of new features to Backstage, see our [Accessibility documentation](https://backstage.io/docs/accessibility/) for more details. + ## Get Started! So...feel ready to jump in? Let's do this. 👏🏻💯 -Start by reading our [Getting Started for Contributors](https://backstage.io/docs/getting-started/contributors) page to get yourself setup with a fresh copy of Backstage ready for your contributions. If you need help, just jump into our [Discord chatroom](https://discord.gg/backstage-687207715902193673). +### 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/backstage +git pull upstream master +``` + +After you have cloned the Backstage repository, you should run the following commands once to set things up for development: + +```bash +cd backstage # change to root directory of project + +yarn install # fetch dependency packages - may take a while +yarn tsc # does a first run of type generation and checks +``` + +### Serving the Example App + +Open a terminal window and start the web app by using the following command from the project root. Make sure you have run the above mentioned commands first. + +```bash +yarn dev +``` + +This is going to start two things, the frontend (:3000) and the backend (:7007). + +This should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal. + +By default, Backstage will start on port 3000, however you can override this by setting an environment variable `PORT` on your local machine. e.g. `export PORT=8080` then running `yarn start`. Or `PORT=8080 yarn start`. + +Once successfully started, you should see the following message in your terminal window: + +```sh +$ concurrently "yarn start" "yarn start-backend" +$ yarn workspace example-app start +$ yarn workspace example-backend start +$ backstage-cli app:serve +$ backstage-cli backend:dev +[0] Loaded config from app-config.yaml +[1] Build succeeded +[0] ℹ ｢wds｣: Project is running at http://localhost:3000/ +[0] ℹ ｢wds｣: webpack output is served from / +[0] ℹ ｢wds｣: Content not from webpack is served from $BACKSTAGE_DIR/packages/app/public +[0] ℹ ｢wds｣: 404s will fallback to /index.html +[0] ℹ ｢wdm｣: wait until bundle finished: / +[1] 2021-02-12T20:58:17.614Z backstage info Loaded config from app-config.yaml +``` + +You'll see how you get both logs for the frontend `webpack-dev-server` which serves the react app ([0]) and the backend ([1]); + +Visit and you should see the bleeding edge of Backstage ready for contributions! + +If you want to get a better understanding of the layout of the repo not that you have a local copy running feel free to review the [Backstage Project Structure](https://backstage.io/docs/getting-started/project-structure) documentation. ## Coding Guidelines @@ -28,6 +100,163 @@ Also be sure to skim through our [ADRs](docs/architecture-decisions) to see if t If there are any updates in `markdown` file please make sure to run `yarn run lint:docs`. Though it is checked on `lint-staged`. It is required to install [vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command. +### Editor + +The Backstage development environment does not require any specific editor, but it is intended to be used with one that has built-in linting and type-checking. The development server does not include any checks by default, but they can be enabled using the `--check` flag. Note that using the flag may consume more system resources and slow things down. + +## Package Scripts + +There are many commands to be found in the root [package.json](https://github.com/backstage/backstage/blob/master/package.json), here are some useful ones: + +```shell +yarn start # Start serving the example app, use --check to include type checks and linting + +yarn storybook # Start local storybook, useful for working on components in @backstage/core-components + +yarn workspace @backstage/plugin-api-docs start # Serve api-docs plugin only, also supports --check + +yarn tsc # Run typecheck, use --watch for watch mode +yarn tsc:full # Run full type checking, for example without skipLibCheck, use in CI + +yarn build:backend # Build the backend package, depends on tsc +yarn build:all # Build published versions of packages, depends on tsc +yarn build:api-reports # Build API Reports used for documentation + +yarn lint # lint packages that have changed since later commit on origin/master +yarn lint:all # lint all packages +yarn lind:docs # lint all the Markdown files +yarn lint:type-deps # verify that @types/* dependencies are placed correctly in packages + +yarn test # test packages that have changed since later commit on origin/master +yarn test:all # test all packages + +yarn clean # Remove all output folders and @backstage/cli cache + +yarn diff # Make sure all plugins are up to date with the latest plugin template + +yarn new # Create a new module +``` + +> See [package.json](https://github.com/backstage/backstage/blob/master/package.json) for other yarn commands/options. + +## Local configuration + +Backstage allows you to specify the configuration used while running the application on your computer. Local configuration is read from `app-config.local.yaml`. This file is ignored by Git, which means that you can safely use it to reference secrets like GitHub tokens without worrying about these secrets, inadvertently ending up in the Git repository. You do not need to copy everything from the default config to the local config. The `app-config.local.yaml` file will be merged with `app-config.yaml` and overwrite the default app configs. + +> NOTE: If you want to add your own configuration values to access in the frontend you also need to mark those values as visible using configuration schema, either in the app or in your own plugin. For more information, see [Defining Configuration](https://backstage.io/docs/conf/defining/). + +You can learn more about the local configuration in the [Static Configuration in Backstage](https://backstage.io/docs/conf/) section. + +## 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. + +### When to use a changeset? + +Any time a patch, minor, or major change aligning to [Semantic Versioning](https://semver.org) is made to any published package in `packages/` or `plugins/`, a changeset should be used. It helps to align your change to the [Backstage package versioning policy](https://backstage.io/docs/overview/versioning-policy#package-versioning-policy) for the package you are changing, for example, when to provide additional clarity on deprecation or impacting changes which will then be included into CHANGELOGs. + +In general, changesets are only needed for changes to packages within `packages/` or `plugins/` directories, and only for the packages that are not marked as `private`. Changesets are also not needed for changes that do not affect the published version of each package, for example changes to tests or in-line source code comments. + +Changesets **are** needed for new packages, as that is what triggers the package to be part of the next release. They are also needed for changes to `README.md` files so that the updates are reflected on the NPM page for the changed package. + +### How to create a changeset + +1. Run `yarn changeset` from the root of the repo +2. Select which packages you want to include a changeset for +3. Select impact of the change you're introducing. If the package you are changing is at version `0.x`, use `minor` for breaking changes and `patch` otherwise. If the package is at `1.0.0` or higher, use `major` for breaking changes, `minor` for backwards compatible API changes, and `patch` otherwise. See the [Semantic Versioning specification](https://semver.org/#semantic-versioning-specification-semver) for more details. +4. Explain your changes in the generated changeset. See [examples of well written changesets](#writing-changesets). +5. Add generated changeset to Git +6. Push the commit with your changeset to the branch associated with your PR +7. Accept our gratitude for making the release process easier on the maintainers + +### Writing changesets + +Changesets are an important part of the development process. They are used to generate Changelog entries for all changes to the project. Ultimately they are read by the end users to learn about important changes and fixes to the project. Some of these fixes might require manual intervention from users so it's important to write changesets that users understand and can take action on. + +Here are some important do's and don'ts when writing changesets: + +### Changeset should give a clear description to what has changed + +#### Bad + +```md +--- +'@backstage/catalog': patch +--- + +Fixed table layout +``` + +#### Good + +```md +--- +'@backstage/catalog': patch +--- + +Fixed bug in EntityTable component where table layout did not readjust properly below 1080x768 pixels. +``` + +### Breaking changes not caught by the type checker should be clearly marked with bold **BREAKING** text + +#### Bad + +```md +--- +'@backstage/catalog': minor +--- + +getEntity is now a function that returns a Promise. +``` + +#### Good + +```md +--- +'@backstage/catalog': minor +--- + +**BREAKING** The getEntity function now returns a Promise and **must** be awaited from now on. +``` + +### Changes to code should include a diff of the files that need updating + +#### Bad + +```md +--- +'@backstage/catalog': patch +--- + +**BREAKING** The catalogEngine now requires a flux capacitor to be passed. +``` + +#### Good + +````md +--- +'@backstage/catalog': patch +--- + +**BREAKING** The catalog createRouter now requires that a `FluxCapacitor` is +passed to the router. + +These changes are **required** to `packages/backend/src/plugins/catalog.ts` + +```diff ++ import { FluxCapacitor } from '@backstage/time'; ++ const fluxCapacitor = new FluxCapacitor(); + return await createRouter({ + entitiesCatalog, + locationAnalyzer, + locationService, ++ fluxCapacitor, + logger: env.logger, + config: env.config, + }); +``` +```` + ## Developer Certificate of Origin As with other CNCF projects, Backstage has adopted a [Developers Certificate of Origin (DCO)](https://developercertificate.org/). A DCO is a lightweight way for a developer to certify that they wrote or otherwise have the right to submit code or documentation to a project. @@ -62,44 +291,71 @@ Signed-off-by: Jane Smith In case you forgot to add the line to your most recent commit, you can amend the commit message from the History tab before pushing your branch (GitHub Desktop 2.9 or later). -## Creating Changesets +## API Reports -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. +Backstage uses [API Extractor](https://api-extractor.com/) and TSDoc comments to generate API Reports in Markdown format. These reports are what drive the [API Reference documentation](https://backstage.io/docs/reference/). 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. -### When to use a changeset? +There are two ways you can do this: -Any time a patch, minor, or major change aligning to [Semantic Versioning](https://semver.org) is made to any published package in `packages/` or `plugins/`, a changeset should be used. It helps to align your change to the [Backstage package versioning policy](https://backstage.io/docs/overview/versioning-policy#package-versioning-policy) for the package you are changing, for example, when to provide additional clarity on deprecation or impacting changes which will then be included into CHANGELOGs. +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/` from the root and it will update the existing API Report or create a new one. -In general, changesets are only needed for changes to packages within `packages/` or `plugins/` directories, and only for the packages that are not marked as `private`. Changesets are also not needed for changes that do not affect the published version of each package, for example changes to tests or in-line source code comments. +> Note: the above commands assume you've run `yarn install` before hand or recently -Changesets **are** needed for new packages, as that is what triggers the package to be part of the next release. +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. -### How to create a changeset +## Submitting a Pull Request -1. Run `yarn changeset` -2. Select which packages you want to include a changeset for -3. Select impact of the change you're introducing. If the package you are changing is at version `0.x`, use `minor` for breaking changes and `patch` otherwise. If the package is at `1.0.0` or higher, use `major` for breaking changes, `minor` for backwards compatible API changes, and `patch` otherwise. See the [Semantic Versioning specification](https://semver.org/#semantic-versioning-specification-semver) for more details. -4. Explain your changes in the generated changeset. See [examples of well written changesets](https://backstage.io/docs/getting-started/contributors#writing-changesets). -5. Add generated changeset to Git -6. Push the commit with your changeset to the branch associated with your PR -7. Accept our gratitude for making the release process easier on the maintainers +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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/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: -For more information, check out [adding a changeset](https://github.com/atlassian/changesets/blob/master/docs/adding-a-changeset.md) documentation in the changesets repository. +```md +## Hey, I just made a Pull Request! -## Merging to Master + + +#### :heavy_check_mark: Checklist + + + +- [ ] 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 of 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 `master` branch is up to date and then in your branch run `git checkout master yarn.lock` and then run `yarn install`, this will get you a conflict free `yarn.lock` file you can commit +- If Vale finds issues with your documentation but it's a code reference you can fix it by putting backticks (`) around it. Now if it is a special word or maybe a name there are two ways you can fix that by adding it to the list of accepted words in the [accept.txt file](https://github.com/backstage/backstage/blob/master/.github/vale/Vocab/Backstage/accept.txt) and them committing that change + +### Merging to Master For those contributors who have earned write access to the repository, when a pull request is approved, in general we prefer the author of the PR to perform the merge themselves. This allows them to own accountability for the change and they likely know best how or when to address pending fixes or additional follow-ups. In this way, we all help contribute to the project's successful outcomes. - -## Code of Conduct - -This project adheres to the [CNCF Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code. - -[code-of-conduct]: https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md - -## Security Issues? - -See [SECURITY](SECURITY.md). - -## Accessibility - -We encourage you to catch any accessibility issues already in the development phase of new features to Backstage, see our [Accessibility documentation](./docs/accessibility/index.md) for more details. diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md deleted file mode 100644 index 8ef0fec9fc..0000000000 --- a/docs/getting-started/contributors.md +++ /dev/null @@ -1,367 +0,0 @@ ---- -id: contributors -title: Contributors -# prettier-ignore -description: Documentation on how to get set up for doing development on the Backstage repository ---- - -This section describes how to get set up for doing development on the Backstage -repository. - -## 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/backstage -git pull upstream master -``` - -After you have cloned the Backstage repository, you should run the following -commands once to set things up for development: - -```bash -cd backstage # change to root directory of project - -yarn install # fetch dependency packages - may take a while -yarn tsc # does a first run of type generation and checks -``` - -## Serving the Example App - -Open a terminal window and start the web app by using the following command from -the project root. Make sure you have run the above mentioned commands first. - -```bash -yarn dev -``` - -This is going to start two things, the frontend (:3000) and the backend (:7007). - -This should open a local instance of Backstage in your browser, otherwise open -one of the URLs printed in the terminal. - -By default, Backstage will start on port 3000, however you can override this by -setting an environment variable `PORT` on your local machine. e.g. -`export PORT=8080` then running `yarn start`. Or `PORT=8080 yarn start`. - -Once successfully started, you should see the following message in your terminal -window: - -```sh -$ concurrently "yarn start" "yarn start-backend" -$ yarn workspace example-app start -$ yarn workspace example-backend start -$ backstage-cli app:serve -$ backstage-cli backend:dev -[0] Loaded config from app-config.yaml -[1] Build succeeded -[0] ℹ ｢wds｣: Project is running at http://localhost:3000/ -[0] ℹ ｢wds｣: webpack output is served from / -[0] ℹ ｢wds｣: Content not from webpack is served from $BACKSTAGE_DIR/packages/app/public -[0] ℹ ｢wds｣: 404s will fallback to /index.html -[0] ℹ ｢wdm｣: wait until bundle finished: / -[1] 2021-02-12T20:58:17.614Z backstage info Loaded config from app-config.yaml -``` - -You'll see how you get both logs for the frontend `webpack-dev-server` which -serves the react app ([0]) and the backend ([1]); - -Visit and you should see the bleeding edge of Backstage -ready for contributions! - -## 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. - -A consistent coding style is included via [EditorConfig](https://editorconfig.org/) with the file [`.editorconfig`](https://github.com/backstage/backstage/blob/master/.editorconfig) at the root of the repo. Depending on your editor of choice, it will either support it out of the box or you can [download a plugin](https://editorconfig.org/#download) for the config to be applied. - -If you're contributing to the backend or CLI tooling, be mindful of cross-platform support. [This](https://shapeshed.com/writing-cross-platform-node/) blog post is a good guide of what to keep in mind when writing cross-platform NodeJS. - -Also be sure to skim through our [ADRs](../architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](../architecture-decisions/adr006-avoid-react-fc.md) is one to look out for. - -If there are any updates in any Markdown files please make sure to run `yarn run lint:docs`. (Though it is also checked by `lint-staged` when you commit via [Husky](https://github.com/typicode/husky).) It is required to install [Vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command. - -### Editor - -The Backstage development environment does not require any specific editor, but -it is intended to be used with one that has built-in linting and type-checking. -The development server does not include any checks by default, but they can be -enabled using the `--check` flag. Note that using the flag may consume more -system resources and slow things down. - -## Package Scripts - -There are many commands to be found in the root -[package.json](https://github.com/backstage/backstage/blob/master/package.json), -here are some useful ones: - -```shell -yarn start # Start serving the example app, use --check to include type checks and linting - -yarn storybook # Start local storybook, useful for working on components in @backstage/core-components - -yarn workspace @backstage/plugin-api-docs start # Serve api-docs plugin only, also supports --check - -yarn tsc # Run typecheck, use --watch for watch mode -yarn tsc:full # Run full type checking, for example without skipLibCheck, use in CI - -yarn build:backend # Build the backend package, depends on tsc -yarn build:all # Build published versions of packages, depends on tsc -yarn build:api-reports # Build API Reports used for documentation - -yarn lint # lint packages that have changed since later commit on origin/master -yarn lint:all # lint all packages -yarn lind:docs # lint all the Markdown files -yarn lint:type-deps # verify that @types/* dependencies are placed correctly in packages - -yarn test # test packages that have changed since later commit on origin/master -yarn test:all # test all packages - -yarn clean # Remove all output folders and @backstage/cli cache - -yarn diff # Make sure all plugins are up to date with the latest plugin template - -yarn new # Create a new module -``` - -> See -> [package.json](https://github.com/backstage/backstage/blob/master/package.json) -> for other yarn commands/options. - -## Local configuration - -Backstage allows you to specify the configuration used while running the -application on your computer. Local configuration is read from -`app-config.local.yaml`. This file is ignored by Git, which means that you can -safely use it to reference secrets like GitHub tokens without worrying about -these secrets, inadvertently ending up in the Git repository. You do not need to -copy everything from the default config to the local config. -`app-config.local.yaml` will be merged with `app-config.yaml` and overwrite the -default app configs. - -> NOTE: If you want to add your own configuration values to access in the -> frontend you also need to mark those values as visible using configuration -> schema, either in the app or in your own plugin. For more information, see -> [Defining Configuration](../conf/defining.md). - -You can learn more about the local configuration in -[Static Configuration in Backstage](../conf/) section. - -## 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. - -### When to use a changeset? - -Any time a patch, minor, or major change aligning to [Semantic Versioning](https://semver.org) is made to any published package in `packages/` or `plugins/`, a changeset should be used. It helps to align your change to the [Backstage package versioning policy](https://backstage.io/docs/overview/versioning-policy#package-versioning-policy) for the package you are changing, for example, when to provide additional clarity on deprecation or impacting changes which will then be included into CHANGELOGs. - -In general, changesets are only needed for changes to packages within `packages/` or `plugins/` directories, and only for the packages that are not marked as `private`. Changesets are also not needed for changes that do not affect the published version of each package, for example changes to tests or in-line source code comments. - -Changesets **are** needed for new packages, as that is what triggers the package to be part of the next release. - -### How to create a changeset - -1. Run `yarn changeset` from the root of the repo -2. Select which packages you want to include a changeset for -3. Select impact of the change you're introducing. If the package you are changing is at version `0.x`, use `minor` for breaking changes and `patch` otherwise. If the package is at `1.0.0` or higher, use `major` for breaking changes, `minor` for backwards compatible API changes, and `patch` otherwise. See the [Semantic Versioning specification](https://semver.org/#semantic-versioning-specification-semver) for more details. -4. Explain your changes in the generated changeset. See [examples of well written changesets](#writing-changesets). -5. Add generated changeset to Git -6. Push the commit with your changeset to the branch associated with your PR -7. Accept our gratitude for making the release process easier on the maintainers - -### Writing changesets - -Changesets are an important part of the development process. They are used to -generate Changelog entries for all changes to the project. Ultimately they are -read by the end users to learn about important changes and fixes to the project. -Some of these fixes might require manual intervention from users so it's -important to write changesets that users understand and can take action on. - -Here are some important do's and don'ts when writing changesets: - -### Changeset should give a clear description to what has changed - -#### Bad - -```md ---- -'@backstage/catalog': patch ---- - -Fixed table layout -``` - -#### Good - -```md ---- -'@backstage/catalog': patch ---- - -Fixed bug in EntityTable component where table layout did not readjust properly below 1080x768 pixels. -``` - -### Breaking changes not caught by the type checker should be clearly marked with bold **BREAKING** text - -#### Bad - -```md ---- -'@backstage/catalog': minor ---- - -getEntity is now a function that returns a Promise. -``` - -#### Good - -```md ---- -'@backstage/catalog': minor ---- - -**BREAKING** The getEntity function now returns a Promise and **must** be awaited from now on. -``` - -### Changes to code should include a diff of the files that need updating - -#### Bad - -```md ---- -'@backstage/catalog': patch ---- - -**BREAKING** The catalogEngine now requires a flux capacitor to be passed. -``` - -#### Good - -````md ---- -'@backstage/catalog': patch ---- - -**BREAKING** The catalog createRouter now requires that a `FluxCapacitor` is -passed to the router. - -These changes are **required** to `packages/backend/src/plugins/catalog.ts` - -```diff -+ import { FluxCapacitor } from '@backstage/time'; -+ const fluxCapacitor = new FluxCapacitor(); - return await createRouter({ - entitiesCatalog, - locationAnalyzer, - locationService, -+ fluxCapacitor, - logger: env.logger, - config: env.config, - }); -``` -```` - -## Developer Certificate of Origin - -As with other CNCF projects, Backstage has adopted a [Developers Certificate of Origin (DCO)](https://developercertificate.org/). A DCO is a lightweight way for a developer to certify that they wrote or otherwise have the right to submit code or documentation to a project. - -To certify the code you submit to the repository you'll need to add a `Signed-off-by` line to your commits. - -`$ git commit -s -m 'Awesome commit message'` - -Which will look something like the following in the repo; - -```text -Awesome commit message - -Signed-off-by: Jane Smith -``` - -- In case you forgot to add it to the most recent commit, use `git commit --amend --signoff` -- In case you forgot to add it to the last N commits in your branch, use `git rebase --signoff HEAD~N` and replace N with the number of new commits you created in your branch. -- If you have a very deep branch with a lot of commits, run `git rebase -i --signoff $(git merge-base -a master HEAD)`, double check to make sense of the commits (keep all lines as `pick`) and save and close the editor. This should bulk sign all the commits in your PR. Do be careful though. If you have a complex flow with a lot of branching and re-merging of work branches and stuff, merge-base may not be the right solution for you. - -Note: If you have already pushed your branch to a remote, you might have to force push: `git push -f` after the rebase. - -### Using GitHub Desktop? - -If you are using the GitHub Desktop client, you need to manually add the `Signed-off-by` line to the Description field on the Changes tab before committing: - -```text -Awesome description (commit message) - -Signed-off-by: Jane Smith -``` - -In case you forgot to add the line to your most recent commit, you can amend the commit message from the History tab before pushing your branch (GitHub Desktop 2.9 or later). - -## API Reports - -Backstage uses [API Extractor](https://api-extractor.com/) and TSDoc comments to generate API Reports in Markdown format. These reports are what drive the [API Reference documentation](https://backstage.io/docs/reference/). 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/` from the 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/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: - -```md -## Hey, I just made a Pull Request! - - - -#### :heavy_check_mark: Checklist - - - -- [ ] 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 of 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 `master` branch is up to date and then in your branch run `git checkout master yarn.lock` and then run `yarn install`, this will get you a conflict free `yarn.lock` file you can commit -- If Vale finds issues with your documentation but it's a code reference you can fix it by putting backticks (`) around it. Now if it is a special word or maybe a name there are two ways you can fix that by adding it to the list of accepted words in the [accept.txt file](https://github.com/backstage/backstage/blob/master/.github/vale/Vocab/Backstage/accept.txt) and them committing that change diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index 063eeb399f..9c6f34dd2c 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -11,7 +11,7 @@ A Backstage App is a monorepo setup with `lerna` that includes everything you need to run Backstage in your own environment. If you intend to contribute a plugin, new feature, or bug fix to the Backstage project, you -may want to read the [Contributors](./contributors.md) guide instead. +may want to read the [Contributors](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md) guide instead. ## Create an app diff --git a/microsite/docusaurus.config.js b/microsite/docusaurus.config.js index a55ad01a35..bd1b59ce97 100644 --- a/microsite/docusaurus.config.js +++ b/microsite/docusaurus.config.js @@ -139,6 +139,10 @@ module.exports = { from: '/docs/getting-started/running-backstage-locally', to: '/docs/getting-started/', }, + { + from: '/docs/getting-started/contributors', + to: 'https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md', + }, ], }, ], From 4f07583ea6c4aa574d2121aef670d043046ad77e Mon Sep 17 00:00:00 2001 From: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Date: Fri, 8 Sep 2023 14:24:48 -0500 Subject: [PATCH 6/7] Corrections to get build to pass Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> --- docs/getting-started/index.md | 2 +- mkdocs.yml | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 773b5bd5a2..cd5a1725c9 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -15,7 +15,7 @@ system using tools like apt-get, npm, yarn, curl. Docker knowledge is also helpful for making the best use of your Backstage installation. If you are planning to contribute plugins or to the project in general, we advise -you to use the [Contributors](contributors.md) guide to do a repository-based installation. +you to use the [Contributors](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md) guide to do a repository-based installation. ### Prerequisites diff --git a/mkdocs.yml b/mkdocs.yml index 23d519f66e..66cd7ab977 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,7 +28,6 @@ nav: - Customize the look-and-feel of your App: 'getting-started/app-custom-theme.md' - Keeping Backstage Updated: 'getting-started/keeping-backstage-updated.md' - Key Concepts: 'getting-started/concepts.md' - - Contributors: 'getting-started/contributors.md' - Project Structure: 'getting-started/project-structure.md' - Local Development: - CLI: From 153ab42d90cd391192aec97d503295c6ad323d7d Mon Sep 17 00:00:00 2001 From: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Date: Mon, 11 Sep 2023 08:20:44 -0500 Subject: [PATCH 7/7] Added back contributors.md and removed redirect Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> --- docs/getting-started/contributors.md | 14 ++++++++++++++ microsite/docusaurus.config.js | 4 ---- 2 files changed, 14 insertions(+), 4 deletions(-) create mode 100644 docs/getting-started/contributors.md diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md new file mode 100644 index 0000000000..123958d440 --- /dev/null +++ b/docs/getting-started/contributors.md @@ -0,0 +1,14 @@ +--- +id: contributors +title: Contributors +# prettier-ignore +description: Documentation on how to get set up for doing development on the Backstage repository +--- + +Our vision for Backstage is for it to become the trusted standard toolbox (read: UX layer) for the open source infrastructure landscape. Think of it like Kubernetes for developer experience. We realize this is an ambitious goal. We can’t do it alone. + +Therefore we want to create a strong community of contributors -- all working together to create the kind of delightful experience that our developers deserve. + +Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. ❤️ + +To get you started we've put together a [Contributors Guide in the Backstage GitHub repo](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md) that has all the information you need diff --git a/microsite/docusaurus.config.js b/microsite/docusaurus.config.js index bd1b59ce97..a55ad01a35 100644 --- a/microsite/docusaurus.config.js +++ b/microsite/docusaurus.config.js @@ -139,10 +139,6 @@ module.exports = { from: '/docs/getting-started/running-backstage-locally', to: '/docs/getting-started/', }, - { - from: '/docs/getting-started/contributors', - to: 'https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md', - }, ], }, ],