docs/releases/v1.2.0-changelog.md
TechDocsAddonTester class may now be extended if custom test configuration is needed.buildAddonsInTechDocs().withApis() from being called with multiple partial API implementations.5f4dbd2b52: A package for contributed TechDocs addons.
In this release it will introduce the ReportIssue addon, which lets you select text and open a GitHub/Gitlab issue.
10d86dedc0: Improved inline/type documentation for the <ReportIssue /> addon.
52419be116: Create a TechDocs <TextSize/> addon that allows users to set a font size in the browser's local storage for the text of documentation pages.
Here's an example on how to use it in a Backstage app:
import {
DefaultTechDocsHome,
TechDocsIndexPage,
TechDocsReaderPage,
} from '@backstage/plugin-techdocs';
import { TechDocsAddons } from '@backstage/plugin-techdocs-react/alpha';
+import { TextSize } from '@backstage/plugin-techdocs-module-addons-contrib';
const AppRoutes = () => {
<FlatRoutes>
// other plugin routes
<Route path="/docs" element={<TechDocsIndexPage />}>
<DefaultTechDocsHome />
</Route>
<Route
path="/docs/:namespace/:kind/:name/*"
element={<TechDocsReaderPage />}
>
<TechDocsAddons>
+ <TextSize />
</TechDocsAddons>
</Route>
</FlatRoutes>;
};
075a9a067b: Updated the return type of createTechDocsAddonExtension to better reflect the fact that passing children to Addon components is not a valid use-case.
c25e880e36: Introducing the Expandable Navigation addon, which lets you expand and collapse the TechDocs main navigation and store your preference in local storage.
Updated dependencies
52419be116: Create a new addon location called "Settings", it is designed for addons that allow users to customize the reading experience in documentation pages.
Usage example:
const TextSize = techdocsModuleAddonsContribPlugin.provide(
createTechDocsAddonExtension({
name: 'TextSize',
location: TechDocsAddonLocations.Settings,
component: TextSizeAddon,
}),
);
c25e880e36: Added overload signatures for createTechDocsAddonExtension to handle TechDocs addons without props.
52fddad92d: The TechDocsStorageApi and its associated ref are now exported by @backstage/plugin-techdocs-react. The API interface, ref, and types are now deprecated in @backstage/plugin-techdocs and will be removed in a future release.
075a9a067b: Updated the return type of createTechDocsAddonExtension to better reflect the fact that passing children to Addon components is not a valid use-case.
Updated dependencies
e295ce87de: added the possibility to handle raw Gitlab URLs with nested namespaces
6673babab9: Gerrit UrlReader: Implemented readTree
1b4e1e2306: Split bitbucket integration into bitbucketCloud and bitbucketServer
(backwards compatible).
In order to migrate to the new integration configs,
move your configs from integrations.bitbucket
to integrations.bitbucketCloud or integrations.bitbucketServer.
Migration example:
Before:
integrations:
bitbucket:
- host: bitbucket.org
username: bitbucket_user
appPassword: app-password
- host: bitbucket-server.company.com
token: my-token
After:
integrations:
bitbucketCloud:
- username: bitbucket_user
appPassword: app-password
bitbucketServer:
- host: bitbucket-server.company.com
token: my-token
566407bf8a: Gerrit Integration: Added the getGerritProjectsApiUrl function
1b4e1e2306: Split bitbucket integration into bitbucketCloud and bitbucketServer
(backwards compatible).
In order to migrate to the new integration configs,
move your configs from integrations.bitbucket
to integrations.bitbucketCloud or integrations.bitbucketServer.
Migration example:
Before:
integrations:
bitbucket:
- host: bitbucket.org
username: bitbucket_user
appPassword: app-password
- host: bitbucket-server.company.com
token: my-token
After:
integrations:
bitbucketCloud:
- username: bitbucket_user
appPassword: app-password
bitbucketServer:
- host: bitbucket-server.company.com
token: my-token
renderWithEffects, which if forwarded to the render function from @testling-library/react. Initially only the wrapper option is supported.createTestAppWrapper, which returns a component that can be used as the wrapper option for render or renderWithEffects.renderInTestApp so that it is able to re-render the result without removing the app wrapping.Routes element to wrap the Route elements of the test app wrapping.mountedRoutes implementation are now hidden during rendering.disableRefresh option from OAuthAdapter. Refresh can still be disabled for a provider by not implementing the refresh method.cac3ba68a2: Fixed a bug that was introduced in 0.13.1-next.0 which caused the ent claim of issued tokens to be dropped.
5d268623dd: Updates the OAuth2 Proxy provider to require less infrastructure configuration.
The auth result object of the OAuth2 Proxy now provides access to the request headers, both through the headers object as well as getHeader method. The existing logic that parses and extracts the user information from ID tokens is deprecated and will be removed in a future release. See the OAuth2 Proxy provider documentation for more details.
The OAuth2 Proxy provider now also has a default authHandler implementation that reads the display name and email from the incoming request headers.
2df2f01a29: The Auth0 adapter no longer disables session refreshing.
cfc0f19699: Updated dependency fs-extra to 10.1.0.
787ae0d541: Add more common predefined sign-in resolvers to auth providers.
Add the existing resolver to more providers (already available at google):
providers.microsoft.resolvers.emailLocalPartMatchingUserEntityName()providers.okta.resolvers.emailLocalPartMatchingUserEntityName()Add a new resolver for simple email-to-email matching:
providers.google.resolvers.emailMatchingUserEntityProfileEmail()providers.microsoft.resolvers.emailMatchingUserEntityProfileEmail()providers.okta.resolvers.emailMatchingUserEntityProfileEmail()9ec4e0613e: Update to jose 4.6.0
Updated dependencies
NotFoundComponent to EntityLayout which can be used to include a custom component when an entity is not found in the catalogplugin-catalog-backend-module-gerrit pluginpublishConfigfs-extra to 10.1.0.https?:// are rendered as links as well.EntityTypeFilter so generating available types is case insensitive@testing-library/user-event to ^14.0.0.rc-progress to 3.3.2.use-immer to ^0.7.0.@codemirror/legacy-modes to ^0.20.0.9818112d12: Update the github:publish action to allow passing required status check
contexts before merging to the main branch.
f8baf7df44: Added the ability to reference the user in the template.yaml manifest
8d5a2238a9: Split publish:bitbucket into publish:bitbucketCloud and publish:bitbucketServer.
In order to migrate from the deprecated action, you need to replace the use of action
publish:bitbucket in your templates with the use of either publish:bitbucketCloud
or publish:bitbucketServer - depending on which destination SCM provider you use.
Additionally, these actions will not utilize integrations.bitbucket anymore,
but integrations.bitbucketCloud or integrations.bitbucketServer respectively.
You may or may not have migrated to these already.
As described in a previous changeset, using these two replacement integrations configs
will not compromise use cases which still rely on integrations.bitbucket as this was
set up in a backwards compatible way.
Additionally, please mind that the option enableLFS is only available (and always was)
for Bitbucket Server use cases and therefore, is not even part of the schema for
publish:bitbucketCloud anymore.
fs-extra to 10.1.0.allowedImageNames option, which needs to list any image name for it to be allowed as imageName input.template.yaml manifestbdbe620797: BREAKING: SearchContextProviderForStorybook and SearchApiProviderForStorybook has been deleted. New mock implementation of the SearchApi introduced. If you need to mock the api we recommend you to do the following:
import {
searchApiRef,
MockSearchApi,
SearchContextProvider,
} from '@backstage/plugin-search-react';
import { TestApiProvider } from '@backstage/test-utils';
<TestApiProvider apis={[[searchApiRef, new MockSearchApi()]]}>
<SearchContextProvider>
<Component />
</SearchContextProvider>
</TestApiProvider>;
useSearchContextCheck hook to check if the search context is available@backstage/core-app-api.3333e20b27: BREAKING: The buildTechInsightsContext function now takes an additional
field in its options argument: tokenManager. This is an instance of
TokenManager, which can be found in your backend initialization code's
env.
const builder = buildTechInsightsContext({
logger: env.logger,
config: env.config,
database: env.database,
discovery: env.discovery,
scheduler: env.scheduler,
+ tokenManager: env.tokenManager,
factRetrievers: [ /* ... */ ],
});
FactRetrieverContext type now contains an additional
field: tokenManager.e0a6360b80: Added a stream() method to complement the buffer() method on ReadUrlResponse. A ReadUrlResponseFactory utility class is now also available, providing a simple, consistent way to provide a valid ReadUrlResponse.
This method, though optional for now, will be required on the responses of UrlReader.readUrl() implementations in a future release.
4b811aafce: Implemented the UrlReader.search() method for Google Cloud Storage. Due to limitations in the underlying storage API, only prefix-based searches are supported right now (for example, https://storage.cloud.google.com/your-bucket/some-path/*).
6673babab9: Gerrit integration: Added optional cloneUrl string to config.
75bf9e1da9: Split BitbucketUrlReader into BitbucketCloudUrlReader and BitbucketServerUrlReader. Backwards compatible.
28b0e4ddef: Update types to match the new version of @keyv/redis
5fcbd86960: DEPRECATION: Server-to-server authentication tokens issued from a
TokenManager (specifically, ServerTokenManager) now has an expiry time set,
for one hour in the future from when issued. This improves security. The ability
to pass in and validate tokens that either have a missing exp claim, or an
exp claim that expired in the past, is now deprecated. Trying to do so will
lead to logged warnings, and in a future release will instead lead to errors.
It was always the case that users of this interface were expected to call its
getToken() method for every outgoing call and never hold on to any given token
for reuse. But this now has become even more important advice to heed, and you
should verify that you do not hold on to and reuse tokens such as these in your
own code.
cfc0f19699: Updated dependency fs-extra to 10.1.0.
9ec4e0613e: Update to jose 4.6.0
Updated dependencies
73480846dd: TaskScheduleDefinition has been updated to also accept an options object containing duration information in the form of days, hours, seconds and so on. This allows for scheduling without importing luxon.
-import { Duration } from 'luxon';
// omitted other code
const schedule = env.scheduler.createScheduledTaskRunner({
- frequency: Duration.fromObject({ minutes: 10 }),
- timeout: Duration.fromObject({ minutes: 15 }),
+ frequency: { minutes: 10 },
+ timeout: { minutes: 15 },
// omitted other code
});
cfd779a9bc: Scheduled tasks now have an optional scope field. If unset, or having the
value 'global', the old behavior with cross-worker locking is retained. If
having the value 'local', there is no coordination across workers and the
behavior is more like setInterval. This can be used to replace usages of
runPeriodically helpers.
ebbec677e1: Correctly set next run time for tasks
Updated dependencies
BACKSTAGE_NEXT_TESTS.create-github-app command.css,
scss, sass, svg, eot, woff, woff2 and ttf files.fs-extra to 10.1.0.commander to version 9.1.0create-github-app command to throw an error if the organization argument is a user or a non existing organization.create-github-app command to prompt for read or write permissions to simplify setup.@types/node to ^16.0.0.commander to version 9.1.0@types/node to ^16.0.0.fs-extra to 10.1.0.<main> to Page component and added ARIA landmark <nav> to DesktopSidebar and Sidebar componentsRead More destination with readMoreUrl prop for MissingAnnotationEmptyState component.@types/react-syntax-highlighter to ^15.0.0.rc-progress to 3.3.2.<main>), & label and a heading to OAuthRequestDialog. Removed nested interactive control (button).SidebarSubmenuItem dropdown items on hover, use ellipsis styling on long labels in SidebarSubmenu, allow icon and to properties to be optional on SidebarSubmenuItem, and fix SidebarPage padding to be responsive to pinned state@alpha. Since the @backstage/core-plugin-api has no /alpha entrypoint, the only effect of marking the APIs as @alpha was to hide them in documentation. They are still expected to be widely used and there will be a migration path if they are changed in the future.73480846dd: Simplified the search collator scheduling by removing the need for the luxon dependency.
For existing installations the scheduling can be simplified by removing the luxon dependency and using the human friendly duration object instead.
Please note that this only applies if luxon is not used elsewhere in your installation.
packages/backend/package.json
"express": "^4.17.1",
"express-promise-router": "^4.1.0",
- "luxon": "^2.0.2",
packages/backend/src/plugins/search.ts
import { Router } from 'express';
-import { Duration } from 'luxon';
// omitted other code
const schedule = env.scheduler.createScheduledTaskRunner({
- frequency: Duration.fromObject({ minutes: 10 }),
- timeout: Duration.fromObject({ minutes: 15 }),
+ frequency: { minutes: 10 },
+ timeout: { minutes: 15 },
// A 3 second delay gives the backend server a chance to initialize before
// any collators are executed, which may attempt requests against the API.
- initialDelay: Duration.fromObject({ seconds: 3 }),
+ initialDelay: { seconds: 3 },
});
7cda923c16: Tweaked the .dockerignore file so that it's easier to add additional backend packages if desired.
To apply this change to an existing app, make the following change to .dockerignore:
cypress
microsite
node_modules
-packages
-!packages/backend/dist
+packages/*/src
+packages/*/node_modules
plugins
3983940a21: Optimized the command order in packages/backend/Dockerfile as well as added the --no-install-recommends to the apt-get install and tweaked the installed packages.
To apply this change to an existing app, update your packages/backend/Dockerfile to match the documented Dockerfile at https://backstage.io/docs/deployment/docker#host-build.
28bbf5aff6: Added some instruction comments to the generated config files, to clarify the
usage of backend.baseUrl and backend.listen.host. Importantly, it also per
default now listens on all IPv4 interfaces, to make it easier to take the step
over to production. If you want to do the same, update your
app-config.production.yaml as follows:
backend:
listen:
port: 7007
+ host: 0.0.0.0
Also, updated the builtin backend Dockerfile to honor the
app-config.production.yaml file. If you want to do the same, change
packages/backend/Dockerfile as follows:
-COPY packages/backend/dist/bundle.tar.gz app-config.yaml ./
+COPY packages/backend/dist/bundle.tar.gz app-config*.yaml ./
RUN tar xzf bundle.tar.gz && rm bundle.tar.gz
-CMD ["node", "packages/backend", "--config", "app-config.yaml"]
+CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.production.yaml"]
If you look carefully, this adds a glob match on app-config files. For those
that try out the build flows locally, you also want to make sure that the docker
daemon does NOT pick up any local/private config files that might contain
secrets. You should therefore also update your local .dockerignore file at the
same time:
+*.local.yaml
7b253072c6: Tweaked template to provide an example and guidance for how to configure sign-in in packages/backend/src/plugins/auth.ts. There is no need to add this to existing apps, but for more information about sign-in configuration, see https://backstage.io/docs/auth/identity-resolver.
cfc0f19699: Updated dependency fs-extra to 10.1.0.
f55414f895: Added sample catalog data to the template under a top-level examples directory. This includes some simple entities, org data, and a template. You can find the sample data at https://github.com/backstage/backstage/tree/master/packages/create-app/templates/default-app/examples.
344ea56acc: Bump commander to version 9.1.0
00fa0dada0: Removed the database choice from the create-app command.
This reduces the step from development to production by always installing the dependencies and templating the production configuration in app-config.production.yaml.
Added app-config.local.yaml to allow for local configuration overrides.
To replicate this behavior in an existing installation simply touch app-config.local.yaml in the project root and apply your local configuration.
better-sqlite3 has been moved to devDependencies, for existing installations using postgres in production and SQLite in development it's recommended to move SQLite into the devDependencies section to avoid unnecessary dependencies during builds.
in packages/backend/package.json
"dependencies": {
...
"pg": "^8.3.0",
- "better-sqlite3": "^7.5.0",
"winston": "^3.2.1"
},
"devDependencies": {
...
"@types/luxon": "^2.0.4",
+ "better-sqlite3": "^7.5.0"
}
10d86dedc0: Integrates TechDocs add-ons with the app package so add-ons are configured when creating an app using the Backstage CLI. To apply these changes to an existing application do the following:
@backstage/plugin-techdocs-react and @backstage/plugin-techdocs-module-addons-contrib packages to your app's dependencies;<ReportIssue/ > Addon in your packages/app/src/App.tsx file, there where you define a route to <TechDocsReaderPage />:import {
DefaultTechDocsHome,
TechDocsIndexPage,
TechDocsReaderPage,
} from '@backstage/plugin-techdocs';
+ import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
+ import { ReportIssue } from '@backstage/plugin-techdocs-module-addons-contrib';
// ...
const AppRoutes = () => {
<FlatRoutes>
// ... other plugin routes
<Route path="/docs" element={<TechDocsIndexPage />}>
<DefaultTechDocsHome />
</Route>
<Route
path="/docs/:namespace/:kind/:name/*"
element={<TechDocsReaderPage />}
>
+ <TechDocsAddons>
+ <ReportIssue />
+ </TechDocsAddons>
</Route>
</FlatRoutes>;
};
806427545f: Added a link to the ${GITHUB_TOKEN} to document how to generate a token
3a74e203a8: Implement highlighting matching terms in search results. To enable this for an existing app, make the following changes:
// packages/app/src/components/search/SearchPage.tsx
...
- {results.map(({ type, document }) => {
+ {results.map(({ type, document, highlight }) => {
switch (type) {
case 'software-catalog':
return (
<CatalogSearchResultListItem
key={document.location}
result={document}
+ highlight={highlight}
/>
);
case 'techdocs':
return (
<TechDocsSearchResultListItem
key={document.location}
result={document}
+ highlight={highlight}
/>
);
default:
return (
<DefaultResultListItem
key={document.location}
result={document}
+ highlight={highlight}
/>
);
}
})}
...
d41f19ca2a: Bumped the typescript version in the template to ~4.6.4.
To apply this change to an existing app, make the following change to the root package.json:
dependencies: {
...
- "typescript": "~4.5.4"
+ "typescript": "~4.6.4"
},
Updated dependencies
@types/node to ^16.0.0.@types/node to ^16.0.0.commander to version 9.1.0@backstage/plugin-techdocs-react package.techdocs-cli serve's proxyEndpoint to match the base URL of the embedded techdocs app.graphiql to ^1.8.8.@asyncapi/react-component to 1.0.0-next.37.@asyncapi/react-component to 1.0.0-next.38.graphql-ws to fix the latest release of @graphiql/toolkit that has a missing dependencyfs-extra to 10.1.0.jose 4.6.0isGroupEntity function.knex when checking returned rowsfs-extra to 10.1.0.PermissionEvaluator instance check that would cause unexpected "invalid union" errors.bffec1c96a: Fix S3 object URL creation at AwsS3EntityProvider by
Updated dependencies
a7de43f648: GitHubOrgEntityProvider.fromConfig now supports a schedule option like other
entity providers, that makes it more convenient to leverage using the common
task scheduler.
If you want to use this in your own project, it is used something like the following:
// In packages/backend/src/plugins/catalog.ts
builder.addEntityProvider(
GitHubOrgEntityProvider.fromConfig(env.config, {
id: 'production',
orgUrl: 'https://github.com/backstage',
schedule: env.scheduler.createScheduledTaskRunner({
frequency: { cron: '*/30 * * * *' },
timeout: { minutes: 10 },
}),
logger: env.logger,
}),
);
Updated dependencies
8d9f673106: Add annotation microsoft.com/email when using the defaultUserTransformer.
This will allow users of the Microsoft auth provider to utilize the predefined SignIn resolver instead of maintaining their own.
// backend/plugins/auth.ts
// [...]
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return await createRouter({
// [...]
providerFactories: {
microsoft: providers.microsoft.create({
signIn: {
resolver:
providers.microsoft.resolvers.emailMatchingUserEntityAnnotation(),
},
}),
},
});
}
Updated dependencies
@types/codemirror to ^5.0.0.@types/codemirror to ^0.0.109.graphql-ws to fix the latest release of @graphiql/toolkit that has a missing dependencyStarredEntities home page card (if defined) and don't show entities which no longer existPermissionEvaluator instance check that would cause unexpected "invalid union" errors.fs-extra to 10.1.0.FetchApi and related fetchApiRef which implement fetch. in order to included the Authorization Token to New Relic Dashboard Plugin, so that frontend can send an authenticated proxy call to backendMyGroupSidebarItem if not default and remove root item routing if there are multiple groupsfs-extra to 10.1.0.fs-extra to 10.1.0.HomePageSearchBar requiring SearchContext<SearchModalProvider>, which can optionally be placed higher up in the react tree in order to allow control of search modal visibility from outside the modal itself.PermissionEvaluator instance check that would cause unexpected "invalid union" errors.nextPageCursor is defined on the last page of resultsrc-progress to 3.3.2.EntityTechInsightsScorecardCard, which can be used in the overview of the EntityPage page or display multiple individual EntityTechInsightsScorecardCard in EntityLayout.Route.buildTechInsightsContext in README.use to adopt, to reflect Zalando Tech Radar regarding quadrants and add link to Zalando explanation.@backstage/core-app-api.sub-route path on the EntityDocs page to fix the blank screen error when navigating using sidebar links.bota with extended charactersTechDocsStorageApi and its associated ref are now exported by @backstage/plugin-techdocs-react. The API interface, ref, and types are now deprecated in @backstage/plugin-techdocs and will be removed in a future release.fs-extra to 10.1.0.search_index.json was empty.fs-extra to 10.1.0.@spotify/techdocs container used when techdocs.generator.runIn is docker to v1.0.3.