Merge branch 'mob/prepare-from-catalog' into blam/github-as-source

.github/CODEOWNERS

@@ -4,4 +4,5 @@
 # The last matching pattern takes precedence.
 # https://help.github.com/articles/about-codeowners/
 
-*                @spotify/backstage-core
+*                 @spotify/backstage-core
+/plugins/techdocs @spotify/techdocs-core

packages/app/package.json

@@ -14,6 +14,7 @@
     "@backstage/plugin-scaffolder": "^0.1.1-alpha.9",
     "@backstage/plugin-sentry": "^0.1.1-alpha.9",
     "@backstage/plugin-tech-radar": "^0.1.1-alpha.9",
+    "@backstage/plugin-techdocs": "^0.1.1-alpha.9",
     "@backstage/plugin-welcome": "^0.1.1-alpha.9",
     "@backstage/test-utils": "^0.1.1-alpha.9",
     "@backstage/theme": "^0.1.1-alpha.9",

packages/app/src/plugins.ts

@@ -23,3 +23,4 @@ export { plugin as Circleci } from '@backstage/plugin-circleci';
 export { plugin as RegisterComponent } from '@backstage/plugin-register-component';
 export { plugin as Sentry } from '@backstage/plugin-sentry';
 export { plugin as GitopsProfiles } from '@backstage/plugin-gitops-profiles';
+export { plugin as TechDocs } from '@backstage/plugin-techdocs';

packages/backend-common/src/hot.ts

@@ -72,63 +72,53 @@ export function useHotCleanup(_module: NodeModule, cancelEffect: () => void) {
   }
 }
 
