paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 26 Packages Projects Releases Wiki Activity

apply suggestions from code review

Browse Source 
Signed-off-by: Aramis <sennyeyaramis@gmail.com>
Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>
This commit is contained in:
Aramis
2024-02-10 11:11:51 -05:00
committed by aramissennyeydd
parent f6cabb7115
commit 21684fe210
18 changed files with 55 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/config/database.md
+3 -3
View File
@@ -8,7 +8,7 @@ Audience: Admins
### Summary
This guide walks through how to set up a PostgreSQL database to host your Backstage data. It assumes you've already have a scaffolded Backstage app from following the [Standalone Install](../standalone-install.md) guide.
This guide walks through how to set up a PostgreSQL database to host your Backstage data. It assumes you've already have a scaffolded Backstage app from following the [Standalone Install](../index.md) guide.
By the end of this tutorial, you will have a working PostgreSQL database hooked up to your Backstage install.
@@ -75,7 +75,7 @@ App. Run the following to install the PostgreSQL client into your backend:
```bash
# From your Backstage root directory
yarn add --cwd packages/backend pg
yarn --cwd packages/backend add pg
```
Use your favorite editor to open `app-config.yaml` and add your PostgreSQL
@@ -117,7 +117,7 @@ If you opt for the second option of replacing the entire string, take care to no
:::
[Start the Backstage app](../standalone-install.md#2-run-the-backstage-app):
[Start the Backstage app](../index.md#2-run-the-backstage-app):
```shell
yarn dev
docs/getting-started/configure-app-with-plugins.md
+2 -2
View File
@@ -11,7 +11,7 @@ infrastructure needs - CI/CD, monitoring, auditing, and more.
## Adding existing plugins to your app
The following steps assume that you have
[created a Backstage app](./standalone-install.md) and want to add an existing plugin
[created a Backstage app](./index.md) and want to add an existing plugin
to it.
We are using the
@@ -75,7 +75,7 @@ to an entity in the software catalog.
### Adding a plugin page to the Sidebar
In a standard Backstage app created with
[@backstage/create-app](./standalone-install.md), the sidebar is managed inside
[@backstage/create-app](./index.md), the sidebar is managed inside
`packages/app/src/components/Root/Root.tsx`. The file exports the entire
`Sidebar` element of your app, which you can extend with additional entries by
adding new `SidebarItem` elements.
docs/getting-started/contributors.md
-14
View File
@@ -1,14 +0,0 @@
---
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.
docs/getting-started/create-a-component.md
+1 -1
View File
@@ -18,7 +18,7 @@ If you're running Backstage with Node 20 or later, you'll need to pass the flag
:::
You should already have [a standalone app](./standalone-install.md).
You should already have [a standalone app](./index.md).
## Creating your component
docs/getting-started/getting-involved.md
-66
View File
@@ -1,66 +0,0 @@
---
id: getting-involved
title: Getting Involved
# prettier-ignore
description: How can you help us build Backstage? We welcome contributions of all kinds, from documentation to code to design.
---
We encourage contributions of all kinds, from documentation to code to design, here's some ideas on how you can help us build and improve Backstage!
### Report bugs
No one likes bugs. Report bugs as an issue [here](https://github.com/backstage/backstage/issues/new?template=bug_template.md).
### Fix bugs or build new features
Look through the GitHub issues for [bugs](https://github.com/backstage/backstage/labels/bug), [good first issues](https://github.com/backstage/backstage/labels/good%20first%20issue) or [help wanted](https://github.com/backstage/backstage/labels/help%20wanted).
### Build a plugin
The value of Backstage grows with every new plugin that gets added. Wouldn't it be fantastic if there was a plugin for every infrastructure project out there? We think so. And we would love your help.
A great reference example of a plugin can be found on [our blog](https://backstage.io/blog/2020/04/06/lighthouse-plugin) (thanks [@fastfrwrd](https://github.com/fastfrwrd)!)
What kind of plugins should/could be created? Some inspiration from the 120+ plugins that we have developed inside Spotify can be found [here](https://backstage.io/demos), but we will keep a running list of suggestions labeled with [[plugin]](https://github.com/backstage/backstage/labels/plugin).
### Suggesting a plugin
If you start developing a plugin that you aim to release as open source, we suggest that you create a [new Issue](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development.
You can also use this process if you have an idea for a good plugin but you hope that someone else will pick up the work.
### Adding non-code Contributions
Since there is such a large landscape of possible development, build, and deployment environments, we welcome community contributions in these areas in the [`/contrib`](https://github.com/backstage/backstage/tree/master/contrib) folder of the project. This is an excellent place to put things that help out the community at large, but which may not fit within the scope of the core product to support natively. Here, you will find Helm charts, alternative Docker images, and much more.
### Write documentation or improve the website
The current documentation is very limited. Help us make the `/docs` folder come alive.
Docs are published to [backstage.io/docs](https://backstage.io/docs). If you
contribute to the documentation, you might want to preview your changes before
submitting them. You'll find the website sources under [/microsite](https://github.com/backstage/backstage/tree/master/microsite)
with instructions for building and locally serving the website in the
[README](/microsite#readme).
### Contribute to Storybook
We think the best way to ensure different plugins provide a consistent experience is through a solid set of reusable UI/UX components. Backstage uses [Storybook](http://backstage.io/storybook).
Either help us [create new components](https://github.com/backstage/backstage/labels/help%20wanted) or improve stories for the existing ones (look for files with `*.stories.tsx`).
### Submit feedback
The best way to send feedback is to file [an issue](https://github.com/backstage/backstage/issues).
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Use appropriate labels
- Remember that this is a volunteer-driven project, and that contributions
are welcome :)
### Add your company to `ADOPTERS`
Have you started using Backstage? Adding your company to [ADOPTERS](https://github.com/backstage/backstage/blob/master/ADOPTERS.md) really helps the project, you can do this by filling out this [Adopter form](https://form.typeform.com/to/zcOaKikB).
docs/getting-started/homepage.md
+1 -1
View File
@@ -19,7 +19,7 @@ At the end of this tutorial, you can expect:
Before we begin, make sure
- You have created your own standalone Backstage app using [`@backstage/create-app`](./standalone-install.md#1-create-your-backstage-app) and not using a fork of the [backstage](https://github.com/backstage/backstage) repository.
- You have created your own standalone Backstage app using [`@backstage/create-app`](./index.md#1-create-your-backstage-app) and not using a fork of the [backstage](https://github.com/backstage/backstage) repository.
- You do not have an existing homepage, and by default you are redirected to Software Catalog when you open Backstage.
Now, let's get started by installing the home plugin and creating a simple homepage for your Backstage app.
docs/getting-started/standalone-install.md → docs/getting-started/index.md
+8 -6
View File
@@ -1,10 +1,11 @@
---
id: standalone-install
title: Installing a standalone server (Developer or Admin)
id: index
title: Installing a standalone server
sidebar_label: Introduction
description: How to install Backstage for your own use.
---
Audience: All
Audience: Developers and Admins
## Summary
@@ -154,9 +155,10 @@ Choose the correct next steps for your user role, if you're likely to be deployi
### Developer
- [Logging into Backstage](./logging-in.md)
- [Register a component](./register-a-component.md)
- [Create a new component](./create-a-component.md)
- Using your Backstage instance
- [Logging into Backstage](./logging-in.md)
- [Register a component](./register-a-component.md)
- [Create a new component](./create-a-component.md)
Share your experiences, comments, or suggestions with us:
[on discord](https://discord.gg/backstage-687207715902193673), file issues for any
docs/getting-started/logging-in.md
+4 -2
View File
@@ -12,9 +12,9 @@ This guide will provide a quick tutorial on how to log in to your Backstage inst
## Prerequisites
You should have already [have a standalone app](./standalone-install.md) and completed the Github OAuth app setup defined in [the authentication tutorial](./config/authentication.md).
You should have already [have a standalone app](./index.md) and completed the Github OAuth app setup defined in [the authentication tutorial](./config/authentication.md).
## 1. Login to Backstage and check profile
## 1. Login to Backstage
Run your Backstage app with `yarn dev`. Navigate to `http://localhost:3000`.
@@ -24,6 +24,8 @@ To login, you should choose the "Github" provider and click the "Sign in" button
If you are already logged in, you will be automatically brought to your Backstage instance.
## 2. Verify that you're logged in
Once you've logged in, find the "Settings" item in the navigation bar to the left. Click it and you will see your profile. If you see your profile picture and name from Github here, congratulations! You've successfully set up a Github authentication integration.
<!-- Would like to have more FAQs here for help instead of funneling to Discord -->
docs/getting-started/project-structure.md
-226
View File
@@ -1,226 +0,0 @@
---
id: project-structure
title: Backstage Project Structure
# prettier-ignore
description: Introduction to files and folders in the Backstage Project repository
---
Backstage is a complex project, and the GitHub repository contains many
different files and folders. This document aims to clarify the purpose of those
files and folders.
## General purpose files and folders
In the project root, there are a set of files and folders which are not part of
the project as such, and may or may not be familiar to someone looking through
the code.
- [`.changeset/`](https://github.com/backstage/backstage/tree/master/.changeset) -
This folder contains files outlining which changes occurred in the project
since the last release. These files are added manually, but managed by
[changesets](https://github.com/atlassian/changesets) and will be removed at
every new release. They are essentially building-blocks of a CHANGELOG.
- [`.github/`](https://github.com/backstage/backstage/tree/master/.github) -
Standard GitHub folder. It contains - amongst other things - our workflow
definitions and templates. Worth noting is the
[vale](https://github.com/backstage/backstage/tree/master/.github/vale)
sub-folder which is used for a markdown spellchecker.
- [`.yarn/`](https://github.com/backstage/backstage/tree/master/.yarn) -
Backstage ships with its own `yarn` implementation. This allows us to have
better control over our `yarn.lock` file and hopefully avoid problems due to
yarn versioning differences.
- [`contrib/`](https://github.com/backstage/backstage/tree/master/contrib) -
Collection of examples or resources contributed by the community. We really
appreciate contributions in here and encourage them being kept up to date.
- [`docs/`](https://github.com/backstage/backstage/tree/master/docs) - This is
where we keep all of our documentation Markdown files. These end up on
https://backstage.io/docs. Just keep in mind that changes to the
[`sidebars.json`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.json)
file may be needed as sections are added/removed.
- [`.editorconfig`](https://github.com/backstage/backstage/tree/master/.editorconfig) -
A configuration file used by most common code editors. Learn more at
[EditorConfig.org](https://editorconfig.org/).
- [`.imgbotconfig`](https://github.com/backstage/backstage/tree/master/.imgbotconfig) -
Configuration for a [bot](https://imgbot.net/) which helps reduce image sizes.
## Monorepo packages
Every folder in both `packages/` and `plugins/` is within our monorepo setup, as
defined in
[`package.json`](https://github.com/backstage/backstage/blob/master/package.json):
```json
"workspaces": {
"packages": [
"packages/*",
"plugins/*"
]
},
```
Let's look at them individually.
### `packages/`
These are all the packages that we use within the project. [Plugins](#plugins)
are separated out into their own folder, see further down.
- [`app/`](https://github.com/backstage/backstage/tree/master/packages/app) -
This is our take on how an App could look like, bringing together a set of
packages and plugins into a working Backstage App. This is not a published
package, and the main goals are to provide a demo of what an App could look
like and to enable local development.
- [`backend/`](https://github.com/backstage/backstage/tree/master/packages/backend) -
Every standalone Backstage project will have both an `app` _and_ a `backend`
package. The `backend` uses plugins to construct a working backend that the
frontend (`app`) can use.
- [`backend-common/`](https://github.com/backstage/backstage/tree/master/packages/backend-common) -
There are no "core" packages in the backend. Instead we have `backend-common`
which contains helper middleware and other utils.
- [`catalog-client`](https://github.com/backstage/backstage/tree/master/packages/catalog-client) -
An isomorphic client to interact with the Software Catalog. Backend plugins
can use the package directly. Frontend plugins can use the client by using
`@backstage/plugin-catalog` in combination with `useApi` and the
`catalogApiRef`.
- [`catalog-model/`](https://github.com/backstage/backstage/tree/master/packages/catalog-model) -
You can consider this to be a library for working with the catalog of sorts.
It contains the definition of an
[Entity](https://backstage.io/docs/features/software-catalog/references#docsNav),
as well as validation and other logic related to it. This package can be used
in both the frontend and the backend.
- [`cli/`](https://github.com/backstage/backstage/tree/master/packages/cli) -
One of the biggest packages in our project, the `cli` is used to build, serve,
diff, create plugins and more. In the early days of this project, we started
out with calling tools directly - such as `eslint` - through `package.json`.
But as it was tricky to have a good development experience around that when we
change named tooling, we opted for wrapping those in our own CLI. That way
everything looks the same in `package.json`. Much like
[react-scripts](https://github.com/facebook/create-react-app/tree/master/packages/react-scripts).
- [`cli-common/`](https://github.com/backstage/backstage/tree/master/packages/cli-common) -
This package mainly handles path resolving. It is a separate package to reduce
bugs in
[CLI](https://github.com/backstage/backstage/tree/master/packages/cli). We
also want as few dependencies as possible to reduce download time when running
the CLI which is another reason this is a separate package.
- [`config/`](https://github.com/backstage/backstage/tree/master/packages/config) -
The way we read configuration data. This package can take a bunch of config
objects and merge them together.
[app-config.yaml](https://github.com/backstage/backstage/blob/master/app-config.yaml)
is an example of an config object.
- [`config-loader/`](https://github.com/backstage/backstage/tree/master/packages/config-loader) -
This package is used to read config objects. It does not know how to merge,
but only reads files and passes them on to the config. As this part is only
used by the backend, we chose to separate `config` and `config-loader` into
two different packages.
- [`core-app-api/`](https://github.com/backstage/backstage/tree/master/packages/core-app-api) -
This package contains the core APIs that are used to wire together Backstage
apps.
- [`core-components/`](https://github.com/backstage/backstage/tree/master/packages/core-components) -
This package contains our visual React components, some of which you can find
in
[plugin examples](https://backstage.io/storybook/?path=/story/plugins-examples--plugin-with-data).
- [`core-plugin-api/`](https://github.com/backstage/backstage/tree/master/packages/core-plugin-api) -
This package contains the core APIs that are used to build Backstage plugins.
- [`create-app/`](https://github.com/backstage/backstage/tree/master/packages/create-app) -
An CLI to specifically scaffold a new Backstage App. It does so by using a
[template](https://github.com/backstage/backstage/tree/master/packages/create-app/templates/default-app).
- [`dev-utils/`](https://github.com/backstage/backstage/tree/master/packages/dev-utils) -
Helps you setup a plugin for isolated development so that it can be served
separately.
- [`e2e-test/`](https://github.com/backstage/backstage/tree/master/packages/e2e-test) -
Another CLI that can be run to try out what would happen if you build all the
packages, publish them, create a new app, and then run them. CI uses this for
e2e-tests.
- [`integration/`](https://github.com/backstage/backstage/tree/master/packages/integration) -
Common functionalities of integrations like GitHub, GitLab, etc.
- [`storybook/`](https://github.com/backstage/backstage/tree/master/storybook) -
This folder contains only the Storybook config which helps visualize our
reusable React components. Stories are within the core package, and are
published in the [Backstage Storybook](https://backstage.io/storybook).
- [`techdocs-node/`](https://github.com/backstage/backstage/tree/master/plugins/techdocs-node) -
Common node.js functionalities for TechDocs, to be shared between
[techdocs-backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend)
plugin and [techdocs-cli](https://github.com/backstage/techdocs-cli).
- [`test-utils/`](https://github.com/backstage/backstage/tree/master/packages/test-utils) -
This package contains general purpose testing facilities for testing a
Backstage App or its plugins.
- [`theme/`](https://github.com/backstage/backstage/tree/master/packages/theme) -
Holds the Backstage Theme.
### `plugins/`
Most of the functionality of a Backstage App comes from plugins. Even core
features can be plugins, take the
[catalog](https://github.com/backstage/backstage/tree/master/plugins/catalog) as
an example.
We can categorize plugins into three different types; **Frontend**, **Backend**
and **GraphQL**. We differentiate these types of plugins when we name them, with
a dash-suffix. `-backend` means it’s a backend plugin and so on.
One reason for splitting a plugin is because of its dependencies. Another reason
is for clear separation of concerns.
Take a look at our [Plugin Directory](https://backstage.io/plugins) or browse
through the
[`plugins/`](https://github.com/backstage/backstage/tree/master/plugins) folder.
## Packages outside of the monorepo
For convenience we include packages in our project that are not part of our
monorepo setup.
- [`microsite/`](https://github.com/backstage/backstage/blob/master/microsite) -
This folder contains the source code for backstage.io. It is built with
[Docusaurus](https://docusaurus.io/). This folder is not part of the monorepo
due to dependency reasons. Look at the
[microsite README](https://github.com/backstage/backstage/blob/master/microsite/README.md)
for instructions on how to run it locally.
## Root files specifically used by the `app`
These files are kept in the root of the project mostly by historical reasons.
Some of these files may be subject to be moved out of the root sometime in the
future.
- [`.npmrc`](https://github.com/backstage/backstage/tree/master/.npmrc) - It's
common for companies to have their own npm registry, and this file makes sure
that this folder always uses the public registry.
- [`.yarnrc.yml`](https://github.com/backstage/backstage/tree/master/.yarnrc.yml) -
Enforces "our" version of Yarn.
- [`app-config.yaml`](https://github.com/backstage/backstage/tree/master/app-config.yaml) -
Configuration for the app, both frontend and backend.
- [`catalog-info.yaml`](https://github.com/backstage/backstage/tree/master/catalog-info.yaml) -
Description of Backstage in the Backstage Entity format.
- [`lerna.json`](https://github.com/backstage/backstage/tree/master/lerna.json) -
[Lerna](https://github.com/lerna/lerna) monorepo config. We are using
`yarn workspaces`, so this will only be used for executing scripts.
docs/getting-started/register-a-component.md
+1 -1
View File
@@ -12,7 +12,7 @@ This guide will walk you through how to pull Backstage data from other locations
## Prerequisites
You should have already [have a standalone app](./standalone-install.md).
You should have already [have a standalone app](./index.md).
## 1. Finding our template