From 5502d4d790d397c6587f42fd2e9d90156a822695 Mon Sep 17 00:00:00 2001 From: Marian Steinbach Date: Wed, 19 Mar 2025 15:47:39 +0100 Subject: [PATCH 1/3] Language and formatting improvements in notifications section Signed-off-by: Marian Steinbach --- docs/notifications/index.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/notifications/index.md b/docs/notifications/index.md index 1156db45a7..79c8dfc8f6 100644 --- a/docs/notifications/index.md +++ b/docs/notifications/index.md @@ -8,7 +8,7 @@ The Backstage Notifications System provides a way for plugins and external servi These notifications are displayed in the dedicated page of the Backstage frontend UI or by frontend plugins per specific scenarios. Additionally, notifications can be sent to external channels (like email) via "processors" implemented within plugins. -Notifications can be optionally integrated with the signals (a push mechanism) to ensure users receive them immediately. +Notifications can be optionally extended with the signals plugin, which provides a push mechanism to ensure users receive notifications immediately. ### Upgrade to the latest version of Backstage @@ -27,8 +27,8 @@ There are two basic types of notifications: Example of use-cases: - System-wide announcements or alerts -- Notifications for component owners: e.g., build failures, successful deployments, new vulnerabilities -- Notifications for individuals: e.g., updates you have subscribed to, new required training courses +- Notifications for component owners, e.g. build failures, successful deployments, new vulnerabilities +- Notifications for individuals, e.g. updates you have subscribed to, new required training courses - Notifications pertaining to a particular entity in the catalog: A notification might apply to an entity and the owning team. ## Installation @@ -87,17 +87,17 @@ import { NotificationsPage } from '@backstage/plugin-notifications'; ### Optional: Add Signals -The use of signals is optional but improves user experience. +The use of signals is optional but improves the user experience. #### Optional: Add Signals Backend -Add Signals to your backend by first adding the backend package: +Add signals to your backend by first adding the backend package: ```bash title="From your Backstage root directory" yarn --cwd packages/backend add @backstage/plugin-signals-backend ``` -The add the signals to your backend: +Then add the signals plugin to your backend: ```ts title="packages/backend/src/index.ts" const backend = createBackend(); @@ -156,19 +156,19 @@ add the `UserNotificationSettingsCard` to your frontend. You can customize the origin names shown in the UI by passing an object where the keys are the origins and the values are the names you want to show in the UI. -Each notification processor will receive its own column in the settings page, where the user can enable or disable notifications from that processor. +Each notification processor will receive its own row in the settings page, where the user can enable or disable notifications from that processor. ## Additional info -An example of a backend plugin sending notifications can be found in https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-notifications. +An example of a backend plugin sending notifications can be found in the [`@backstage/plugin-scaffolder-backend-module-notifications` repository](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-notifications). -Sources of the notifications and signal plugins: +Sources of the notifications and signals plugins: -- https://github.com/backstage/backstage/blob/master/plugins/notifications -- https://github.com/backstage/backstage/blob/master/plugins/notifications-backend -- https://github.com/backstage/backstage/blob/master/plugins/notifications-common -- https://github.com/backstage/backstage/blob/master/plugins/notifications-node -- https://github.com/backstage/backstage/blob/master/plugins/signals-backend -- https://github.com/backstage/backstage/blob/master/plugins/signals -- https://github.com/backstage/backstage/blob/master/plugins/signals-node -- https://github.com/backstage/backstage/blob/master/plugins/signals-react +- [notifications](https://github.com/backstage/backstage/blob/master/plugins/notifications) +- [notifications-backend](https://github.com/backstage/backstage/blob/master/plugins/notifications-backend) +- [notifications-common](https://github.com/backstage/backstage/blob/master/plugins/notifications-common) +- [notifications-node](https://github.com/backstage/backstage/blob/master/plugins/notifications-node) +- [signals-backend](https://github.com/backstage/backstage/blob/master/plugins/signals-backend) +- [signals](https://github.com/backstage/backstage/blob/master/plugins/signals) +- [signals-node](https://github.com/backstage/backstage/blob/master/plugins/signals-node) +- [signals-react](https://github.com/backstage/backstage/blob/master/plugins/signals-react) From 0db2c686eb649296665209e11c980792b59848e8 Mon Sep 17 00:00:00 2001 From: Marian Steinbach Date: Wed, 19 Mar 2025 15:52:41 +0100 Subject: [PATCH 2/3] Language and formatting improvements in notifications sub-page Signed-off-by: Marian Steinbach --- docs/notifications/usage.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/notifications/usage.md b/docs/notifications/usage.md index 59fbd83e3b..358426dc21 100644 --- a/docs/notifications/usage.md +++ b/docs/notifications/usage.md @@ -6,7 +6,7 @@ description: How to use the notifications and signals ## Notifications Backend -The Notifications backend plugin provides an API to create notifications, list notifications per logged-in user, and search based on parameters. +The notifications backend plugin provides an API to create notifications, list notifications per logged-in user, and search based on parameters. The plugin uses a relational [database](https://backstage.io/docs/getting-started/config/database) for persistence; no specifics are introduced in this context. @@ -26,7 +26,7 @@ In the `packages/app/src/components/Root/Root.tsx`, tweak the [properties](https ## Usage -New notifications can be sent either by a backend plugin or an external service through the REST API. +New notifications can be sent either by a backend plugin or by an external service through the REST API. ## Backend @@ -71,7 +71,7 @@ await notificationService.send({ }); ``` -Refer the [API documentation](https://github.com/backstage/backstage/blob/master/plugins/notifications-node/report.api.md) for further details. +Consult the [API documentation](https://github.com/backstage/backstage/blob/master/plugins/notifications-node/report.api.md) for further details. ### External Services From 46501e1a051b12969934ad49b88a108ac53ee580 Mon Sep 17 00:00:00 2001 From: Marian Steinbach Date: Mon, 24 Mar 2025 11:50:18 +0100 Subject: [PATCH 3/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Marian Steinbach --- docs/notifications/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/notifications/index.md b/docs/notifications/index.md index 79c8dfc8f6..2af8879ac0 100644 --- a/docs/notifications/index.md +++ b/docs/notifications/index.md @@ -160,7 +160,7 @@ Each notification processor will receive its own row in the settings page, where ## Additional info -An example of a backend plugin sending notifications can be found in the [`@backstage/plugin-scaffolder-backend-module-notifications` repository](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-notifications). +An example of a backend plugin sending notifications can be found in the [`@backstage/plugin-scaffolder-backend-module-notifications` package](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend-module-notifications). Sources of the notifications and signals plugins: