Merge pull request #1 from backstage/master

update master

.changeset/afraid-weeks-sort.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-kubernetes': patch
+---
+
+k8s plugin now surfaces k8s components with only label selector query annotation.
+Previously backstage.io/kubernetes-label-selector catalog entity annotation would only work if you also included backstage.io/kubernetes-id.
+But backstage.io/kubernetes-id value was ignored

.changeset/blue-lemons-reflect.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-circleci': patch
+'@backstage/plugin-cloudbuild': patch
+'@backstage/plugin-github-actions': patch
+---
+
+Use Breadcrumbs from @backstage/core rather than material-ui

.changeset/brown-hotels-study.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-scaffolder': patch
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Move logic for constructing the template form to the backend, using a new `./parameter-schema` endpoint that returns the form schema for a given template.

.changeset/chatty-turkeys-fold.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+Bump `@svgr/webpack` from `5.4.x` to `5.5.x`.

.changeset/clean-plums-crash.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs-backend': patch
+---
+
+Forward authorization header on backend request if present

.changeset/curvy-pugs-type.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+GithubDiscoveryProcessor outputs locations as optional to avoid outputting errors for missing locations (see https://github.com/backstage/backstage/issues/4730).

.changeset/empty-windows-nail.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog': patch
+---
+
+Make the external `createComponent` route optional, hiding the "Create Component" button if it isn't bound.

.changeset/five-lies-smile.md

@@ -1,8 +0,0 @@
----
-'@backstage/plugin-circleci': patch
-'@backstage/plugin-jenkins': patch
----
-
-Refactor to support ADR004 module exporting.
-
-For more information, see https://backstage.io/docs/architecture-decisions/adrs-adr004.

.changeset/fluffy-elephants-suffer.md

@@ -0,0 +1,7 @@
+---
+'@backstage/catalog-model': patch
+'@backstage/plugin-catalog-backend': patch
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Add version `backstage.io/v1beta2` schema for Template entities.

.changeset/gentle-bears-fry.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-sonarqube': patch
+---
+
+Collect all available metric types if the number exceeds the default page size of 100.

.changeset/honest-moose-eat.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-common': patch
+---
+
+Add optional `logClientErrors` to errorHandler to log 4XX errors

.changeset/hungry-frogs-flow.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Consider both authentication methods for both `onprem` and `cloud` BitBucket

.changeset/itchy-items-serve.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs-backend': patch
+---
+
+Use external url for static docs

.changeset/kind-pens-deliver.md

@@ -0,0 +1,10 @@
+---
+'@backstage/techdocs-common': patch
+'@backstage/plugin-auth-backend': patch
+'@backstage/plugin-kafka-backend': patch
+'@backstage/plugin-kubernetes-backend': patch
+'@backstage/plugin-scaffolder-backend': patch
+'@backstage/plugin-techdocs-backend': patch
+---
+
+remove usage of res.send() for res.json() and res.end() to ensure content types are more consistently application/json on backend responses and error cases

.changeset/late-singers-speak.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-common': patch
+---
+
+Change debug log format to print as color grey

.changeset/light-vans-hide.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-api-docs': patch
+---
+
+Add organization name to the API Explorer page title

.changeset/long-bikes-check.md

@@ -0,0 +1,23 @@
+---
+'@backstage/create-app': patch
+---
+
+The api-docs plugin has been migrated to use an [external route reference](https://backstage.io/docs/plugins/composability#binding-external-routes-in-the-app) to dynamically link to the create component page.
+
+If you want to have a button that links to the scaffolder plugin from the API explorer, apply the following changes to `packages/app/src/App.tsx`:
+
+```diff
++ import { apiDocsPlugin } from '@backstage/plugin-api-docs';
+  import { scaffolderPlugin } from '@backstage/plugin-scaffolder';
+
+  const app = createApp({
+    // ...
+    bindRoutes({ bind }) {
++     bind(apiDocsPlugin.externalRoutes, {
++       createComponent: scaffolderPlugin.routes.root,
++     });
+    },
+  });
+```
+
+If you choose to not bind the routes, the button to create new APIs is not displayed.

.changeset/metal-pianos-repeat.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-kubernetes': patch
+---
+
+Support AWS auth provider on kubernetes FE plugin

.changeset/new-forks-perform.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog': patch
+---
+
+Use entity relation for the owner of an entity in the catalog entity page header.

.changeset/nice-spies-beam.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+Bump `@testing-library/react` in the plugin template from `^10.4.1` to `^11.2.5`. To apply this to an existing plugin, update the dependency in your `package.json`.

.changeset/old-coats-suffer.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs': minor
+---
+
+Add authorization header on techdocs api requests. Breaking change as clients now needs the Identity API.

.changeset/perfect-donkeys-hope.md

@@ -1,5 +0,0 @@
----
-'@backstage/cli': patch
----
-
-Fix config schema for `.app.listen`

.changeset/popular-sheep-act.md

@@ -0,0 +1,6 @@
+---
+'@backstage/core-api': patch
+'@backstage/core': patch
+---
+
+Added support for optional external route references. By setting `optional: true` when creating an `ExternalRouteRef` it is no longer a requirement to bind the route in the app. If the app isn't bound `useRouteRef` will return `undefined`.

.changeset/red-taxis-confess.md

@@ -0,0 +1,23 @@
+---
+'@backstage/plugin-api-docs': patch
+---
+
+The api-docs plugin has been migrated to use an [external route reference](https://backstage.io/docs/plugins/composability#binding-external-routes-in-the-app) to dynamically link to the create component page. This means you need to migrate the api docs plugin to use the new extension components, as well as bind the external route.
+
+To bind the external route from the api docs plugin to the scaffolder template index page, make sure you have the appropriate imports and add the following to the `createApp` call:
+
+```ts
+import { apiDocsPlugin } from '@backstage/plugin-api-docs';
+import { scaffolderPlugin } from '@backstage/plugin-scaffolder';
+
+const app = createApp({
+  // ...
+  bindRoutes({ bind }) {
+    bind(apiDocsPlugin.externalRoutes, {
+      createComponent: scaffolderPlugin.routes.root,
+    });
+  },
+});
+```
+
+If you choose to not bind the routes, the button to create new APIs is not displayed.

.changeset/rich-socks-move.md

@@ -0,0 +1,6 @@
+---
+'@backstage/core-api': patch
+'@backstage/core': patch
+---
+
+Internal refactor of how component data is access to avoid polluting components and make it possible to bridge across versions.

.changeset/shaggy-spiders-shop.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-sonarqube': patch
+---
+
+Display '-' instead of 'undefined' if no code coverage is reported.

.changeset/short-geese-double.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+New config command to export the configuration schema. When running backstage-cli with yarn, consider using `yarn --silent backstage-cli config:schema` to get a clean output on `stdout`.

.changeset/silly-dolphins-repair.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+Added the color prop to TrendLine from the Sparklines props types to be able to have custom colors.

.changeset/silver-balloons-play.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+Added a new useSupportConfig hook that reads a new `app.support` config key. Also updated the SupportButton and ErrorPage components to use the new config.

.changeset/slimy-singers-return.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Fixed file path resolution for templates with a file location

.changeset/spotty-cooks-work.md

@@ -0,0 +1,22 @@
+---
+'@backstage/plugin-scaffolder-backend': minor
+---
+
+Removed support for deprecated publisher auth configuration within the `scaffolder` configuration block, such as `scaffolder.github.token`. Access should instead be configured through `integrations` configuration.
+
+For example, replace the following configuration in `app-config.yaml`
+
+```yaml
+scaffolder:
+  github:
+    token: my-token
+```
+
+with
+
+```yaml
+integrations:
+  github:
+    - host: github.com
+      token: my-token
+```

.changeset/stale-ducks-sing.md

@@ -0,0 +1,56 @@
+---
+'@backstage/create-app': patch
+---
+
+Migrated away from using deprecated routes and router components at top-level in the app, and instead use routable extension pages.
+
+To apply this change to an existing app, make the following changes to `packages/app/src/App.tsx`:
+
+Update imports and remove the usage of the deprecated `app.getRoutes()`.
+
+```diff
+-import { Router as DocsRouter } from '@backstage/plugin-techdocs';
++import { TechdocsPage } from '@backstage/plugin-techdocs';
+ import { CatalogImportPage } from '@backstage/plugin-catalog-import';
+-import { Router as TechRadarRouter } from '@backstage/plugin-tech-radar';
+-import { SearchPage as SearchRouter } from '@backstage/plugin-search';
+-import { Router as SettingsRouter } from '@backstage/plugin-user-settings';
++import { TechRadarPage } from '@backstage/plugin-tech-radar';
++import { SearchPage } from '@backstage/plugin-search';
++import { UserSettingsPage } from '@backstage/plugin-user-settings';
++import { ApiExplorerPage } from '@backstage/plugin-api-docs';
+ import { EntityPage } from './components/catalog/EntityPage';
+ import { scaffolderPlugin, ScaffolderPage } from '@backstage/plugin-scaffolder';
+
+
+ const AppProvider = app.getProvider();
+ const AppRouter = app.getRouter();
+-const deprecatedAppRoutes = app.getRoutes();
+```
+
+As well as update or add the following routes:
+
+```diff
+   <Route path="/create" element={<ScaffolderPage />} />
+-  <Route path="/docs" element={<DocsRouter />} />
++  <Route path="/docs" element={<TechdocsPage />} />
++  <Route path="/api-docs" element={<ApiExplorerPage />} />
+   <Route
+     path="/tech-radar"
+-    element={<TechRadarRouter width={1500} height={800} />}
++    element={<TechRadarPage width={1500} height={800} />}
+   />
+   <Route path="/catalog-import" element={<CatalogImportPage />} />
+-  <Route
+-    path="/search"
+-    element={<SearchRouter/>}
+-  />
+-  <Route path="/settings" element={<SettingsRouter />} />
+-  {deprecatedAppRoutes}
++  <Route path="/search" element={<SearchPage />} />
++  <Route path="/settings" element={<UserSettingsPage />} />
+```
+
+If you have added additional plugins with registered routes or are using `Router` components from other plugins, these should be migrated to use the `*Page` components as well. See [this commit](https://github.com/backstage/backstage/commit/abd655e42d4ed416b70848ffdb1c4b99d189f13b) for more examples of how to migrate.
+
+For more information and the background to this change, see the [composability system migration docs](https://backstage.io/docs/plugins/composability).

.changeset/strange-apes-exercise.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-cloudbuild': patch
+---
+
+Change terminology for cloudbuild

.changeset/sweet-experts-whisper.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-backend': patch
+---
+
+Expose a configuration option for the oidc scope

.changeset/swift-cows-thank.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog': patch
+---
+
+Removed fullScreen property from UnregisterEntity Dialog modal.

.changeset/tame-wolves-hunt.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-github-actions': patch
+---
+
+Use Breadcrumbs from @backstage/core

.changeset/three-pumpkins-watch.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-jenkins': patch
+---
+
+- Add Jenkins logo to project page.
+- Move to new Backstage breadcrumb component.
+- Change references of deprecated "Job" terminology to "Project" per [Jenkins Glossary](https://www.jenkins.io/doc/book/glossary/).

.changeset/twenty-pandas-crash.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-react': patch
+---
+
+Fixed EntityProvider setting 'loading' bool erroneously to true

.changeset/young-pens-argue.md

@@ -0,0 +1,5 @@
+---
+'@backstage/techdocs-common': patch
+---
+
+Remove read-store-upload loop when uploading S3 objects for TechDocs

.dockerignore

@@ -1,5 +1,8 @@
 .git
+docs
+cypress
+microsite
 node_modules
-packages/*/node_modules
-plugins/*/node_modules
-plugins/*/dist
+packages
+!packages/backend/dist
+plugins

.github/CODEOWNERS

@@ -6,9 +6,13 @@
 
 *                                           @backstage/maintainers
 /docs/features/techdocs                     @backstage/techdocs-core
+/docs/features/search                       @backstage/techdocs-core
+/docs/assets/search                         @backstage/techdocs-core
 /plugins/cost-insights                      @backstage/silver-lining
 /plugins/cloudbuild                         @trivago/ebarrios
-/plugins/techdocs                           @backstage/techdocs-core
 /plugins/search                             @backstage/techdocs-core
+/plugins/techdocs                           @backstage/techdocs-core
 /plugins/techdocs-backend                   @backstage/techdocs-core
+/packages/techdocs-common                   @backstage/techdocs-core
 /.changeset/cost-insights-*                 @backstage/silver-lining
+/.changeset/techdocs-*                      @backstage/techdocs-core

.github/codecov.yml

@@ -1,5 +1,8 @@
 comment: false # Ref: https://docs.codecov.io/docs/pull-request-comments
 
+ignore:
+  - '**/*.stories.*'
+
 coverage:
   status:
     project:

.github/styles/vocab.txt

@@ -1,28 +1,118 @@
-abc
-andrewthauer
 Apdex
-api
 Api
+Autoscaling
+Avro
+Balachandran
+Bigtable
+Billett
+Blackbox
+Chai
+Changesets
+Chanwit
+Codecov
+Codehilite
+Config
+Discoverability
+Dockerfile
+Dockerize
+Docusaurus
+Dominik
+Ek
+Env
+Expedia
+Figma
+Firekube
+Fiverr
+Fredrik
+Georgoulas
+GitHub
+GitLab
+Grafana
+GraphQL
+Gustavsson
+Hackathons
+Henneke
+Heroku
+Hostname
+Iain
+Ioannis
+JavaScript
+Kaewkasi
+Knex
+Kumar
+Lerna
+Lundberg
+Luxon
+Malus
+Minikube
+Mkdocs
+Monorepo
+Namespaces
+Niklas
+OAuth
+Okta
+Oldsberg
+Olle
+Onboarding
+Patrik
+Phoen
+Platformize
+Pomaceous
+Preprarer
+Protobuf
+Proxying
+Raghunandan
+Readme
+Recharts
+Redash
+Repo
+Rollbar
+Rollup
+Rosaceae
+Routable
+Scaffolder
+Serverless
+Sinon
+Sneha
+Snyk
+Splunk
+Spotifiers
+Spotify
+Superfences
+Talkdesk
+Telenor
+Templater
+Templaters
+Thauer
+Tolerations
+Tuite
+Voi
+WWW
+Wealthsimple
+Weaveworks
+Webpack
+Zalando
+Zhou
+Zolotusky
+abc
+accessors
+adamdmharvey
+andrewthauer
+api
 apis
 args
 asciidoc
 async
-Avro
+autoscaling
 backrub
-Balachandran
 benjdlambert
-Bigtable
-Billett
-Blackbox
 bool
 boolean
 builtins
-Chai
 changeset
 changesets
-Changesets
 chanwit
-Chanwit
+ci
 cisphobia
 cissexist
 classname
@@ -30,144 +120,113 @@ cli
 cloudbuild
 cncf
 codeblocks
-Codecov
 codehilite
-Codehilite
 codeowners
+composability
+composable
 config
-Config
 configmaps
 configs
 const
 cookiecutter
 css
 dariddler
+dataflow
 deadnaming
 destructured
 dev
+devops
 devs
+dhenneke
 discoverability
-Discoverability
 dls
 docgen
-Dockerfile
-Dockerize
 dockerode
-Docusaurus
+dtuite
 dzolotusky
-eg
-Ek
 env
-Env
+esbuild
 eslint
+etag
 facto
 failover
-Figma
-Firekube
 freben
-Fredrik
-github
-Github
-gitlab
-Gitlab
-Grafana
+gitbeaker
 graphql
 graphviz
-Gustavsson
-Hackathons
 haproxy
-heroku
-Heroku
 horizontalpodautoscalers
-Hostname
+hotspots
+html
 http
 https
-Iain
 img
 incentivised
 inlined
 inlinehilite
 interop
-javascript
-Javascript
 jq
 js
 json
+jsonnet
 jsx
-Kaewkasi
-Knex
 kubectl
 kubernetes
 learnings
 lerna
-Lerna
+lockfile
 magiclink
 mailto
 maintainership
-Malus
 md
 microsite
 middleware
 minikube
-Minikube
+misconfiguration
+misconfigured
 misgendering
 mkdocs
-Mkdocs
 monorepo
-Monorepo
 monorepos
 msw
 namespace
 namespaces
-Namespaces
 namespacing
 neuro
 newrelic
 nginx
-Niklas
+nodegit
 nohoist
 nonces
+noop
 npm
+nvarchar
 nvm
-oauth
-Oauth
+octokit
 oidc
-Okta
-Oldsberg
 onboarding
-Onboarding
 pagerduty
-Patrik
-Phoen
+pageview
+parallelization
 plantuml
-Pomaceous
 postgres
+postpack
 pre
 prebaked
 preconfigured
-Preprarer
-Prerequisities
+prepack
 productional
-Protobuf
 proxying
-Proxying
 pygments
 pymdownx
-Raghunandan
 rankdir
 readme
-Readme
-Recharts
-Redash
 replicasets
 repo
-Repo
 repos
 rerender
 rollbar
-Rollbar
-Rollup
-Rosaceae
+routable
 rst
 rsync
 rugvip
@@ -175,59 +234,50 @@ ruleset
 sam
 scaffolded
 scaffolder
-Scaffolder
 semlas
 semver
-Serverless
-Sinon
-smartsymobls
-Snyk
+sourcemaps
 sparklines
-Spotifiers
 spotify
-Spotify
+sqlite
 squidfunk
 src
+stdout
 stefanalund
+subcomponent
+subcomponents
 subkey
 subtree
 superfences
-Superfences
 superset
 talkdesk
-Talkdesk
 tasklist
 techdocs
 templated
 templater
-Templater
 templaters
-Templaters
-Thauer
-theres
+theia
 toc
 tolerations
-Tolerations
 toolchain
 toolsets
 tooltip
 tooltips
 touchpoints
+transpilation
+transpiled
 ui
+unmanaged
+unregister
 untracked
 upvote
 url
 utils
+Valdemar
 validators
-Voi
-Wealthsimple
-Weaveworks
-Webpack
+varchar
+winston
 www
-WWW
 xyz
 yaml
-Zalando
-Zhou
-Zolotusky
 zoomable

.github/workflows/ci.yml

@@ -15,6 +15,10 @@ jobs:
     env:
       CI: true
       NODE_OPTIONS: --max-old-space-size=4096
+      INTEGRATION_TEST_GITHUB_TOKEN: ${{ secrets.INTEGRATION_TEST_GITHUB_TOKEN }}
+      INTEGRATION_TEST_GITLAB_TOKEN: ${{ secrets.INTEGRATION_TEST_GITLAB_TOKEN }}
+      INTEGRATION_TEST_BITBUCKET_TOKEN: ${{ secrets.INTEGRATION_TEST_BITBUCKET_TOKEN }}
+      INTEGRATION_TEST_AZURE_TOKEN: ${{ secrets.INTEGRATION_TEST_AZURE_TOKEN }}
 
     steps:
       - uses: actions/checkout@v2
@@ -73,7 +77,7 @@ jobs:
         run: yarn prettier:check
 
       - name: validate config
-        run: yarn backstage-cli config:check
+        run: yarn backstage-cli config:check --lax
 
       - name: lint
         run: yarn lerna -- run lint --since origin/master
@@ -83,7 +87,7 @@ jobs:
 
       - name: build changed packages
         if: ${{ steps.yarn-lock.outcome == 'success' }}
-        run: yarn lerna -- run build --since origin/master
+        run: yarn lerna -- run build --since origin/master --include-dependencies
 
       - name: build all packages
         if: ${{ steps.yarn-lock.outcome == 'failure' }}

.github/workflows/codeql-analysis.yml

@@ -11,6 +11,11 @@ on:
   pull_request:
     # The branches below must be a subset of the branches above
     branches: [master]
+    # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#scanning-pull-requests
+    paths-ignore:
+      - '**/*.md'
+      - '**/*.yml'
+      - '**/*.yaml'
   schedule:
     - cron: '0 8 * * 6'
 
@@ -36,11 +41,6 @@ jobs:
           # a pull request then we can checkout the head.
           fetch-depth: 2
 
-      # If this run was triggered by a pull request event, then checkout
-      # the head of the pull request instead of the merge commit.
-      - run: git checkout HEAD^2
-        if: ${{ github.event_name == 'pull_request' }}
-
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v1

.github/workflows/e2e.yml

@@ -3,6 +3,7 @@ name: E2E Test Linux
 on:
   pull_request:
     paths-ignore:
+      - '.changeset/**'
       - 'contrib/**'
       - 'docs/**'
       - 'microsite/**'

.github/workflows/fossa.yml

@@ -0,0 +1,24 @@
+name: FOSSA
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2.3.4
+
+      - name: Install Fossa
+        run: "curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install.sh | bash"
+
+      - name: Fossa Configure & Analyze
+        env:
+          # FOSSA Push-Only API Token
+          GITHUB_REF: $GITHUB_REF
+          FOSSA_API_KEY: 9ee7e8893660832a7387dcc32377fb61
+        run: node scripts/run-fossa.js

.github/workflows/master-win.yml

@@ -1,6 +1,7 @@
 name: Master Build Windows
 
 on:
+  workflow_dispatch:
   push:
     branches: [master]
 
@@ -15,6 +16,10 @@ jobs:
     env:
       CI: true
       NODE_OPTIONS: --max-old-space-size=4096
+      INTEGRATION_TEST_GITHUB_TOKEN: ${{ secrets.INTEGRATION_TEST_GITHUB_TOKEN }}
+      INTEGRATION_TEST_GITLAB_TOKEN: ${{ secrets.INTEGRATION_TEST_GITLAB_TOKEN }}
+      INTEGRATION_TEST_BITBUCKET_TOKEN: ${{ secrets.INTEGRATION_TEST_BITBUCKET_TOKEN }}
+      INTEGRATION_TEST_AZURE_TOKEN: ${{ secrets.INTEGRATION_TEST_AZURE_TOKEN }}
 
     steps:
       - uses: actions/checkout@v2
@@ -51,10 +56,13 @@ jobs:
       - name: test
         run: yarn lerna -- run test
 
+      # credit: https://github.com/appleboy/discord-action/issues/3#issuecomment-731426861
       - name: Discord notification
         if: ${{ failure() }}
-        uses: Ilshidur/action-discord@0.2.0
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
-        with:
-          args: 'Windows master build failed https://github.com/{{GITHUB_REPOSITORY}}/actions/runs/{{GITHUB_RUN_ID}}'
+        run: |
+          $MESSAGE=@"
+          {\"content\": \"Windows master build failed https://github.com/${{github.repository}}/actions/runs/${{github.run_id}}\"}
+          "@
+          C:\msys64\usr\bin\curl.exe -i -H "Accept: application/json" -H "Content-Type:application/json" -X POST $env:DISCORD_WEBHOOK --data $MESSAGE

.github/workflows/master.yml

@@ -1,6 +1,7 @@
 name: Main Master Build
 
 on:
+  workflow_dispatch:
   push:
     branches: [master]
 
@@ -8,6 +9,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
 
+    outputs:
+      needs_release: ${{ steps.release_check.outputs.needs_release }}
+
     strategy:
       matrix:
         node-version: [12.x, 14.x]
@@ -15,6 +19,99 @@ jobs:
     env:
       CI: true
       NODE_OPTIONS: --max-old-space-size=4096
+      INTEGRATION_TEST_GITHUB_TOKEN: ${{ secrets.INTEGRATION_TEST_GITHUB_TOKEN }}
+      INTEGRATION_TEST_GITLAB_TOKEN: ${{ secrets.INTEGRATION_TEST_GITLAB_TOKEN }}
+      INTEGRATION_TEST_BITBUCKET_TOKEN: ${{ secrets.INTEGRATION_TEST_BITBUCKET_TOKEN }}
+      INTEGRATION_TEST_AZURE_TOKEN: ${{ secrets.INTEGRATION_TEST_AZURE_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      # Beginning of yarn setup, keep in sync between all workflows, see ci.yml
+      - name: use node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/ # Needed for auth
+      - name: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.os }}-v${{ matrix.node-version }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+      - name: find location of global yarn cache
+        id: yarn-cache
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+      - name: yarn install
+        run: yarn install --frozen-lockfile
+      # End of yarn setup
+
+      - name: Fetch previous commit for release check
+        run: git fetch origin '${{ github.event.before }}'
+
+      - name: Check if release
+        id: release_check
+        run: node scripts/check-if-release.js
+        env:
+          COMMIT_SHA_BEFORE: '${{ github.event.before }}'
+
+      - name: validate config
+        run: yarn backstage-cli config:check --lax
+
+      - name: lint
+        run: yarn lerna -- run lint
+
+      - name: type checking and declarations
+        run: yarn tsc:full
+
+      - name: build
+        run: yarn build
+
+      - name: verify type dependencies
+        run: yarn lint:type-deps
+
+      - name: test (and upload coverage)
+        run: |
+          yarn lerna -- run test -- --coverage
+          bash <(curl -s https://codecov.io/bash)
+          # Upload code coverage for some specific flags. Also see .codecov.yml
+          bash <(curl -s https://codecov.io/bash) -f packages/core/coverage/* -F core
+          bash <(curl -s https://codecov.io/bash) -f packages/core-api/coverage/* -F core-api
+
+      - name: Discord notification
+        if: ${{ failure() }}
+        uses: Ilshidur/action-discord@0.2.0
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        with:
+          args: 'Master build failed https://github.com/{{GITHUB_REPOSITORY}}/actions/runs/{{GITHUB_RUN_ID}}'
+
+  # A separate release build that is only run for commits that are the result of merging the "Version Packages" PR
+  # We can't re-use the output from the above step, but we'll have a guaranteed node_modules cache and
+  # only run the build steps that are necessary for publishing
+  release:
+    needs: build
+
+    if: needs.build.outputs.needs_release == 'true'
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [14.x]
+
+    env:
+      CI: 'true'
+      NODE_OPTIONS: --max-old-space-size=4096
 
     steps:
       - uses: actions/checkout@v2
@@ -47,48 +144,36 @@ jobs:
         run: yarn install --frozen-lockfile
       # End of yarn setup
 
-      - name: validate config
-        run: yarn backstage-cli config:check
-
-      - name: lint
-        run: yarn lerna -- run lint
-
-      - name: type checking and declarations
+      - name: build type declarations
         run: yarn tsc:full
 
-      - name: build
-        run: yarn build
-
-      - name: verify type dependencies
-        run: yarn lint:type-deps
-
-      - name: test (and upload coverage)
-        run: |
-          yarn lerna -- run test -- --coverage
-          bash <(curl -s https://codecov.io/bash)
-          # Upload code coverage for some specific flags. Also see .codecov.yml
-          bash <(curl -s https://codecov.io/bash) -f packages/core/coverage/* -F core
-          bash <(curl -s https://codecov.io/bash) -f packages/core-api/coverage/* -F core-api
+      - name: build packages
+        run: yarn lerna -- run --ignore example-app build
 
       # Publishes current version of packages that are not already present in the registry
       - name: publish
-        if: matrix.node-version == '12.x'
         run: yarn lerna -- publish from-package --yes
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      # Tags the commit with the version in the core package if the tag doesn't exist
-      - uses: Klemensas/action-autotag@1.2.3
-        if: matrix.node-version == '12.x'
-        with:
-          GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
-          package_root: 'packages/core'
-          tag_prefix: 'v'
+      # Creates the next available tag with format "release-<year>-<month>-<day>[.<n>]"
+      - name: Create a release tag
+        id: create_tag
+        run: node scripts/create-release-tag.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
 
+      # Convert the newly created tag into a release with changelog information
+      - name: Create release on GitHub
+        run: node scripts/create-github-release.js ${{ steps.create_tag.outputs.tag_name }} 1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
+
+      # Notify everyone about this great new release :D
       - name: Discord notification
-        if: ${{ failure() }}
         uses: Ilshidur/action-discord@0.2.0
         env:
-          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_RELEASE_WEBHOOK }}
+          TAG_NAME: ${{ steps.create_tag.outputs.tag_name }}
         with:
-          args: 'Master build failed https://github.com/{{GITHUB_REPOSITORY}}/actions/runs/{{GITHUB_RUN_ID}}'
+          args: 'A new release has been published! https://github.com/backstage/backstage/releases/tag/{{TAG_NAME}}'

.github/workflows/microsite-build-check.yml

@@ -13,7 +13,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x, 14.x]
+        node-version: [14.x]
 
     env:
       CI: true
@@ -27,6 +27,9 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
 
+      - name: verify doc links
+        run: node scripts/verify-links.js
+
         # Skip caching of microsite dependencies, it keeps the global cache size
         # smaller, which make Windows builds a lot faster for the rest of the project.
       - name: yarn install
@@ -40,3 +43,7 @@ jobs:
       - name: build microsite
         run: yarn build
         working-directory: microsite
+
+      - name: verify sidebars
+        run: yarn verify:sidebars
+        working-directory: microsite

.github/workflows/microsite-with-storybook-deploy.yml

@@ -17,7 +17,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x]
+        node-version: [14.x]
 
     env:
       CI: true
@@ -55,7 +55,7 @@ jobs:
         run: ls microsite/build/backstage && ls microsite/build/backstage/storybook
 
       - name: Deploy both microsite and storybook to gh-pages
-        uses: JamesIves/github-pages-deploy-action@3.4.2
+        uses: JamesIves/github-pages-deploy-action@3.7.1
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           BRANCH: gh-pages

.github/workflows/nightly.yml

@@ -55,6 +55,7 @@ jobs:
 
       - name: tsc
         run: yarn tsc
+
       - name: build
         run: yarn build
 
@@ -62,7 +63,7 @@ jobs:
       - name: prepare nightly release
         run: yarn changeset version --snapshot nightly
 
-      # Publishes the nightly release to NPM, by using tag we make sure the release is
+      # Publishes the nightly release to npm, by using tag we make sure the release is
       # not flagged as the latest release, which means that people will not get this
       # version of the package unless requested explicitly
       - name: publish nightly release

.github/workflows/techdocs-project-board.yml

@@ -1,7 +1,7 @@
 name: Automatically add new TechDocs Issues and PRs to the GitHub project board
 # Development of TechDocs in Backstage is managed by this Kanban board - https://github.com/orgs/backstage/projects/1
 # New issues and PRs with TechDocs in their title or docs-like-code label will be added to the board.
-# Caveat: New PRs created from forks will not be added since GitHub actions don't share credentials with forks.
+# Caveat: New PRs created from forks will not be added since GitHub Actions don't share credentials with forks.
 
 on:
   issues:
@@ -9,17 +9,17 @@ on:
   pull_request:
     types: [opened, reopened, labeled, edited]
 
-env:
-  MY_GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
-
 jobs:
   assign_issue_or_pr_to_project:
     runs-on: ubuntu-latest
     name: Triage
+    env:
+      MY_GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
     steps:
       - name: Assign new issue to Incoming based on its title.
         uses: srggrs/assign-one-project-github-action@1.2.0
         if: |
+          env.MY_GITHUB_TOKEN != null &&
           contains(github.event.issue.title, 'TechDocs') ||
           contains(github.event.issue.title, 'techdocs') ||
           contains(github.event.issue.title, 'Techdocs')
@@ -30,6 +30,7 @@ jobs:
       - name: Assign new issue to Incoming based on its label.
         uses: srggrs/assign-one-project-github-action@1.2.0
         if: |
+          env.MY_GITHUB_TOKEN != null &&
           contains(github.event.issue.labels.*.name, 'docs-like-code')
         with:
           project: 'https://github.com/orgs/backstage/projects/1'
@@ -38,6 +39,7 @@ jobs:
       - name: Assign new PR to Incoming based on its title.
         uses: srggrs/assign-one-project-github-action@1.2.0
         if: |
+          env.MY_GITHUB_TOKEN != null &&
           contains(github.event.pull_request.title, 'TechDocs') ||
           contains(github.event.pull_request.title, 'techdocs') ||
           contains(github.event.pull_request.title, 'Techdocs')
@@ -48,6 +50,7 @@ jobs:
       - name: Assign new PR to Incoming based on its label.
         uses: srggrs/assign-one-project-github-action@1.2.0
         if: |
+          env.MY_GITHUB_TOKEN != null &&
           contains(github.event.pull_request.labels.*.name, 'docs-like-code')
         with:
           project: 'https://github.com/orgs/backstage/projects/1'

.github/workflows/tugboat.yml

@@ -0,0 +1,130 @@
+name: Tugboat E2E Tests
+on: deployment_status
+jobs:
+  set-pending:
+    if: github.event.deployment_status.state != 'success' && github.event.deployment_status.state != 'failed'
+    name: Set pending waiting for Tugboat
+    runs-on: ubuntu-latest
+    steps:
+      # Set an initial commit status message to indicate that the tests are
+      # running.
+      - name: set pending status
+        uses: actions/github-script@v3
+        with:
+          github-token: ${{secrets.GH_SERVICE_ACCOUNT_TOKEN}}
+          debug: true
+          script: |
+            return github.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: context.sha,
+              state: 'pending',
+              context: 'Backstage Tugboat E2E Tests',
+              description: 'Waiting for Tugboat to complete deployment',
+              target_url: "https://github.com/${{github.repository}}/actions/runs/${{github.run_id}}"
+            });
+
+  run-tests:
+    # Only run after a successful Tugboat deployment.
+    if: github.event.deployment_status.state == 'success'
+    name: Run tests against Tugboat deployment
+    runs-on: ubuntu-latest
+    steps:
+      # Set an initial commit status message to indicate that the tests are
+      # running.
+      - name: set pending status
+        uses: actions/github-script@v3
+        with:
+          github-token: ${{secrets.GH_SERVICE_ACCOUNT_TOKEN}}
+          debug: true
+          script: |
+            return github.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: context.sha,
+              state: 'pending',
+              context: 'Backstage Tugboat E2E Tests',
+              description: 'Running against tugboat preview',
+              target_url: "https://github.com/${{github.repository}}/actions/runs/${{github.run_id}}"
+            });
+
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v1
+        with:
+          node-version: '14'
+
+      - name: yarn install
+        run: yarn --cwd cypress install
+
+      # This is required because the environment_url param that Tugboat uses
+      # to tell us where the preview is located isn't supported unless you
+      # specify the custom Accept header when getting the deployment_status,
+      # and GitHub actions doesn't do that by default. So instead we have to
+      # load the status object manually and get the data we need.
+      # https://developer.github.com/changes/2016-04-06-deployment-and-deployment-status-enhancements/
+      - name: get deployment status
+        id: get-status-env
+        uses: actions/github-script@v3
+        with:
+          github-token: ${{secrets.GH_SERVICE_ACCOUNT_TOKEN}}
+          result-encoding: string
+          script: |
+            const result = await github.repos.getDeploymentStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              deployment_id: context.payload.deployment.id,
+              status_id: context.payload.deployment_status.id,
+              headers: {
+                'Accept': 'application/vnd.github.ant-man-preview+json'
+              },
+            });
+            console.log(result);
+            return result.data.environment_url;
+
+      - name: cypress run
+        uses: cypress-io/github-action@v2
+        env:
+          CYPRESS_baseUrl: ${{steps.get-status-env.outputs.result}}
+        with:
+          config-file: ./cypress.json
+          working-directory: ./cypress
+          browser: chrome
+          install: false
+          headless: true
+
+      - name: update artifact
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v1
+        with:
+          name: cypress-videos
+          path: ./cypress/cypress/videos
+
+      - name: set status
+        if: ${{ failure() }}
+        uses: actions/github-script@v3
+        with:
+          github-token: ${{secrets.GH_SERVICE_ACCOUNT_TOKEN}}
+          script: |
+            return github.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: context.sha,
+              state: "error",
+              context: 'Backstage Tugboat E2E Tests',
+              target_url: "https://github.com/${{github.repository}}/actions/runs/${{github.run_id}}"
+            });
+
+      - name: set status
+        if: ${{ success() }}
+        uses: actions/github-script@v3
+        with:
+          github-token: ${{secrets.GH_SERVICE_ACCOUNT_TOKEN}}
+          script: |
+            return github.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: context.sha,
+              state: "success",
+              context: 'Backstage Tugboat E2E Tests',
+              target_url: "https://github.com/${{github.repository}}/actions/runs/${{github.run_id}}"
+            });