+const CURRENT_HOT_MEMOIZE_INDEX_KEY = 'backstage.io/hmr-memoize-key';
+
 /**
- * This function allows devs to preserve
- * some value between hot-reloads.
- * Useful for stateful parts of the backend
+ * Memoizes a generated value across hot-module reloads. This is useful for
+ * stateful parts of the backend, e.g. to retain a database.
+ *
  * @example
  * ```ts
  * const db = useHotMemoize(module, () => createDB(dbParams));
  * ```
- * @param _module Reference to the current module where you invoke the fn
- * @param valueFactory Fn that returns the value you want to memoize
+ *
  * @warning Don't use inside conditionals or loops,
  * same rules as for hooks apply (https://reactjs.org/docs/hooks-rules.html)
+ *
+ * @param _module Reference to the current module where you invoke the fn
+ * @param valueFactory Fn that returns the value you want to memoize
  */
 export function useHotMemoize<T>(
   _module: NodeModule,
   valueFactory: () => T,
 ): T {
-  const CURRENT_HOT_MEMOIZE_INDEX_KEY = 'backstage.io/hmr-memoize-key';
-
   if (!_module.hot) {
-    // Just return value straight away
     return valueFactory();
   }
 
-  if (_module.hot && typeof _module.hot.data === 'undefined') {
-    // First run, init the module data
+  // When starting blank, reset the counter
+  if (!_module.hot.data?.[CURRENT_HOT_MEMOIZE_INDEX_KEY]) {
+    for (const ancestor of findAllAncestors(_module)) {
+      ancestor.hot?.addDisposeHandler(data => {
+        data[CURRENT_HOT_MEMOIZE_INDEX_KEY] = 1;
+      });
+    }
+
     _module.hot.data = {
-      [CURRENT_HOT_MEMOIZE_INDEX_KEY]: 0,
+      ..._module.hot.data,
+      [CURRENT_HOT_MEMOIZE_INDEX_KEY]: 1,
     };
   }
 
-  // Let's store data per module based on the order of the code invocation
-  const index = _module.hot.data[CURRENT_HOT_MEMOIZE_INDEX_KEY];
-  // Increasing the counter after each call
-  _module.hot.data[CURRENT_HOT_MEMOIZE_INDEX_KEY] += 1;
+  // Store data per module, based on the order of the code invocation
+  const index = _module.hot.data[CURRENT_HOT_MEMOIZE_INDEX_KEY]++;
+  const value = _module.hot.data[index] ?? valueFactory();
 
-  const prevValue = _module.hot.data[index];
-  const createDisposeHandler = (value: any) => (data: {
-    [key: number]: any;
-    [indexKey: string]: number;
-  }) => {
-    // Preserving the value through the HMR process
+  // Always add a handler that, upon a HMR event, reinstates the value.
+  _module.hot.addDisposeHandler(data => {
     data[index] = value;
-    // Decreasing the counter after each handler
-    data[CURRENT_HOT_MEMOIZE_INDEX_KEY] =
-      // First hot update is still different, need to populate the data
-      typeof data[CURRENT_HOT_MEMOIZE_INDEX_KEY] === 'undefined'
-        ? _module.hot!.data[CURRENT_HOT_MEMOIZE_INDEX_KEY] - 1
-        : data[CURRENT_HOT_MEMOIZE_INDEX_KEY] - 1;
-  };
+  });
 
-  if (prevValue) {
-    _module.hot!.addDisposeHandler(createDisposeHandler(prevValue));
-    return prevValue;
-  }
-
-  const newValue = valueFactory();
-  _module.hot.addDisposeHandler(createDisposeHandler(newValue));
-  return newValue;
+  return value;
 }

packages/backend/src/plugins/scaffolder.ts

@@ -32,5 +32,7 @@ export default async function createPlugin({ logger }: PluginEnvironment) {
   preparers.register('file', filePreparer);
   preparers.register('github', githubPreparer);
 
+  const preparers = new Preparers();
+
   return await createRouter({ preparers, templater, logger });
 }

plugins/scaffolder-backend/src/service/router.ts

@@ -53,6 +53,7 @@ export async function createRouter(
           'A GraphQL starter template for backstage to get you up and running\nthe best pracices with GraphQL\n',
         uid: '9cf16bad-16e0-4213-b314-c4eec773c50b',
         etag: 'ZTkxMjUxMjUtYWY3Yi00MjU2LWFkYWMtZTZjNjU5ZjJhOWM2',
+
         generation: 1,
       },
       spec: {

plugins/techdocs/.eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: [require.resolve('@backstage/cli/config/eslint')],
+};

plugins/techdocs/README.md

@@ -0,0 +1,13 @@
+# TechDocs Plugin
+
+Welcome to the TechDocs plugin - Spotify's docs-like-code approach built directly into [Backstage](https://backstage.io). Watch [a video of our approach on YouTube](https://www.youtube.com/watch?v=uFGCaZmA6d4) to learn more.
+
+**WIP: This plugin is a work in progress. It is not ready for use yet. Follow our progress on [the Backstage Discord](https://discord.gg/MUpMjP2) under #docs-like-code or on [our GitHub Milestone](https://github.com/spotify/backstage/milestone/15).**
+
+## Getting started
+
+Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/techdocs](http://localhost:3000/techdocs).
+
+You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
+This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
+It is only meant for local development, and the setup for it can be found inside the [/dev](/dev) directory.

plugins/techdocs/dev/index.tsx

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createDevApp } from '@backstage/dev-utils';
+import { plugin } from '../src/plugin';
+
+createDevApp().registerPlugin(plugin).render();

plugins/techdocs/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@backstage/plugin-techdocs",
+  "version": "0.1.1-alpha.9",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "private": true,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "scripts": {
+    "build": "backstage-cli plugin:build",
+    "start": "backstage-cli plugin:serve",
+    "lint": "backstage-cli lint",
+    "test": "backstage-cli test",
+    "diff": "backstage-cli plugin:diff",
+    "prepack": "backstage-cli prepack",
+    "postpack": "backstage-cli postpack",
+    "clean": "backstage-cli clean"
+  },
+  "dependencies": {
+    "@backstage/core": "^0.1.1-alpha.9",
+    "@backstage/theme": "^0.1.1-alpha.9",
+    "@material-ui/core": "^4.9.1",
+    "@material-ui/icons": "^4.9.1",
+    "@material-ui/lab": "4.0.0-alpha.45",
+    "react": "^16.13.1",
+    "react-dom": "^16.13.1",
+    "react-use": "^14.2.0"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.1.1-alpha.9",
+    "@backstage/dev-utils": "^0.1.1-alpha.9",
+    "@testing-library/jest-dom": "^5.7.0",
+    "@testing-library/react": "^9.3.2",
+    "@testing-library/user-event": "^10.2.4",
+    "@types/jest": "^25.2.2",
+    "@types/node": "^12.0.0",
+    "@types/testing-library__jest-dom": "^5.0.4",
+    "jest-fetch-mock": "^3.0.3"
+  },
+  "files": [
+    "dist/**/*.{js,d.ts}"
+  ]
+}

plugins/techdocs/src/components/ExampleComponent/ExampleComponent.test.tsx

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React from 'react';
+import { render } from '@testing-library/react';
+import mockFetch from 'jest-fetch-mock';
+import ExampleComponent from './ExampleComponent';
+import { ThemeProvider } from '@material-ui/core';
+import { lightTheme } from '@backstage/theme';
+
+describe('ExampleComponent', () => {
+  it('should render', () => {
+    mockFetch.mockResponse(() => new Promise(() => {}));
+    const rendered = render(
+      <ThemeProvider theme={lightTheme}>
+        <ExampleComponent />
+      </ThemeProvider>,
+    );
+    expect(rendered.getByText('Welcome to techdocs!')).toBeInTheDocument();
+  });
+});

plugins/techdocs/src/components/ExampleComponent/ExampleComponent.tsx

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React, { FC } from 'react';
+import { Typography, Grid } from '@material-ui/core';
+import {
+  InfoCard,
+  Header,
+  Page,
+  pageTheme,
+  Content,
+  ContentHeader,
+  HeaderLabel,
+  SupportButton,
+} from '@backstage/core';
+import ExampleFetchComponent from '../ExampleFetchComponent';
+
+const ExampleComponent: FC<{}> = () => (
+  <Page theme={pageTheme.tool}>
+    <Header title="Welcome to techdocs!" subtitle="Optional subtitle">
+      <HeaderLabel label="Owner" value="Team X" />
+      <HeaderLabel label="Lifecycle" value="Alpha" />
+    </Header>
+    <Content>
+      <ContentHeader title="Plugin title">
+        <SupportButton>A description of your plugin goes here.</SupportButton>
+      </ContentHeader>
+      <Grid container spacing={3} direction="column">
+        <Grid item>
+          <InfoCard title="Information card">
+            <Typography variant="body1">
+              All content should be wrapped in a card like this.
+            </Typography>
+          </InfoCard>
+        </Grid>
+        <Grid item>
+          <ExampleFetchComponent />
+        </Grid>
+      </Grid>
+    </Content>
+  </Page>
+);
+
+export default ExampleComponent;

