Merge branch 'master' of github.com:spotify/backstage into scaffolder/new-templates

* 'master' of github.com:spotify/backstage: [Templates] Remove WIP label (#1665) README: Fix another broken link (#1664) [Docs] Fix relative paths to code (#1662) docs(scaffolder) tidy up some more docs (#1661)
2020-07-16 14:11:51 +02:00
parent 540345bf73 33c834e2a9
commit bd7c38708d
20 changed files with 71 additions and 55 deletions
@@ -54,6 +54,10 @@ If you are proposing a feature:
 - 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](ADOPTERS.md) really helps the project.
+
 # Get Started!

 So...feel ready to jump in? Let's do this. Head over to the [Getting Started guide](https://github.com/spotify/backstage#getting-started) 👏🏻💯
@@ -59,11 +59,9 @@ The Backstage platform consists of a number of different components:
 - **app** - Main web application that users interact with. It's built up by a number of different _Plugins_. This repo contains an example implementation of an app (located in `packages/app`) and you can easily get started with your own app by [creating one](docs/create-an-app.md).
 - [**plugins**](https://github.com/spotify/backstage/tree/master/plugins) - Each plugin is treated as a self-contained web app and can include almost any type of content. Plugins all use a common set of platform API's and reusable UI components. Plugins can fetch data either from the _backend_ or through any RESTful API exposed through the _proxy_.
 - [**service catalog**](https://github.com/spotify/backstage/tree/master/packages/backend) - Service that holds the model of your software ecosystem, including organisational information and what team owns what software. The backend also has a Plugin model for extending its graph.
- **proxy** \* - Terminates HTTPS and exposes any RESTful API to Plugins.
+- [**proxy**](https://github.com/spotify/backstage/tree/master/plugins/proxy-backend) - Terminates HTTPS and exposes any RESTful API to Plugins.
 - **identity** - A backend service that holds your organisation's metadata.

-_\* not yet released_
-
 ## Getting started

 To run a Backstage app, you will need to have the following installed:
@@ -86,7 +84,7 @@ And that's it! You are good to go 👍

 ### Next step

-Take a look at the [Getting Started](docs/getting-started/README.md) guide to learn more about how to extend the functionality with Plugins.
+Take a look at the [Getting Started](docs/getting-started/index.md) guide to learn how to set up Backstage, and how to develop on the platform.

 ## Documentation

@@ -108,6 +106,7 @@ We would love your help in building Backstage! See [CONTRIBUTING](CONTRIBUTING.m
 - [RFCs](https://github.com/spotify/backstage/labels/rfc) - Help shape the technical direction
 - [FAQ](docs/FAQ.md) - Frequently Asked Questions
 - [Code of Conduct](CODE_OF_CONDUCT.md) - This is how we roll
+- [Adopters](ADOPTERS.md) - Companies already using Backstage
 - [Blog](https://backstage.io/blog/) - Announcements and updates
 - [Newsletter](https://mailchi.mp/spotify/backstage-community)
 - Give us a star ⭐️ - If you are using Backstage or think it is an interesting project, we would love a star ❤️
@@ -32,8 +32,12 @@ better yet, a pull request.
      - [API](features/software-catalog/api.md)
    - Software creation templates
      - [Overview](features/software-templates/index.md)
-      - [Configure templates](features/software-templates/configure-templates.md)
      - [Adding templates](features/software-templates/adding-templates.md)
+        - Extending the Scaffolder:
+          - [Overview](features/software-templates/extending/index.md)
+          - [Create your own Templater](features/software-templates/extending/create-your-own-templater.md)
+          - [Create your own Publisher](features/software-templates/extending/create-your-own-publisher.md)
+          - [Create your own Preparer](features/software-templates/extending/create-your-own-preparer.md)
    - Docs-like-code
      - [Overview](features/techdocs/README.md)
      - [Getting Started](features/techdocs/getting-started.md)
@@ -48,7 +52,7 @@ better yet, a pull request.
    - [Overview](plugins/index.md)
    - [Existing plugins](plugins/existing-plugins.md)
    - [Creating a new plugin](plugins/create-a-plugin.md)
-    - [Developing a plugin](plugins/developing-plugins.md)
+    - [Developing a plugin](plugins/plugin-development.md)
    - [Structure of a plugin](plugins/structure-of-a-plugin.md)
    - Backends and APIs
      - [Proxying](plugins/proxying.md)
@@ -9,10 +9,11 @@ to various third party APIs.
 There are occasions when the user wants to perform actions towards third party
 services that require authorization via OAuth. Backstage provides standardized
 [Utility APIs](../api/utility-apis.md) such as the
-[GoogleAuthApi](../../packages/core-api/src/apis/definitions/auth.ts) for that
-use-case. Backstage also includes a set of implementations of these APIs that
-integrate with the [auth-backend](../../plugins/auth-backend) plugin to provide
-a popup-based OAuth flow.
+[GoogleAuthApi](https://github.com/spotify/backstage/blob/master/packages/core-api/src/apis/definitions/auth.ts)
+for that use-case. Backstage also includes a set of implementations of these
+APIs that integrate with the
+[auth-backend](https://github.com/spotify/backstage/tree/master/plugins/auth-backend)
+plugin to provide a popup-based OAuth flow.

 ## Background

@@ -51,8 +52,9 @@ easier to make authenticated requests inside a plugin.
 ## OAuth Flow

 The following describes the OAuth flow implemented by the
-[auth-backend](../../plugins/auth-backend) and
-[DefaultAuthConnector](../../packages/core-api/src/lib/AuthConnector/DefaultAuthConnector.ts)
+[auth-backend](https://github.com/spotify/backstage/tree/master/plugins/auth-backend)
+and
+[DefaultAuthConnector](https://github.com/spotify/backstage/blob/master/packages/core-api/src/lib/AuthConnector/DefaultAuthConnector.ts)
 in `@backstage/core-api`.

 Component and APIs can request Access or ID Tokens from any available Auth
@@ -312,7 +312,7 @@ Apart from being a string, the software catalog leaves the format of this field
 open to implementers to choose. Most commonly, it is set to the ID or email of a
 group of people in an organizational structure.

-##
+## Kind: Template

 Describes the following entity kind:

@@ -43,7 +43,7 @@ As you can see in the above code a `TemplaterBuilder` is created and the default

 This `TemplaterKey` is used to select the correct templater from the
 `spec.templater` in the
-[Template Entity](../software-catalog/descriptor-format.md#kind-template).
+[Template Entity](../../software-catalog/descriptor-format.md#kind-template).

 If you wish to add a new templater you'll need to register it with the
 `TemplaterBuilder`.
@@ -73,9 +73,9 @@ follows:
 - `directory`- the skeleton directory returned from the `Preparer`, more info at
  [Create your own preparer](./create-your-own-preparer.md).
 - `values` - a json object which will resemble the `spec.schema` from the
-  [Template Entity](../software-catalog/descriptor-format.md#kind-template)
+  [Template Entity](../../software-catalog/descriptor-format.md#kind-template)
  which is defined here under spec.schema`. More info can be found here
-  [Register your own template](./register-your-own-template.md#adding-form-values-in-the-scaffolder-wizard)
+  [Register your own template](../adding-templates.md#adding-form-values-in-the-scaffolder-wizard)
 - `logStream` - a stream that you can write to for displaying in the frontend.
 - `dockerClient` - a [dockerode](https://github.com/apocas/dockerode) client to
  be able to run docker containers.
@@ -29,7 +29,7 @@ are required for backstage usage. The owner, which is a `user` in the backstage
 system, and the `storePath` which right now must be a Github Organisation and a
 non-existing github repository name in the format `organistaion/reponame`.

-![Enter backstage vars](./assets/template-picked-1.png)
+![Enter backstage vars](./assets/template-picked-2.png)

 ### Run!

@@ -50,7 +50,8 @@ system resources and slow things down.

 ## Package Scripts

-There are many commands to be found in the root [package.json](package.json),
+There are many commands to be found in the root
+[package.json](https://github.com/spotify/backstage/blob/master/package.json),
 here are some useful ones:

 ```python
@@ -80,7 +81,9 @@ yarn diff # Make sure all plugins are up to date with the latest plugin template
 yarn create-plugin # Create a new plugin
 ```

-> See [package.json](/package.json) for other yarn commands/options.
+> See
+> [package.json](https://github.com/spotify/backstage/blob/master/package.json)
+> for other yarn commands/options.

 [Next Step - Create a Backstage plugin](../plugins/create-a-plugin.md)

@@ -24,7 +24,7 @@ for your new plugin directly by navigating to
 `http://localhost:3000/my-plugin`._

 <p align='center'>
-    <img src='https://github.com/spotify/backstage/raw/master/docs/getting-started/my-plugin_screenshot.png' width='600' alt='my plugin'>
+    <img src='https://github.com/spotify/backstage/raw/master/docs/plugins/my-plugin_screenshot.png' width='600' alt='my plugin'>
 </p>

 You can also serve the plugin in isolation by running `yarn start` in the plugin
@@ -0,0 +1,11 @@
+# Existing plugins
+
+## Open source plugins
+
+The full list of open source plugins can be found
+[here](https://github.com/spotify/backstage/tree/master/plugins).
+
+## Plugin gallery
+
+TODO: In the future we would like to have something similar to
+https://grafana.com/grafana/plugins
@@ -5,15 +5,14 @@ Backstage is a single-page application composed of a set of plugins.
 Our goal for the plugin ecosystem is that the definition of a plugin is flexible
 enough to allow you to expose pretty much any kind of infrastructure or software
 development tool as a plugin in Backstage. By following strong
-[design guidelines](https://github.com/spotify/backstage/blob/master/docs/design.md)
-we ensure the the overall user experience stays consistent between plugins.
+[design guidelines](../dls/design.md) we ensure the the overall user experience
+stays consistent between plugins.

 ![plugin](my-plugin_screenshot.png)

 ## Creating a plugin

-To create a plugin, follow the steps outlined
-[here](https://github.com/spotify/backstage/blob/master/docs/getting-started/create-a-plugin.md).
+To create a plugin, follow the steps outlined [here](create-a-plugin.md).

 ## Suggesting a plugin

@@ -3,9 +3,10 @@
 ## NPM

 NPM packages are published through CI/CD in the
-[.github/workflows/master.yml](../../.github/workflows/master.yml) workflow.
-Every commit that is merged to master will be checked for new versions of all
-public packages, and any new versions will automatically be published to NPM.
+[.github/workflows/master.yml](https://github.com/spotify/backstage/blob/master/.github/workflows/master.yml)
+workflow. Every commit that is merged to master will be checked for new versions
+of all public packages, and any new versions will automatically be published to
+NPM.

 ### Creating a new release

@@ -102,6 +102,6 @@ environment you will probably face challenges like CORS policies and/or
 backend-side authorization. To smooth this process out you can use proxy -
 either the one you already have (like nginx/haproxy/etc) or the proxy-backend
 plugin that we provide for the backstage backend.
-[Read more](../../plugins/proxy-backend/README.md)
+[Read more](https://github.com/spotify/backstage/blob/master/plugins/proxy-backend/README.md)

 [Back to Getting Started](../README.md)
@@ -30,7 +30,6 @@ nav:
          - API: 'features/software-catalog/api.md'
      - Software creation templates:
          - Overview: 'features/software-templates/index.md'
-          - Configure templates: 'features/software-templates/configure-templates.md'
          - Adding templates: 'features/software-templates/adding-templates.md'
          - Extending the Scaffolder:
              - Overview: 'features/software-templates/extending/index.md'
@@ -51,7 +50,7 @@ nav:
      - Overview: 'plugins/index.md'
      - Existing plugins: 'plugins/existing-plugins.md'
      - Creating a new plugin: 'plugins/create-a-plugin.md'
-      - Developing a plugin: 'plugins/developing-plugins.md'
+      - Developing a plugin: 'plugins/plugin-development.md'
      - Structure of a plugin: 'plugins/structure-of-a-plugin.md'
      - Backends and APIs:
          - Proxying: 'plugins/proxying.md'
@@ -14,13 +14,13 @@ To run it within the backend do:

 1. Register the router in `packages/backend/src/index.ts`:

-```
+```ts
 const proxyEnv = useHotMemoize(module, () => createEnv('proxy'));

 const service = createServiceBuilder(module)
-    .loadConfig(configReader)
-    /** several different routers */
-    .addRouter('/', await proxy(proxyEnv));
+  .loadConfig(configReader)
+  /** several different routers */
+  .addRouter('/', await proxy(proxyEnv));
 ```

 2. Start the backend
@@ -33,5 +33,4 @@ This will launch the full example backend.

 ## Links

- (http-proxy-middleware)[https://www.npmjs.com/package/http-proxy-middleware]
- (The Backstage homepage)[https://backstage.io]
+- [http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware)
@@ -3,7 +3,7 @@ kind: Template
 metadata:
  name: springboot-template
  title: Spring Boot GRPC Service
-  description: Standard Spring Boot (Java) microservice with recommended configuration fpr GRPRC
+  description: Standard Spring Boot (Java) microservice with recommended configuration for GRPRC
  tags:
    - Recommended
    - Java
@@ -17,6 +17,7 @@ import Stream, { PassThrough } from 'stream';
 import os from 'os';
 import fs from 'fs';
 import Docker from 'dockerode';
+import { Writable } from 'stream';
 import { runDockerContainer } from './helpers';

 describe('helpers', () => {
@@ -26,9 +27,15 @@ describe('helpers', () => {
    jest
      .spyOn(mockDocker, 'run')
      .mockResolvedValue([{ Error: null, StatusCode: 0 }]);
-    jest
-      .spyOn(mockDocker, 'pull')
-      .mockResolvedValue([{ Error: null, StatusCode: 0 }]);
+    jest.spyOn(mockDocker, 'pull').mockImplementation((async (
+      _image: string,
+      _something: any,
+      handler: (err: Error | undefined, stream: Writable) => void,
+    ) => {
+      const mockStream = new Writable();
+      handler(undefined, mockStream);
+      mockStream.end();
+    }) as any);
  });

  describe('runDockerContainer', () => {
@@ -23,17 +23,12 @@ import {
  Lifecycle,
  Page,
  pageTheme,
+  Progress,
  SupportButton,
  useApi,
 } from '@backstage/core';
 import { catalogApiRef } from '@backstage/plugin-catalog';
-import {
-  Button,
-  Grid,
-  LinearProgress,
-  Link,
-  Typography,
-} from '@material-ui/core';
+import { Button, Grid, Typography, Link } from '@material-ui/core';
 import React, { useEffect } from 'react';
 import { Link as RouterLink } from 'react-router-dom';
 import useStaleWhileRevalidate from 'swr';
@@ -95,13 +90,7 @@ export const ScaffolderPage: React.FC<{}> = () => {
            documentation, ...).
          </SupportButton>
        </ContentHeader>
-        <Typography variant="body2" paragraph style={{ fontStyle: 'italic' }}>
-          <strong>NOTE!</strong> This feature is WIP. You can follow progress{' '}
-          <Link href="https://github.com/spotify/backstage/milestone/11">
-            here
-          </Link>
-          .
-        </Typography>
+        {!templates && isValidating && <Progress />}
        {templates && !templates.length && (
          <Typography variant="body2">
            Shoot! Looks like you don't have any templates. Check out the
@@ -111,7 +100,6 @@ export const ScaffolderPage: React.FC<{}> = () => {
            </Link>
          </Typography>
        )}
-        {!templates && isValidating && <LinearProgress />}
        <Grid container>
          {templates &&
            templates?.length > 0 &&