.gitignore

@@ -130,3 +130,6 @@ site
 
 # Local configuration files
 *.local.yaml
+
+# Sensitive credentials
+*-credentials.yaml

.tugboat/config.yml

@@ -0,0 +1,17 @@
+services:
+  backstage:
+    image: tugboatqa/node:lts
+    expose: 7000
+    default: true
+    commands:
+      init:
+        - mkdir -p /etc/service/node
+        - echo "#!/bin/sh" > /etc/service/node/run
+        - echo "yarn --cwd ${TUGBOAT_ROOT} start-backend --config ${TUGBOAT_ROOT}/app-config.yaml --config ${TUGBOAT_ROOT}/.tugboat/tugboat.app-config.production.yaml" >> /etc/service/node/run
+        - chmod +x /etc/service/node/run
+      build:
+        - yarn install --frozen-lockfile
+        - yarn workspace example-app build
+      start:
+        # wget the endpoint. Will retry every 2 seconds. 30 retries = 1m for service to come up. Plenty.
+        - wget -O /dev/null -o /dev/null --tries=30 --timeout=5 --retry-connrefused http://localhost:7000

.tugboat/tugboat.app-config.production.yaml

@@ -0,0 +1,13 @@
+app:
+  title: Backstage Tugboat Preview
+  baseUrl:
+    $env: TUGBOAT_DEFAULT_SERVICE_URL
+
+backend:
+  baseUrl:
+    $env: TUGBOAT_DEFAULT_SERVICE_URL
+  cors:
+    origin:
+      $env: TUGBOAT_DEFAULT_SERVICE_URL
+    methods: [GET, POST, PUT, DELETE]
+    credentials: true