plugins/techdocs/src/components/ExampleComponent/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { default } from './ExampleComponent';

plugins/techdocs/src/components/ExampleFetchComponent/ExampleFetchComponent.test.tsx

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React from 'react';
+import { render } from '@testing-library/react';
+import mockFetch from 'jest-fetch-mock';
+import ExampleFetchComponent from './ExampleFetchComponent';
+
+describe('ExampleFetchComponent', () => {
+  it('should render', async () => {
+    mockFetch.mockResponse(() => new Promise(() => {}));
+    const rendered = render(<ExampleFetchComponent />);
+    expect(await rendered.findByTestId('progress')).toBeInTheDocument();
+  });
+});

plugins/techdocs/src/components/ExampleFetchComponent/ExampleFetchComponent.tsx

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React, { FC } from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import { Table, TableColumn, Progress } from '@backstage/core';
+import Alert from '@material-ui/lab/Alert';
+import { useAsync } from 'react-use';
+
+const useStyles = makeStyles({
+  avatar: {
+    height: 32,
+    width: 32,
+    borderRadius: '50%',
+  },
+});
+
+type User = {
+  gender: string; // "male"
+  name: {
+    title: string; // "Mr",
+    first: string; // "Duane",
+    last: string; // "Reed"
+  };
+  location: object; // {street: {number: 5060, name: "Hickory Creek Dr"}, city: "Albany", state: "New South Wales",…}
+  email: string; // "duane.reed@example.com"
+  login: object; // {uuid: "4b785022-9a23-4ab9-8a23-cb3fb43969a9", username: "blackdog796", password: "patch",…}
+  dob: object; // {date: "1983-06-22T12:30:23.016Z", age: 37}
+  registered: object; // {date: "2006-06-13T18:48:28.037Z", age: 14}
+  phone: string; // "07-2154-5651"
+  cell: string; // "0405-592-879"
+  id: {
+    name: string; // "TFN",
+    value: string; // "796260432"
+  };
+  picture: { medium: string }; // {medium: "https://randomuser.me/api/portraits/men/95.jpg",…}
+  nat: string; // "AU"
+};
+
+type DenseTableProps = {
+  users: User[];
+};
+
+export const DenseTable: FC<DenseTableProps> = ({ users }) => {
+  const classes = useStyles();
+
+  const columns: TableColumn[] = [
+    { title: 'Avatar', field: 'avatar' },
+    { title: 'Name', field: 'name' },
+    { title: 'Email', field: 'email' },
+    { title: 'Nationality', field: 'nationality' },
+  ];
+
+  const data = users.map(user => {
+    return {
+      avatar: (
+        <img
+          src={user.picture.medium}
+          className={classes.avatar}
+          alt={user.name.first}
+        />
+      ),
+      name: `${user.name.first} ${user.name.last}`,
+      email: user.email,
+      nationality: user.nat,
+    };
+  });
+
+  return (
+    <Table
+      title="Example User List (fetching data from randomuser.me)"
+      options={{ search: false, paging: false }}
+      columns={columns}
+      data={data}
+    />
+  );
+};
+
+const ExampleFetchComponent: FC<{}> = () => {
+  const { value, loading, error } = useAsync(async (): Promise<User[]> => {
+    const response = await fetch('https://randomuser.me/api/?results=20');
+    const data = await response.json();
+    return data.results;
+  }, []);
+
+  if (loading) {
+    return <Progress />;
+  } else if (error) {
+    return <Alert severity="error">{error.message}</Alert>;
+  }
+
+  return <DenseTable users={value || []} />;
+};
+
+export default ExampleFetchComponent;

plugins/techdocs/src/components/ExampleFetchComponent/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { default } from './ExampleFetchComponent';

plugins/techdocs/src/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { plugin } from './plugin';

plugins/techdocs/src/plugin.test.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { plugin } from './plugin';
+
+describe('techdocs', () => {
+  it('should export plugin', () => {
+    expect(plugin).toBeDefined();
+  });
+});

plugins/techdocs/src/plugin.ts

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createPlugin, createRouteRef } from '@backstage/core';
+import ExampleComponent from './components/ExampleComponent';
+
+export const rootRouteRef = createRouteRef({
+  path: '/techdocs',
+  title: 'techdocs',
+});
+
+export const plugin = createPlugin({
+  id: 'techdocs',
+  register({ router }) {
+    router.addRoute(rootRouteRef, ExampleComponent);
+  },
+});

plugins/techdocs/src/setupTests.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import '@testing-library/jest-dom';
+require('jest-fetch-mock').enableMocks();