Project: Backstage (App Definition and Development / Application Definition & Image Build)
File: CONTRIBUTING.md

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 cant 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. Backstage is released under the Apache 2.0 License, and original creations contributed to this repo are accepted under the same license. If you need help, just jump into our . This project adheres to the . By participating, you are expected to honor this code. See . We encourage you to catch any accessibility issues already in the development phase of new features to Backstage, see our for more details. So...feel ready to jump in? Let's do this. Ok. So you're gonna want some code right? Go ahead and fork the repository into your own GitHub account and clone that code to your local machine. GitHub's 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 ``` 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 <http://localhost:3000> 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 documentation. All code is formatted with `prettier` using the configuration in the

If possible we recommend configuring your editor to format automatically, but you can also use the `yarn prettier --write <file>` command to format files. A consistent coding style is included via with the file at the root of the repo. Depending on your editor of choice, it will either support it out of the box or you can for the config to be applied. If you're contributing to the backend or CLI tooling, be mindful of cross-platform support. blog post is a good guide of what to keep in mind when writing cross-platform NodeJS. Also be sure to skim through our to see if they cover what you're working on. In particular 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 separately and make sure it is accessed by global command. 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. There are many commands to be found in the root , 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 lint: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 for other yarn commands/options. 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 . You can learn more about the local configuration in the section. We use to help us prepare

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. Any time a patch, minor, or major change aligning to is made to any published package in `packages/` or `plugins/`, a changeset should be used. It helps to align your change to the 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. Run `yarn changeset` from the root of the repo Select which packages you want to include a changeset for 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 for more details. Explain your changes in the generated changeset. See . Add generated changeset to Git Push the commit with your changeset to the branch associated with your PR Accept our gratitude for making the release process easier on the maintainers 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: ```md '@backstage/catalog': patch Fixed table layout ``` ```md '@backstage/catalog': patch Fixed bug in EntityTable component where table layout did not readjust properly below 1080x768 pixels. ``` ```md '@backstage/catalog': minor getEntity is now a function that returns a Promise. ``` ```md '@backstage/catalog': minor BREAKING The getEntity function now returns a Promise and must be awaited from now on. ``` ```md '@backstage/catalog': patch BREAKING The catalogEngine now requires a flux capacitor to be passed. ``` ````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, }); ``` ```` As with other CNCF projects, Backstage has adopted a . 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

`$ git commit -s -m 'Awesome commit message'` Which will look something like the following in the repo; ``` Awesome commit message Signed-off-by: Jane Smith <jane.smith@example.com> ``` Note: this assumes you have setup your git name and email, if you have not you can use these commands to set that up: ```shell git config --global user.name "Your Name" git config --global user.email "youremail@example.com" ``` 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. 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 <jane.smith@example.com> ``` 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). If you are using VS Code you can enable always signing your commits by setting the following in your `settings.json` file: ```json "git.alwaysSignOff": true, ``` Or from the Settings UI look for the "Git: Always Sign Off" setting and check the "Controls the signoff flag for all commits" box. Backstage uses and TSDoc comments to generate API Reports in Markdown format. These reports are what drive the . 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: 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. You can run `yarn build:api-reports plugins/<your-plugin-with-changes>` 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. 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 documentation will help you with

Once you create your PR you will be presented with a template in the PR's description that looks like this: ```md <!-- Please describe what you added, and add a screenshot if possible. That makes it easier to understand the change so we can :shipit: faster. --> <! Please include the following in your Pull Request when applicable: --> ) [ ] Added or updated documentation [ ] Tests for new functionality and regression tests for bug fixes [ ] Screenshots attached (for UI changes) ) ``` 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: <https://github.com/backstage/backstage/pull/19473> <https://github.com/backstage/backstage/pull/19623> <https://github.com/backstage/backstage/pull/15881> <https://github.com/backstage/backstage/pull/16401> 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. 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 and them committing that change 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.