ADOPTERS.md

@@ -1,15 +1,23 @@
-| Organization                                 | Contact                                                      | Description of Use                                                                               |
-| -------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
-| [Spotify](https://www.spotify.com)           | [@stefanalund](https://github.com/stefanalund)               | Main interface towards all of Spotify's infrastructure and technical documentation.              |
-| [bol.com](https://www.bol.com)               | [@RoyJacobs](https://github.com/RoyJacobs)                   | Initial work being done to unify platform tooling.                                               |
-| [DFDS](https://www.dfds.com)                 | [@carlsendk](https://github.com/carlsendk)                   | V2 self-service platform.                                                                        |
-| [Roadie](https://roadie.io)                  | [@dtuite](https://github.com/dtuite)                         | Hosted, managed Backstage with easy set-up                                                       |
-| [Roku](https://www.roku.com)                 | [@timurista](https://github.com/timurista)                   | Initial work on Cloud engineering service platform.                                              |
-| [SDA SE](https://sda.se)                     | [@Fox32](https://github.com/Fox32)                           | Central place for developing and sharing services in our insurance ecosystem.                    |
-| [H-E-B](https://www.heb.com)                 | [@german-j-rodriguez](https://github.com/german-j-rodriguez) | Initial work on Engineering Portal service platform.                                             |
-| [American Airlines](https://www.aa.com)      | [@paulpach](https://github.com/paulpach)                     | Central place for developers to develop and maintain applications                                |
-| [Kiwi.com](https://kiwi.com)                 | [@aexvir](https://github.com/aexvir)                         | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry. |
-| [Voi](https://www.voiscooters.com/)          | [@K-Phoen](https://github.com/K-Phoen)                       | Developer portal, main gateway to our infrastructure, documentation and internal tooling.        |
-| [Talkdesk](https://www.talkdesk.com)         | [@jaime-talkdesk](https://github.com/jaime-talkdesk)         | Initial work for Engineering Portal and Self Provisioning to R&D                                 |
-| [Wealthsimple](https://www.wealthsimple.com) | [@andrewthauer](https://github.com/andrewthauer)             | Developer portal, service catalog, documentation and tooling                                     |
-| [Grab](https://www.grab.com)                 | [@althafh](https://github.com/althafh)                       | Initial work as a unified interface for all of Grab's internal tooling                           |
+| Organization                                  | Contact                                                                                                                                               | Description of Use                                                                                                                     |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [Spotify](https://www.spotify.com)            | [@leemills83](https://github.com/leemills83)                                                                                                          | Main interface towards all of Spotify's infrastructure and technical documentation.                                                    |
+| [bol.com](https://www.bol.com)                | [@RoyJacobs](https://github.com/RoyJacobs)                                                                                                            | Initial work being done to unify platform tooling.                                                                                     |
+| [DFDS](https://www.dfds.com)                  | [@carlsendk](https://github.com/carlsendk)                                                                                                            | V2 self-service platform.                                                                                                              |
+| [Roadie](https://roadie.io)                   | [@dtuite](https://github.com/dtuite)                                                                                                                  | Hosted, managed Backstage with easy set-up                                                                                             |
+| [Roku](https://www.roku.com)                  | [@timurista](https://github.com/timurista)                                                                                                            | Initial work on Cloud engineering service platform.                                                                                    |
+| [SDA SE](https://sda.se)                      | [@Fox32](https://github.com/Fox32)                                                                                                                    | Central place for developing and sharing services in our insurance ecosystem.                                                          |
+| [H-E-B](https://www.heb.com)                  | [@german-j-rodriguez](https://github.com/german-j-rodriguez)                                                                                          | Initial work on Engineering Portal service platform.                                                                                   |
+| [American Airlines](https://www.aa.com)       | [@paulpach](https://github.com/paulpach)                                                                                                              | Central place for developers to develop and maintain applications                                                                      |
+| [Kiwi.com](https://kiwi.com)                  | [@aexvir](https://github.com/aexvir)                                                                                                                  | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry.                                       |
+| [Voi](https://www.voiscooters.com/)           | [@K-Phoen](https://github.com/K-Phoen)                                                                                                                | Developer portal, main gateway to our infrastructure, documentation and internal tooling.                                              |
+| [Talkdesk](https://www.talkdesk.com)          | [@jaime-talkdesk](https://github.com/jaime-talkdesk)                                                                                                  | Initial work for Engineering Portal and Self Provisioning to R&D                                                                       |
+| [Wealthsimple](https://www.wealthsimple.com)  | [@andrewthauer](https://github.com/andrewthauer)                                                                                                      | Developer portal, service catalog, documentation and tooling                                                                           |
+| [Grab](https://www.grab.com)                  | [@althafh](https://github.com/althafh)                                                                                                                | Initial work as a unified interface for all of Grab's internal tooling                                                                 |
+| [Telenor Sweden](https://www.telenor.se)      | [@O5ten](https://github.com/O5ten)                                                                                                                    | Building a developer portal for scaffolding projects towards our unified build environment and microservice stacks                     |
+| [Fiverr](https://www.fiverr.com)              | [@nirga](https://github.com/nirga)                                                                                                                    | Unifying separate tools that developers are using today (i.e. monitoring, dead letter queues management, etc.) into a single platform. |
+| [Zalando SE](https://www.zalando.de)          | [@leviferreira](https://github.com/leviferreira)                                                                                                      | Building V2 of the Internal Development Portal.                                                                                        |
+| [LegalZoom](https://legalzoom.com)            | [@backjo](https://github.com/backjo)                                                                                                                  | Developer portal - hub for all engineering projects and metadata.                                                                      |
+| [Expedia Group](https://www.expediagroup.com) | [Mike Turner](mailto:miturner@expediagroup.com), [Sneha Kumar](mailto:snkumar@expediagroup.com), [@guillermomanzo](https://github.com/guillermomanzo) | EG Common Developer Toolkit                                                                                                            |
+| [Paddle.com](https://paddle.com)              | [Ioannis Georgoulas](https://github.com/geototti21)                                                                                                   | Developer portal (Tech Docs, Service Catalog, Internal Tooling), we use vanilla Backstage FE and custom BE implementation in Go        |
+| [Acast.com](https://acast.com)                | [Olle Lundberg](https://github.com/lndbrg)                                                                                                            | Developer portal with tech docs, service catalog and a bunch of other internal tooling                                                 |
+| [Lunar](https://lunar.app)                    | [Jacob Valdemar](https://github.com/JacobValdemar)                                                                                                    | Internal developer portal for service overview and insights, API documentation, technical guides, onboarding guides and RFC's.         |

CHANGELOG.md

@@ -1,13 +1,9 @@
 # Backstage Changelog
 
-This is a best-effort changelog where we manually collect breaking changes. It is not an exhaustive list of all changes or even features added.
+This changelog is no longer being updated and will be removed in the future, as each package now has its own changelog instead. It was a best-effort changelog where we manually collected breaking changes during the `v0.1.1-alpha.<n>` releases.
 
 If you encounter issues while upgrading to a newer version, don't hesitate to reach out on [Discord](https://discord.gg/EBHEGzX) or [open an issue](https://github.com/backstage/backstage/issues/new/choose)!
 
-## Next Release
-
-> Collect changes for the next release below
-
 ## v0.1.1-alpha.26
 
 ### @backstage/cli

CODE_OF_CONDUCT.md

@@ -18,7 +18,7 @@ Harassment includes, but is not limited to:
 - Offensive comments related to gender, gender identity and expression, sexual orientation, disability, mental illness, neuro(a)typicality, physical appearance, body size, race, age, regional discrimination, political or religious affiliation
 - Unwelcome comments regarding a person’s lifestyle choices and practices, including those related to food, health, parenting, drugs, and employment
 - Deliberate misgendering. This includes deadnaming or persistently using a pronoun that does not correctly reflect a person's gender identity. You must address people by the name they give you when not addressing them by their username or handle
-- Physical contact and simulated physical contact (eg, textual descriptions like “_hug_” or “_backrub_”) without consent or after a request to stop
+- Physical contact and simulated physical contact (e.g., textual descriptions like “_hug_” or “_backrub_”) without consent or after a request to stop
 - Threats of violence, both physical and psychological
 - Incitement of violence towards any individual, including encouraging a person to commit suicide or to engage in self-harm
 - Deliberate intimidation

CONTRIBUTING.md

@@ -6,19 +6,19 @@ Therefore we want to create strong community of contributors -- all working toge
 
 Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. ❤️
 
-Backstage is released under the Apache2.0 License, and original creations contributed to this repo are accepted under the same license.
+Backstage is released under the Apache 2.0 License, and original creations contributed to this repo are accepted under the same license.
 
-# Types of Contributions
+## Types of Contributions
 
-## Report bugs
+### 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
+### Fix bugs or build new features
 
 Look through the GitHub issues for [bugs](https://github.com/backstage/backstage/labels/bugs), [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
+### 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.
 
@@ -26,27 +26,27 @@ A great reference example of a plugin can be found on [our blog](https://backsta
 
 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
+### 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
+### 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
+### Write Documentation
 
 The current documentation is very limited. Help us make the `/docs` folder come alive.
 
-## Contribute to Storybook
+### 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
+### Submit Feedback
 
 The best way to send feedback is to file [an issue](https://github.com/backstage/backstage/issues).
 
@@ -58,47 +58,75 @@ If you are proposing a feature:
 - Remember that this is a volunteer-driven project, and that contributions
   are welcome :)
 
-## Add your company to ADOPTERS
+### Add your company to ADOPTERS
 
 Have you started using Backstage? Adding your company to [ADOPTERS](ADOPTERS.md) really helps the project.
 
-# Get Started!
+## Get Started!
 
 So...feel ready to jump in? Let's do this. 👏🏻💯
 
-Start by reading our [Getting Started](https://backstage.io/docs/getting-started/) page. If you need help, just jump into our [Discord chatroom](https://discord.gg/MUpMjP2).
+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/MUpMjP2).
 
-# Coding Guidelines
+## 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 <file>` 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](https://github.com/backstage/backstage/tree/master/docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for.
+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.
 
-# Creating Changesets
+## Developer Certificate of Origin
 
-We use [changesets](https://github.com/atlassian/changesets) to help us prepare releases. It helps 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.
+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 create a changeset
+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;
+
+```
+Awesome commit message
+
+Signed-off-by: Jane Smith jane.smith@example.com
+```
+
+## 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 stability index](https://backstage.io/docs/overview/stability-index) 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 not needed for the documentation, build utilities, contributed samples in `contrib/`, or the [example `packages/app`](packages/app).
+
+### How to create a changeset
 
 1. Run `yarn changeset`
 2. Select which packages you want to include a changeset for
-3. Select impact of change that you're introducing (minor, major or patch)
+3. Select impact of change that you're introducing (patch, minor, or major)
 4. Add generated changeset to Git
 5. Push the commit with your changeset to the branch associated with your PR
-6. Accept our gratitude for making the release process easier on the maintainer
+6. Accept our gratitude for making the release process easier on the maintainers
 
-For more information, checkout [adding a changeset](https://github.com/atlassian/changesets/blob/master/docs/adding-a-changeset.md) documentation in changesets repository.
+For more information, checkout [adding a changeset](https://github.com/atlassian/changesets/blob/master/docs/adding-a-changeset.md) documentation in the changesets repository.
 
-# Code of Conduct
+## 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 [Spotify FOSS 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?
+## Security Issues?
 
 See [SECURITY](SECURITY.md).

DCO

@@ -0,0 +1,37 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

OWNERS.md

@@ -22,3 +22,6 @@ People that have made significant contributions to the project and earned write
 
 - Andrew Thauer - Wealthsimple (GitHub: [andrewthauer](https://github.com/andrewthauer))
 - Oliver Sand - SDA SE (GitHub: [Fox32](https://github.com/Fox32))
+- David Tuite - Roadie (GitHub: [dtuite](https://github.com/dtuite))
+- Adam Harvey - DXC Technology (GitHub: [adamdmharvey](https://github.com/adamdmharvey))
+- Dominik Henneke - SDA SE (GitHub: [dhenneke](https://github.com/dhenneke))

README.md

@@ -10,13 +10,9 @@
 [![Codecov](https://img.shields.io/codecov/c/github/backstage/backstage)](https://codecov.io/gh/backstage/backstage)
 [![](https://img.shields.io/npm/v/@backstage/core?label=Version)](https://github.com/backstage/backstage/releases)
 
-> We recently moved from `spotify/backstage`, update your remotes!
->
-> `git remote set-url origin git@github.com:backstage/backstage.git`
-
 ## What is Backstage?
 
-[Backstage](https://backstage.io/) is an open platform for building developer portals. Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure. So your product teams can ship high-quality code quickly — without compromising autonomy.
+[Backstage](https://backstage.io/) is an open platform for building developer portals. Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly — without compromising autonomy.
 
 Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.
 
@@ -43,7 +39,7 @@ Check out [the documentation](https://backstage.io/docs/getting-started) on how
 
 - [Main documentation](https://backstage.io/docs)
 - [Service Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview)
-- [Architecture](https://backstage.io/docs/overview/architecture-terminology) ([Decisions](https://backstage.io/docs/architecture-decisions/adrs-overview))
+- [Architecture](https://backstage.io/docs/overview/architecture-overview) ([Decisions](https://backstage.io/docs/architecture-decisions/adrs-overview))
 - [Designing for Backstage](https://backstage.io/docs/dls/design)
 - [Storybook - UI components](https://backstage.io/storybook)
 
@@ -57,10 +53,11 @@ Check out [the documentation](https://backstage.io/docs/getting-started) on how
 - [Adopters](ADOPTERS.md) - Companies already using Backstage
 - [Blog](https://backstage.io/blog/) - Announcements and updates
 - [Newsletter](https://mailchi.mp/spotify/backstage-community) - Subscribe to our email newsletter
+- [Backstage Community Sessions](https://github.com/backstage/community) - Join monthly meetup and explore Backstage community
 - Give us a star ⭐️ - If you are using Backstage or think it is an interesting project, we would love a star ❤️
 
 ## License
 
-Copyright 2020 © Backstage Project Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage
+Copyright 2020-2021 © Backstage Project Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage
 
 Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

app-config.yaml

@@ -2,6 +2,19 @@ app:
   title: Backstage Example App
   baseUrl: http://localhost:3000
   googleAnalyticsTrackingId: # UA-000000-0
+  support:
+    url: https://github.com/backstage/backstage/issues # Used by common ErrorPage
+    items: # Used by common SupportButton component
+      - title: Issues
+        icon: github
+        links:
+          - url: https://github.com/backstage/backstage/issues
+            title: GitHub Issues
+      - title: Discord Chatroom
+        icon: chat
+        links:
+          - url: https://discord.gg/MUpMjP2
+            title: '#backstage'
 
 backend:
   baseUrl: http://localhost:7000
@@ -16,6 +29,10 @@ backend:
     credentials: true
   csp:
     connect-src: ["'self'", 'http:', 'https:']
+  reading:
+    allow:
+      - host: example.com
+      - host: '*.mozilla.org'
   # workingDirectory: /tmp # Use this to configure a working directory for the scaffolder, defaults to the OS temp-dir
 
 # See README.md in the proxy-backend plugin for information on the configuration format
@@ -46,20 +63,38 @@ proxy:
       X-Api-Key:
         $env: NEW_RELIC_REST_API_KEY
 
+  '/pagerduty':
+    target: https://api.pagerduty.com
+    headers:
+      Authorization:
+        $env: PAGERDUTY_TOKEN
+
   '/buildkite/api':
     target: https://api.buildkite.com/v2/
     headers:
       Authorization:
         $env: BUILDKITE_TOKEN
 
+  '/sentry/api':
+    target: https://sentry.io/api/
+    allowedMethods: ['GET']
+    headers:
+      Authorization:
+        $env: SENTRY_TOKEN
+
 organization:
   name: My Company
 
+# Reference documentation http://backstage.io/docs/features/techdocs/configuration
+# Note: After experimenting with basic setup, use CI/CD to generate docs
+# and an external cloud storage when deploying TechDocs for production use-case.
+# https://backstage.io/docs/features/techdocs/how-to-guides#how-to-migrate-from-techdocs-basic-to-recommended-deployment-approach
 techdocs:
-  storageUrl: http://localhost:7000/api/techdocs/static/docs
-  requestUrl: http://localhost:7000/api/techdocs
+  builder: 'local' # Alternatives - 'external'
   generators:
-    techdocs: 'docker'
+    techdocs: 'docker' # Alternatives - 'local'
+  publisher:
+    type: 'local' # Alternatives - 'googleGcs' or 'awsS3' or 'azureBlobStorage'. Read documentation for using alternatives.
 
 sentry:
   organization: my-company
@@ -78,6 +113,13 @@ kubernetes:
     - 'config'
   clusters: []
 
+kafka:
+  clientId: backstage
+  clusters:
+    - name: cluster
+      brokers:
+        - localhost:9092
+
 integrations:
   github:
     - host: github.com
@@ -110,7 +152,16 @@ integrations:
 
 catalog:
   rules:
-    - allow: [Component, API, Group, User, Template, Location]
+    - allow:
+        - Component
+        - API
+        - Resource
+        - Group
+        - User
+        - Template
+        - System
+        - Domain
+        - Location
 
   processors:
     githubOrg:
@@ -120,7 +171,7 @@ catalog:
             $env: GITHUB_TOKEN
         #### Example for how to add your GitHub Enterprise instance using the API:
         # - target: https://ghe.example.net
-        #   apiBaseUrl: https://ghe.example.net/api/v3
+        #   apiBaseUrl: https://ghe.example.net/api
         #   token:
         #     $env: GHE_TOKEN
     ldapOrg:
@@ -129,7 +180,8 @@ catalog:
       #   - target: ldaps://ds.example.net
       #     bind:
       #       dn: uid=ldap-reader-user,ou=people,ou=example,dc=example,dc=net
-      #       secret: { $secret: { env: LDAP_SECRET } }
+      #       secret:
+      #         $env: LDAP_SECRET
       #     users:
       #       dn: ou=people,ou=example,dc=example,dc=net
       #       options:
@@ -155,24 +207,46 @@ catalog:
       #    groupFilter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified')
 
   locations:
+    # Add a location here to ingest it, for example from an URL:
+    #
+    #     - type: url
+    #       target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-components.yaml
+    #
+    # For local development you can use a file location instead:
+    #
+    #     - type: file
+    #       target: ../catalog-model/examples/all-components.yaml
+    #
+    # File locations are relative to the current working directory of the
+    # backend, for example packages/backend/.
+
     # Backstage example components
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-components.yaml
-    # Example component for github-actions
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/plugins/github-actions/examples/sample.yaml
-    # Example component for techdocs
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/documented-component.yaml
+    - type: file
+      target: ../catalog-model/examples/all-components.yaml
+    # Example component for github-actions and TechDocs
+    - type: file
+      target: ../../plugins/github-actions/examples/sample.yaml
+    # Example component for TechDocs
+    - type: file
+      target: ../../plugins/techdocs-backend/examples/documented-component/catalog-info.yaml
     # Backstage example APIs
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-apis.yaml
+    - type: file
+      target: ../catalog-model/examples/all-apis.yaml
+    # Backstage example resources
+    - type: file
+      target: ../catalog-model/examples/all-resources.yaml
+    # Backstage example systems
+    - type: file
+      target: ../catalog-model/examples/all-systems.yaml
+    # Backstage example domains
+    - type: file
+      target: ../catalog-model/examples/all-domains.yaml
     # Backstage example templates
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/all-templates.yaml
+    - type: file
+      target: ../../plugins/scaffolder-backend/sample-templates/all-templates.yaml
     # Backstage example groups and users
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/acme-corp.yaml
+    - type: file
+      target: ../catalog-model/examples/acme-corp.yaml
 
 scaffolder:
   github:
@@ -184,12 +258,23 @@ scaffolder:
       baseUrl: https://gitlab.com
       token:
         $env: GITLAB_TOKEN
+    visibility: public # or 'internal' or 'private'
   azure:
     baseUrl: https://dev.azure.com/{your-organization}
     api:
       token:
         $env: AZURE_TOKEN
+  bitbucket:
+    api:
+      host: https://bitbucket.org
+      username:
+        $env: BITBUCKET_USERNAME
+      token:
+        $env: BITBUCKET_TOKEN
+    visibility: public # or or 'private'
+
 auth:
+  environment: development
   ### Providing an auth.session.secret will enable session support in the auth-backend
   # session:
   #   secret: custom session secret
@@ -237,6 +322,10 @@ auth:
           $env: AUTH_OAUTH2_AUTH_URL
         tokenUrl:
           $env: AUTH_OAUTH2_TOKEN_URL
+        ###
+        # provide a list of scopes as needed for your OAuth2 Server:
+        #
+        # scope: saml-login-selector openid profile email
     oidc:
       development:
         metadataUrl:
@@ -309,3 +398,5 @@ homepage:
       timezone: 'Europe/Stockholm'
     - label: TYO
       timezone: 'Asia/Tokyo'
+pagerduty:
+  eventsBaseUrl: 'https://events.pagerduty.com/v2'

catalog-info.yaml

@@ -4,9 +4,18 @@ metadata:
   name: backstage
   description: |
     Backstage is an open-source developer portal that puts the developer experience first.
+  links:
+    - title: Website
+      url: http://backstage.io
+    - title: Documentation
+      url: https://backstage.io/docs
+    - title: Storybook
+      url: https://backstage.io/storybook
+    - title: Discord Chat
+      url: https://discord.com/invite/EBHEGzX
   annotations:
     github.com/project-slug: backstage/backstage
-    backstage.io/techdocs-ref: github:https://github.com/backstage/backstage.git
+    backstage.io/techdocs-ref: url:https://github.com/backstage/backstage
     lighthouse.com/website-url: https://backstage.io
 spec:
   type: library

contrib/chart/backstage/templates/backend-secret.yaml

@@ -20,4 +20,5 @@ stringData:
   AZURE_TOKEN: {{ .Values.auth.azure.api.token }}
   NEW_RELIC_REST_API_KEY: {{ .Values.auth.newRelicRestApiKey }}
   TRAVISCI_AUTH_TOKEN: {{ .Values.auth.travisciAuthToken }}
+  PAGERDUTY_TOKEN: {{ .Values.auth.pagerdutyToken }}
 {{- end }}

contrib/chart/backstage/values.yaml

@@ -127,88 +127,67 @@ appConfig:
           appOrigin: 'http://localhost:3000/'
           secure: false
           clientId:
-            $secret:
-              env: AUTH_GOOGLE_CLIENT_ID
+            $env: AUTH_GOOGLE_CLIENT_ID
           clientSecret:
-            $secret:
-              env: AUTH_GOOGLE_CLIENT_SECRET
+            $env: AUTH_GOOGLE_CLIENT_SECRET
       github:
         development:
           appOrigin: 'http://localhost:3000/'
           secure: false
           clientId:
-            $secret:
-              env: AUTH_GITHUB_CLIENT_ID
+            $env: AUTH_GITHUB_CLIENT_ID
           clientSecret:
-            $secret:
-              env: AUTH_GITHUB_CLIENT_SECRET
+            $env: AUTH_GITHUB_CLIENT_SECRET
           enterpriseInstanceUrl:
-            $secret:
-              env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL
+            $env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL
       gitlab:
         development:
           appOrigin: 'http://localhost:3000/'
           secure: false
           clientId:
-            $secret:
-              env: AUTH_GITLAB_CLIENT_ID
+            $env: AUTH_GITLAB_CLIENT_ID
           clientSecret:
-            $secret:
-              env: AUTH_GITLAB_CLIENT_SECRET
+            $env: AUTH_GITLAB_CLIENT_SECRET
           audience:
-            $secret:
-              env: GITLAB_BASE_URL
+            $env: GITLAB_BASE_URL
       okta:
         development:
           appOrigin: 'http://localhost:3000/'
           secure: false
           clientId:
-            $secret:
-              env: AUTH_OKTA_CLIENT_ID
+            $env: AUTH_OKTA_CLIENT_ID
           clientSecret:
-            $secret:
-              env: AUTH_OKTA_CLIENT_SECRET
+            $env: AUTH_OKTA_CLIENT_SECRET
           audience:
-            $secret:
-              env: AUTH_OKTA_AUDIENCE
+            $env: AUTH_OKTA_AUDIENCE
       oauth2:
         development:
           appOrigin: 'http://localhost:3000/'
           secure: false
           clientId:
-            $secret:
-              env: AUTH_OAUTH2_CLIENT_ID
+            $env: AUTH_OAUTH2_CLIENT_ID
           clientSecret:
-            $secret:
-              env: AUTH_OAUTH2_CLIENT_SECRET
+            $env: AUTH_OAUTH2_CLIENT_SECRET
           authorizationURL:
-            $secret:
-              env: AUTH_OAUTH2_AUTH_URL
+            $env: AUTH_OAUTH2_AUTH_URL
           tokenURL:
-            $secret:
-              env: AUTH_OAUTH2_TOKEN_URL
+            $env: AUTH_OAUTH2_TOKEN_URL
       auth0:
         development:
           clientId:
-            $secret:
-              env: AUTH_AUTH0_CLIENT_ID
+            $env: AUTH_AUTH0_CLIENT_ID
           clientSecret:
-            $secret:
-              env: AUTH_AUTH0_CLIENT_SECRET
+            $env: AUTH_AUTH0_CLIENT_SECRET
           domain:
-            $secret:
-              env: AUTH_AUTH0_DOMAIN
+            $env: AUTH_AUTH0_DOMAIN
       microsoft:
         development:
           clientId:
-            $secret:
-              env: AUTH_MICROSOFT_CLIENT_ID
+            $env: AUTH_MICROSOFT_CLIENT_ID
           clientSecret:
-            $secret:
-              env: AUTH_MICROSOFT_CLIENT_SECRET
+            $env: AUTH_MICROSOFT_CLIENT_SECRET
           tenantId:
-            $secret:
-              env: AUTH_MICROSOFT_TENANT_ID
+            $env: AUTH_MICROSOFT_TENANT_ID
 
 auth:
   google:
@@ -250,3 +229,4 @@ auth:
   gitlabToken: g
   newRelicRestApiKey: r
   travisciAuthToken: fake-travis-ci-auth-token
+  pagerdutyToken: h

contrib/docker/frontend-with-nginx/Dockerfile

@@ -8,8 +8,6 @@ FROM nginx:mainline
 # This dockerfile requires the app to be built on the host first, as it
 # simply copies in the build output into the image.
 
-# The safest way to build this image is to use `yarn docker-build:app`
-
 RUN apt-get update && apt-get -y install jq && rm -rf /var/lib/apt/lists/*
 
 COPY packages/app/dist /usr/share/nginx/html

contrib/docs/tutorials/authenticate-api-requests.md

@@ -0,0 +1,93 @@
+# Authenticate API requests
+
+The Backstage backend APIs are by default available without authentication. To avoid evil-doers from accessing or modifying data, one might use a network protection mechanism such as a firewall or an authenticating reverse proxy. For Backstage instances that are available on the Internet one can instead use the experimental IdentityClient as outlined below.
+
+API requests from frontend plugins include an authorization header with a Backstage identity token acquired when the user logs in. By adding a middleware that verifies said token to be valid and signed by Backstage, non-authenticated requests can be blocked with a 401 Unauthorized response.
+
+Note that this means Backstage will stop working for guests, as no token is issued for them.
+
+Caveat: as of writing this, Backstage does not refresh the identity token so eventually users will get a 401 response on API calls (not on loading the web page as only the API calls are authenticated) and have to logout/login again to get a new token.
+
+```typescript
+// packages/backend/src/index.ts from a create-app deployment
+
+import cookieParser from 'cookie-parser';
+import { Request, Response, NextFunction } from 'express';
+import { JWT } from 'jose';
+import { URL } from 'url';
+import { IdentityClient } from '@backstage/plugin-auth-backend';
+
+// ...
+
+function setTokenCookie(
+  res: Response,
+  options: { token: string; secure: boolean; cookieDomain: string },
+) {
+  try {
+    const payload = JWT.decode(options.token) as object & {
+      exp: number;
+    };
+    res.cookie(`token`, options.token, {
+      expires: new Date(payload?.exp ? payload?.exp * 1000 : 0),
+      secure: options.secure,
+      sameSite: 'lax',
+      domain: options.cookieDomain,
+      path: '/',
+      httpOnly: true,
+    });
+  } catch (_err) {
+    // Ignore
+  }
+}
+
+async function main() {
+  // ...
+
+  const discovery = SingleHostDiscovery.fromConfig(config);
+  const identity = new IdentityClient({
+    discovery,
+    issuer: await discovery.getExternalBaseUrl('auth'),
+  });
+  const baseUrl = config.getString('backend.baseUrl');
+  const secure = baseUrl.startsWith('https://');
+  const cookieDomain = new URL(baseUrl).hostname;
+  const authMiddleware = async (
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ) => {
+    try {
+      const token =
+        IdentityClient.getBearerToken(req.headers.authorization) ||
+        req.cookies['token'];
+      req.user = await identity.authenticate(token);
+      if (!req.headers.authorization) {
+        // Authorization header may be forwarded by plugin requests
+        req.headers.authorization = `Bearer ${token}`;
+      }
+      if (token !== req.cookies['token']) {
+        setTokenCookie(res, {
+          token,
+          secure,
+          cookieDomain,
+        });
+      }
+      next();
+    } catch (error) {
+      res.status(401).send(`Unauthorized`);
+    }
+  };
+
+  const apiRouter = Router();
+  apiRouter.use(cookieParser());
+  // The auth route must be publically available as it is used during login
+  apiRouter.use('/auth', await auth(authEnv));
+  // Only authenticated requests are allowed to the routes below
+  apiRouter.use('/catalog', authMiddleware, await catalog(catalogEnv));
+  apiRouter.use('/techdocs', authMiddleware, await techdocs(techdocsEnv));
+  apiRouter.use('/proxy', authMiddleware, await proxy(proxyEnv));
+  apiRouter.use(authMiddleware, notFoundHandler());
+
+  // ...
+}
+```

contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md

@@ -4,6 +4,8 @@ Let's admit it, we've all been there. Sometimes you've gotta run stuff with no w
 
 Whilst this isn't supported natively by Backstage, this might help you get your installation up and running making calls through the said proxy tunnel.
 
+## backend
+
 Unfortunately, `nodejs` does not respect `HTTP(S)_PROXY` environment variables by default, and the library that we use to provide `fetch` functionality `node-fetch` (provided by `cross-fetch`) does not also respect these environment variables.
 
 There are however some ways to get this to work without too much effort. It's most likely that you're going to run into these issues from the `backend` part of `backstage` as that's the part that isn't helped by your browser or OS's settings for the corporate proxy.
@@ -56,3 +58,28 @@ if (process.env.HTTPS_PROXY) {
 ```
 
 4. Start the backend with `yarn start`
+
+## config
+
+If your development environment is in the cloud (like with [AWS Cloud9](https://aws.amazon.com/cloud9/) or an instance of [Theia](https://theia-ide.org/)), you will need to update your configuration.
+
+You will probably need to make some changes in `app-config.yaml` (or another config file like `app-config.local.yaml` if you've created it, see the [configuration doc](https://backstage.io/docs/conf/#supplying-configuration)).  
+The exact values will depend on your setup but for instance, if your public url is `https://your-public-url.com` and the port `3000` and `8080` are open:
+
+```yaml
+app:
+  baseUrl: https://your-public-url.com:3000
+  listen:
+    host: 0.0.0.0 # This makes the dev server bind to all IPv4 interfaces and not just the baseUrl hostname
+
+backend:
+  baseUrl: https://your-public-url.com:8080
+  listen:
+    port: 8080
+  cors:
+    origin: https://your-public-url.com:3000
+```
+
+If the protocol is `http`, you will need to set `backend.csp.upgrade-insecure-requests` to `false` as well.
+
+The app port must proxy web socket connections in order to make hot reloading work.

contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md

@@ -3,7 +3,7 @@
 ExampleComponent.tsx reference
 
 ```tsx
-import React, { FC } from 'react';
+import React from 'react';
 import { Typography, Grid } from '@material-ui/core';
 import {
   InfoCard,
@@ -14,11 +14,11 @@ import {
   HeaderLabel,
   SupportButton,
   identityApiRef,
+  useApi,
 } from '@backstage/core';
-import { useApi } from '@backstage/core-api';
 import ExampleFetchComponent from '../ExampleFetchComponent';
 
-const ExampleComponent: FC<{}> = () => {
+const ExampleComponent = () => {
   const identityApi = useApi(identityApiRef);
   const userId = identityApi.getUserId();
   const profile = identityApi.getProfile();

contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md

@@ -3,7 +3,7 @@
 ExampleFetchComponent.tsx reference
 
 ```tsx
-import React, { FC } from 'react';
+import React from 'react';
 import { useAsync } from 'react-use';
 import Alert from '@material-ui/lab/Alert';
 import {
@@ -11,8 +11,8 @@ import {
   TableColumn,
   Progress,
   githubAuthApiRef,
+  useApi,
 } from '@backstage/core';
-import { useApi } from '@backstage/core-api';
 import { graphql } from '@octokit/graphql';
 
 const query = `{
@@ -57,7 +57,7 @@ type DenseTableProps = {
   viewer: Viewer;
 };
 
-export const DenseTable: FC<DenseTableProps> = ({ viewer }) => {
+export const DenseTable = ({ viewer }: DenseTableProps) => {
   const columns: TableColumn[] = [
     { title: 'Name', field: 'name' },
     { title: 'Created', field: 'createdAt' },
@@ -76,7 +76,7 @@ export const DenseTable: FC<DenseTableProps> = ({ viewer }) => {
   );
 };
 
-const ExampleFetchComponent: FC<{}> = () => {
+const ExampleFetchComponent = () => {
   const auth = useApi(githubAuthApiRef);
 
   const { value, loading, error } = useAsync(async (): Promise<any> => {

contrib/kubernetes/plain_single_backend_deployment/README.md

@@ -6,6 +6,8 @@ This directory contains an example of a simple Kubernetes deployment of Backstag
 
 You can try the deployment out as is. The easiest way is to use [Docker Desktop](https://www.docker.com/products/docker-desktop) with [Kubernetes](https://docs.docker.com/get-started/kube-deploy/).
 
+You can now follow the documentation here to build the Backend Container [Docker Build](https://backstage.io/docs/getting-started/deployment-docker)
+
 From a fresh clone of this repo, run the following in the root:
 
 ```bash

contrib/kubernetes/plain_single_backend_deployment/deployment.yaml

@@ -53,7 +53,7 @@ spec:
 
           volumeMounts:
             - name: config-volume
-              mountPath: /usr/src/app/k8s-config.yaml
+              mountPath: /app/k8s-config.yaml
               subPath: k8s-config.yaml
 
           resources:

cypress/.eslintrc.js

@@ -0,0 +1,17 @@
+module.exports = {
+  extends: [require.resolve('@backstage/cli/config/eslint.backend')],
+  rules: {
+    'no-console': 0,
+    'import/no-extraneous-dependencies': [
+      'error',
+      {
+        devDependencies: true,
+        optionalDependencies: false,
+        peerDependencies: false,
+        bundledDependencies: false,
+      },
+    ],
+    'jest/expect-expect': 'off',
+    'no-restricted-syntax': 'off',
+  },
+};

cypress/README.md

@@ -0,0 +1,27 @@
+# Cypress Tests for Backstage
+
+Hey 👋 Welcome to the Cypress tests for Backstage. They're designed to be run against the `packages/app` folder in the main repo, and be some form of smoke tests to make sure that we don't break any core functionality.
+
+They run part of the PR build, and are triggered from the `.github/workflows/tugboat.yml` file.
+
+The main app gets built up part of a [Tugboat Build](https://tugboat.qa), which when complete, sends a `deployment event` to the PR triggering the aforementioned workflow.
+
+### Running Locally
+
+In order to make typescript happy, this `cypress` package is separate from all the Jest dependencies in the monorepo workspaces setup.
+
+You can run the e2e tests locally pointing at your local running version like so:
+
+```sh
+cd cypress
+yarn install
+yarn cypress run
+```
+
+You can open up the `cypress` console by using `yarn cypress open`.
+
+You can also run towards any Backstage installation by using the Cypress Environment Variable overrides.
+
+```sh
+CYPRESS_baseUrl="http://demo.backstage.io" yarn cypress run
+```

cypress/cypress.json

@@ -0,0 +1,8 @@
+{
+  "baseUrl": "http://localhost:7000",
+  "integrationFolder": "./src/integration",
+  "supportFile": "./src/support",
+  "fixturesFolder": "./src/fixures",
+  "pluginsFile": "./src/plugins",
+  "defaultCommandTimeout": 10000
+}

cypress/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@backstage/cypress-tests",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "private": true,
+  "dependencies": {
+    "cypress": "^6.4.0",
+    "typescript": "^4.1.3"
+  }
+}

cypress/src/integration/catalog.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 Spotify AB
+ * Copyright 2021 Spotify AB
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -13,14 +13,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { getRequestHeaders } from './sentry-api';
+/// <reference types="cypress" />
+import 'os';
 
-describe('SentryApiForwarder', () => {
-  it('should generate headers based on token passed in constructor', () => {
-    expect(getRequestHeaders('testtoken')).toEqual({
-      headers: {
-        Authorization: `Bearer testtoken`,
-      },
+describe('Catalog', () => {
+  describe('default entities', () => {
+    it('displays the correct amount of entities from default config', () => {
+      cy.loginAsGuest();
+
+      cy.visit('/catalog');
+
+      cy.contains('Owned (7)').should('be.visible');
     });
   });
 });

cypress/src/plugins/index.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2021 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 () => {};

cypress/src/support/index.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2021 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.
+ */
+/// <reference types="cypress" />
+
+Cypress.Commands.add('loginAsGuest', () => {
+  cy.visit('/', {
+    onLoad: (win: Window) =>
+      win.localStorage.setItem('@backstage/core:SignInPage:provider', 'guest'),
+  });
+});
+
+export {};

cypress/src/types.d.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2021 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.
+ */
+declare module 'zombie';
+declare module 'pgtools';
+declare namespace Cypress {
+  interface Chainable {
+    /**
+     * Login as guest
+     * @example cy.loginAsGuests
+     */
+    loginAsGuest(): Chainable<Element>;
+  }
+}

cypress/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "declarationMap": false,
+    "esModuleInterop": true,
+    "experimentalDecorators": false,
+    "forceConsistentCasingInFileNames": true,
+    "importHelpers": false,
+    "incremental": true,
+    "isolatedModules": true,
+    "jsx": "react",
+    "lib": ["DOM", "DOM.Iterable", "ScriptHost", "ES2020", "ESNext.Promise"],
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "noEmit": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "pretty": true,
+    "removeComments": false,
+    "resolveJsonModule": true,
+    "sourceMap": false,
+    "skipLibCheck": false,
+    "strict": true,
+    "strictBindCallApply": true,
+    "strictFunctionTypes": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2019",
+    "types": ["node", "cypress"]
+  }
+}

docs/FAQ.md

@@ -117,6 +117,62 @@ through the proxy.
 Learn more about [the different components](overview/what-is-backstage.md) that
 make up Backstage.
 
+### How do I keep my Backstage app up to date?
+
+In many ways one can view Backstage as a library rather than an application or
+service. The `@backstage/create-app` tool that is used to create your own
+Backstage app is similar to
+[`create-react-app`](https://github.com/facebook/create-react-app) in that it
+gives you a starting point. The code you get is meant to be evolved, and most of
+the functionality you get out of the box is brought in via npm dependencies.
+Keeping your app up to date generally means keeping your dependencies up to
+date. The Backstage CLI provides a command to help you with that. Simply run
+`yarn backstage-cli versions:bump` at the root of your repo, and the latest
+versions of all Backstage packages will be installed.
+
+While staying up to date with new releases and changes will keep your app up to
+date, it can often be convenient to use the changes done to the
+`@backstage/create-app` template as another method to stay up to date. For that
+purpose, any changes done to the template are documented along with upgrade
+instructions in the
+[changelog](https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md)
+of the `@backstage/create-app` package.
+
+### Why can't I dynamically install plugins without modifications the app?
+
+This decision is part of the core architecture and development flow of
+Backstage. Plugins have a lot of freedom in what they provide and how they are
+integrated into the app, and it would therefore add a lot of complexity to allow
+plugins to be integrated via configuration the same way as they can be
+integrated with code.
+
+By bundling all plugins and their dependencies into one app bundle it is also
+possible to do significant optimizations to the app load time by allowing
+plugins to share dependencies between each other when possible. This contributes
+to Backstage being fast, which is an important part of the user and developer
+experience.
+
+### Why are there no published Docker images or helm charts for Backstage?
+
+As mentioned above, Backstage is not a packaged service that you can use out of
+the box. In order to get started with Backstage you need to use the
+`@backstage/create-app` package to create and customize your own Backstage app.
+
+In order to build a Docker image from your own app, you can use the
+`yarn build-image` command which is included out of the box in the app template.
+By default this image will bundle up both the frontend and the backend into a
+single image that you can deploy using your favorite tooling.
+
+There are also some examples that can help you deploy Backstage to kubernetes in
+the
+[contrib](https://github.com/backstage/backstage/tree/master/contrib/kubernetes)
+folder.
+
+It is possible that example images will be provided in the future, which can be
+used to quickly try out a small subset of the functionality of Backstage, but
+these would not be able to provide much more functionality on top of what you
+can see on a demo site.
+
 ### Do I have to write plugins in TypeScript?
 
 No, you can use JavaScript if you prefer. We want to keep the Backstage core

docs/api/utility-apis.md

@@ -33,10 +33,10 @@ hook exported by `@backstage/core`, or the `withApis` HOC if you prefer class
 components. For example, the `ErrorApi` can be accessed like this:
 
 ```tsx
-import React, { FC } from 'react';
+import React from 'react';
 import { useApi, errorApiRef } from '@backstage/core';
 
-export const MyComponent: FC<{}> = () => {
+export const MyComponent = () => {
   const errorApi = useApi(errorApiRef);
 
   // Signal to the app that something went wrong, and display the error to the user.
@@ -119,7 +119,7 @@ Plugins supply their APIs through the `apis` option of `createPlugin`, for
 example:
 
 ```ts
-export const plugin = createPlugin({
+export const techdocsPlugin = createPlugin({
   id: 'techdocs',
   apis: [
     createApiFactory({
@@ -181,7 +181,25 @@ The `IgnoringErrorApi` would then be imported in the app, and wired up like
 this:
 
 ```ts
-builder.add(errorApiRef, new IgnoringErrorApi());
+const app = createApp({
+  apis: [
+    /* ApiFactories */
+    createApiFactory(errorApiRef, new IgnoringErrorApi()),
+
+    // OR
+    // If your API has dependencies, you use the object form
+    createApiFactory({
+      api: errorApiRef,
+      deps: { configApi: configApiRef },
+      factory({ configApi }) {
+        return new IgnoringErrorApi({
+          reportingUrl: configApi.getString('error.reportingUrl'),
+        });
+      },
+    }),
+  ],
+  // ... other options
+});
 ```
 
 Note that the above line will cause an error if `IgnoreErrorApi` does not fully

docs/architecture-decisions/adr000-template.md

@@ -0,0 +1,22 @@
+---
+id: adrs-adr000
+title: ADR000: [TITLE]
+description: Architecture Decision Record (ADR) for [TITLE] [DESCRIPTION]
+---
+
+<!-- These documents have names that are short noun phrases. For example, "ADR001: Deployment on Ruby on Rails 3.0.10" or "ADR009: LDAP for Multitenant Integration" -->
+
+## Context
+
+<!--
+This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. -->
+
+## Decision
+
+<!-- This section describes our response to these forces. It is stated in full sentences, with active voice. "We will ..." -->
+
+## Consequences
+
+<!-- This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future. -->
+
+<!-- This template is taken from a blog post by Michael Nygard http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions -->

docs/architecture-decisions/adr001-add-adr-log.md

@@ -4,12 +4,16 @@ title: ADR001: Architecture Decision Record (ADR) log
 description: Architecture Decision Record (ADR) logs as a reference point for the team
 ---
 
-| Created    | Status |
-| ---------- | ------ |
-| 2020-04-26 | Open   |
+## Decision
 
-## Decision: A decision was made to store ADRs in a log in the project repository
+A decision was made to store ADRs in a log in the project repository
 
-## Discussion: There is a need to store big decisions made in a log as a reference point for the team, help with onboarding new members and give context to others interested in the project.
+## Discussion
 
-## Risks: People stop adding ADRs to the log and context gets lost
+There is a need to store big decisions made in a log as a reference point for
+the team, help with onboarding new members and give context to others interested
+in the project.
+
+## Risks
+
+People stop adding ADRs to the log and context gets lost

docs/architecture-decisions/adr002-default-catalog-file-format.md

@@ -4,10 +4,6 @@ title: ADR002: Default Software Catalog File Format
 description: Architecture Decision Record (ADR) log on Default Software Catalog File Format
 ---
 
-| Created    | Status |
-| ---------- | ------ |
-| 2020-05-17 | Open   |
-
 ## Background
 
 Backstage comes with a software catalog functionality, that you can use to track

docs/architecture-decisions/adr003-avoid-default-exports.md

@@ -4,10 +4,6 @@ title: ADR003: Avoid Default Exports and Prefer Named Exports
 description: Architecture Decision Record (ADR) log on Avoid Default Exports and Prefer Named Exports
 ---
 
-| Created    | Status |
-| ---------- | ------ |
-| 2020-05-19 | Open   |
-
 ## Context
 
 When CommonJS was the primary authoring format, the best practice was to export

docs/architecture-decisions/adr004-module-export-structure.md

@@ -4,10 +4,6 @@ title: ADR004: Module Export Structure
 description: Architecture Decision Record (ADR) log on Module Export Structure
 ---
 
-| Created    | Status |
-| ---------- | ------ |
-| 2020-05-27 | Open   |
-
 ## Context
 
 With a growing number of exports of packages like `@backstage/core`, it is

docs/architecture-decisions/adr005-catalog-core-entities.md

@@ -4,10 +4,6 @@ title: ADR005: Catalog Core Entities
 description: Architecture Decision Record (ADR) log on Catalog Core Entities
 ---
 
-| Created    | Status |
-| ---------- | ------ |
-| 2020-05-29 | Open   |
-
 ## Context
 
 We want to standardize on a few core entities that we are tracking in the
@@ -58,7 +54,7 @@ discover existing functionality in the ecosystem.
 APIs are implemented by components and make their boundaries explicit. They
 might be defined using an RPC IDL (e.g. in Protobuf, GraphQL or similar), a data
 schema (e.g. in Avro, TFRecord or similar), or as code interfaces (e.g.
-framework APIs in Swift, Kotlin, Java, C++, Typescript etc). In any case, APIs
+framework APIs in Swift, Kotlin, Java, C++, TypeScript etc). In any case, APIs
 exposed by components need to be in a known machine-readable format so we can
 build further tooling and analysis on top.
 

docs/architecture-decisions/adr006-avoid-react-fc.md

@@ -6,7 +6,7 @@ description: Architecture Decision Record (ADR) log on Avoid React.FC and React.
 
 ## Context
 
-Facebook has removed `React.FC` from their base template for a Typescript
+Facebook has removed `React.FC` from their base template for a TypeScript
 project. The reason for this was that it was found to be an unnecessary feature
 with next to no benefits in combination with a few downsides.
 
@@ -43,6 +43,15 @@ const GoodComponent = ({ text, children }: GoodProps) => (
     {children}
   </div>
 );
+
+/* Or as a shorthand, if no specifc child type is required */
+type GoodProps = PropsWithChildren<{ text: string }>;
+const GoodComponent = ({ text, children }: GoodProps) => (
+  <div>
+    <div>{text}</div>
+    {children}
+  </div>
+);
 ```
 
 ## Consequences

docs/architecture-decisions/adr010-luxon-date-library.md

@@ -0,0 +1,36 @@
+---
+id: adrs-adr010
+title: ADR010: Use the Luxon Date Library
+description: Architecture Decision Record (ADR) for Luxon Date Library
+---
+
+## Context
+
+Date formatting (e.g. `a day ago`) and calculations are common within Backstage.
+Some of these useful features are not supported by the standard JavaScript
+`Date` object. The popular [Moment.js](https://momentjs.com/) library has been
+commonly used to fill this gap but suffers from large bundle sizes and mutable
+state issues. On top of this, `momentjs` is
+[being sunset](https://momentjs.com/docs/#/-project-status/) and the project
+recommends using one of the more modern alternative libraries.
+
+See
+[[RFC] Standardized Date & Time Library](https://github.com/backstage/backstage/issues/3401).
+
+## Decision
+
+We will use [Luxon](https://moment.github.io/luxon/index.html) as the standard
+date library within Backstage.
+
+`Luxon` provides a similar feature set and API to `Moment.js`, but improves on
+its design through immutability and the usage of modern JavaScript APIs (e.g.
+`Intl`). This results in smaller bundle sizes while providing a full feature set
+and avoids the need for using additional libraries for common date & time tasks.
+
+## Consequences
+
+- All core packages and plugins within Backstage should use `Luxon` for any date
+  manipulation or formatting that cannot be easily accomplished with the native
+  JavaScript `Date` object.
+- Using a single date library avoids having to learn multiple library APIs
+- Having a single date library will reduce bundle sizes

docs/architecture-decisions/adr011-plugin-package-structure.md

@@ -0,0 +1,74 @@
+---
+id: adrs-adr011
+title: ADR011: Plugin Package Structure
+description: Architecture Decision Record (ADR) for Plugin Package Structure
+---
+
+## Context
+
+A core feature of Backstage is the extensibility via plugins. The Backstage
+repository is open for contributions of plugins. Even most of the core features
+are implemented as plugins. A plugin consists of one or multiple packages in the
+`plugins/` directory. Up till now, we have a simple conventions for naming
+plugin packages: Plugins are named `x`, with the option of having a related
+backend plugin called `x-backend` (where `x` is the plugin name, like `catalog`
+or `techdocs`). There is a need for sharing code between the frontend and
+backend of a plugin, between backend plugins, or components and hooks between
+different frontend plugins
+([some examples](https://github.com/backstage/backstage/issues/3655#issuecomment-758166746)).
+This results in emerging plugin packages with shared code, like
+`packages/catalog-client` or `packages/techdocs-common`.
+
+> There is a common phrase in software development:
+> [Naming things is hard](https://martinfowler.com/bliki/TwoHardThings.html)
+
+To keep the contributed plugins consistent, this Architecture Decision Record
+provides rules for naming plugin packages.
+
+## Decision
+
+We will place all plugin related code in the `plugins/` directory. The
+`packages/` directory is reserved for core package of Backstage.
+
+We follow this structure for plugin packages (where `x` is the plugin name, for
+example `catalog` or `techdocs`):
+
+- `x`: Contains the main frontend code of the plugin.
+- `x-backend`: Contains the main backend code of the plugin.
+- `x-react`: Contains shared widgets, hooks and similar that both the plugin
+  itself (`x`) and third-party frontend plugins can depend on.
+- `x-node`: Contains utilities for backends that both the plugin backend itself
+  (`x-backend`) and third-party backend plugins can depend on.
+- `x-common`: An isomorphic package with platform agnostic models, clients, and
+  utilities that all packages above or any third-party plugin package can depend
+  on.
+
+We prefix the package names with `@backstage/plugin-`.
+
+This structure is based on a
+[suggestion in issue #3655](https://github.com/backstage/backstage/issues/3655#issuecomment-758166746).
+
+## Consequences
+
+We will actively migrate existing packages that are part of a plugin to the
+`plugins/` folder. This affects packages like:
+
+- `packages/techdocs-common` which should be moved to `plugins/techdocs-node`
+  and named `@backstage/plugin-techdocs-node`.
+- `packages/catalog-client` which will be part of a future
+  `plugins/catalog-common` and named `@backstage/plugin-catalog-common`.
+- While the new location of `packages/catalog-model` should be
+  `plugins/catalog-common` we might want to do an exception here, as it's a very
+  central package.
+
+The limited set of rules might not be sufficient in the future. If additional
+packages are required, we will revisit this decision and extend the pattern.
+
+If possible, we will add tools, such as lint rules, to help enforce the package
+names and dependencies between them or CLI commands to generate these packages.
+
+The distinction between core packages and plugins helps us to setup
+[CODEOWNERS](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners)
+in the repository. We can set the code owners for the `packages/` folder to the
+core team and create additional rules (like `plugins/x*`) for plugin
+maintainers.

docs/architecture-decisions/index.md

@@ -18,8 +18,9 @@ Records should be stored under the `architecture-decisions` directory.
 
 ### Creating an ADR
 
-- Copy `0000-template.md` to `docs/architecture-decisions/0000-my-decision.md`
-  (my-decision should be descriptive. Do not assign an ADR number.)
+- Copy `docs/architecture-decisions/adr000-template.md` to
+  `docs/architecture-decisions/adr000-my-decision.md` (my-decision should be
+  descriptive. Do not assign an ADR number.)
 - Fill in the ADR following the guidelines in the template
 - Submit a pull request
 - Address and integrate feedback from the community