Migrate remaining announcements documentation, env sample, and docker…

… compose (#2406)

* Migrate remaining announcements documentation

Signed-off-by: Kurt King <[email protected]>

* migrate env and docker-compose

Signed-off-by: Kurt King <[email protected]>

---------

Signed-off-by: Kurt King <[email protected]>

workspaces/announcements/README.md

@@ -1,16 +1,45 @@
-# [Backstage](https://backstage.io)
+# Announcements plugin for Backstage
 
-This is your newly scaffolded Backstage App, Good Luck!
+The Announcements plugin manages and displays announcements within Backstage.
 
-To start the app, run:
+## Features
 
-```sh
-yarn install
-yarn dev
-```
+This plugin provides:
 
-To generate knip reports for this app, run:
+- a component to display the latest announcement as a banner, if there is one
+- a component to display the latest announcements, for example on a homepage
+- pages to list, view, create, edit and delete announcements
+- an admin portal to manage announcements
+- integration with the [`@backstage/plugin-search`](https://github.com/backstage/backstage/tree/master/plugins/search) plugin
+- integration with the [`@backstage/plugin-permission-backend`](https://github.com/backstage/backstage/tree/master/plugins/permission-backend) plugin
+- integration with the [`@backstage/plugin-events-backend`](https://github.com/backstage/backstage/tree/master/plugins/events-backend) plugin
+- integration with the [`@backstage/plugin-signals-backend`](https://github.com/backstage/backstage/tree/master/plugins/signals-backend) plugin
 
-```sh
-yarn backstage-repo-tools knip-reports
-```
+You will find installation instructions in each plugin's readme file.
+
+## How does it look?
+
+### Latest announcement banner
+
+![Latest announcement banner](./images/announcement_banner.png)
+
+### Announcements card
+
+![Announcements card](./images/announcements_card.png)
+
+### Announcements page
+
+![Announcements page](./images/announcements_page.png)
+
+### Announcements search
+
+![Announcements search results](./images/announcements_search.png)
+
+### Admin Portal
+
+![Announcements admin portal](./images/announcements_admin_portal.png)
+
+## Previously maintained by
+
+- [procore-oss](https://github.com/procore-oss/backstage-plugin-announcements)
+- [K-Phoen](https://github.com/K-Phoen/backstage-plugin-announcements)

workspaces/announcements/docker-compose.yml

@@ -0,0 +1,8 @@
+services:
+  psql:
+    image: postgres
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    ports:
+      - ${POSTGRES_PORT}:5432

workspaces/announcements/env.sample

@@ -0,0 +1,4 @@
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres

workspaces/announcements/plugins/announcements-backend/README.md

@@ -1,14 +1,14 @@
-# announcements
+# announcements-backend
 
-This is the backend for the Announcements plugin. This plugin provides:
+The backend for the Announcements plugin. This plugin provides:
 
 - REST APIs for managing announcements and categories
 - Integration with the [`@backstage/plugin-search`](https://github.com/backstage/backstage/tree/master/plugins/search) plugin
 - Integration with the [`@backstage/plugin-permission-backend`](https://github.com/backstage/backstage/tree/master/plugins/permission-backend) plugin
 
 ## Installation
 
-This plugin is installed via the `@backstage-community/plugin-announcements-backend` package. To install it to your backend package, run the following command:
+To install it to your backend package, run the following command:
 
 ```bash
 # From your root directory

workspaces/announcements/plugins/announcements-node/README.md

@@ -2,6 +2,14 @@
 
 Exports shared types and services for backend-related announcements functionality.
 
+## Events support
+
+The announcements plugin supports the Backstage Event system. View the [events](./docs/events.md) documentation for more information.
+
+## Signals support
+
+The announcements plugin supports the Backstage Signal system. View the [signals](./docs/signals.md) documentation for more information.
+
 ## Previously maintained by
 
 - [procore-oss](https://github.com/procore-oss/backstage-plugin-announcements/tree/main/plugins/announcements-node)

workspaces/announcements/plugins/announcements-node/docs/events.md

@@ -0,0 +1,36 @@
+# Support for events
+
+The announcements plugin supports the Backstage Event system.
+
+```ts
+import { createBackend } from '@backstage/backend-defaults';
+
+const backend = createBackend();
+backend.add(import('@backstage/events-backend'));
+backend.add(import('@backstage-community/plugin-announcements-backend'));
+
+backend.start();
+```
+
+## Topic
+
+All events are published to the `announcements` topic.
+
+## Event actions
+
+The following event actions are supported
+
+### Announcements
+
+All announcement payloads include the entire contents of the announcement
+
+- 'create_announcement': Create a new announcement
+- 'update_announcement': Update an existing announcement
+- 'delete_announcement': Delete an existing announcement
+
+### Categories
+
+All category payloads include the category slug.
+
+- 'create_category': Create a new category
+- 'delete_category': Delete an existing category

workspaces/announcements/plugins/announcements-node/docs/signals.md

@@ -0,0 +1,20 @@
+# Support for signals
+
+The announcements plugin supports delivering announcements to the frontend in near real-time using the [@backstage/plugins-signals](https://github.com/backstage/backstage/tree/master/plugins/signals) plugin. This is currently supported in the `<NewAnnouncementBanner />` [component](../../announcements/docs/latest-announcement-banner.md).
+
+## Installation
+
+> [!IMPORTANT]
+> This feature requires the `@backstage/plugin-events-backend` plugin to be installed and running.
+
+```ts
+import { createBackend } from '@backstage/backend-defaults';
+
+const backend = createBackend();
+backend.add(import('@backstage/events-backend'));
+...
+backend.add(import('@backstage/signals-backend'));
+backend.add(import('@backstage-community/plugin-announcements-backend'));
+
+backend.start();
+```

workspaces/announcements/plugins/announcements/README.md

@@ -1,6 +1,6 @@
 # announcements
 
-This is the frontend for the Announcements plugin. This plugin provides:
+The frontend for the Announcements plugin. This plugin provides:
 
 - a component to display the latest announcements, for example on a homepage
 - pages to list, view, create, edit and delete announcements
@@ -15,7 +15,7 @@ yarn --cwd packages/app add @backstage-community/plugin-announcements
 
 Expose the announcements page:
 
-```ts
+```tsx
 // packages/app/src/App.tsx
 import { AnnouncementsPage } from '@backstage-community/plugin-announcements';
 
@@ -42,7 +42,7 @@ yarn --cwd packages/app add @backstage-community/plugin-announcements
 
 Add the plugin to `packages/app/src/App.tsx`:
 
-```ts
+```tsx
 import announcementsPlugin from '@backstage-community/plugin-announcements/alpha';
 
 // ...
@@ -78,6 +78,54 @@ app:
           filter: kind:component,system,group,api
 ```
 
+## Components
+
+- [Display latest announcements on a page](./docs/latest-announcements-on-page.md)
+- [Display a banner for the latest announcement](./docs/latest-announcement-banner.md)
+- [Display announcements in a timeline](./docs/announcement-timeline.md)
+
+## Customization
+
+### Overriding the AnnouncementCard
+
+It is possible to specify the length of the title for announcements rendered on the `AnnouncementsPage`. You can do this by passing a `cardOptions` prop to the `AnnouncementsPage` component. The `cardOptions` prop accepts an object with the following properties:
+
+```ts
+{
+  titleLength: number; // defaults to 50
+}
+```
+
+Example
+
+```tsx
+<AnnouncementsPage cardOptions={{ titleLength: 10 }} />
+```
+
+### Overriding the AnnouncementsPage
+
+It is possible to specify the Announcements within a specific category rendered on the `AnnouncementsPage`. You can do this by passing a `category` prop to the `AnnouncementsPage` component. The `AnnouncementsPage` prop accepts an value such as:
+
+```ts
+category = 'conferences';
+```
+
+Example
+
+```tsx
+<AnnouncementsPage category="conferences" />
+```
+
+### Overriding the AnnouncementCreateButton
+
+It is possible to specify the text for the "New announcement" button rendered on the `AnnouncementsPage`. You can do this by passing a `buttonOptions` prop to the `AnnouncementsPage` component. The `buttonOptions` prop accepts an object with the following properties:
+
+```ts
+{
+  name: string; // defaults to 'announcement'
+}
+```
+
 ## Development
 
 ### Getting started

workspaces/announcements/plugins/announcements/docs/announcement-timeline.md

@@ -0,0 +1,21 @@
+# Display announcements in a timeline
+
+Adding the `AnnouncementsTimeline` component to a page will display a raw timeline of the latest announcements.
+
+```ts
+import { AnnouncementsTimeline } from '@backstage-community/plugin-announcements';
+
+export const TimelineExampleCard = () => {
+  return (
+    <Content>
+      <Grid container>
+        <Grid item md={6}>
+          <InfoCard>
+            <AnnouncementsTimeline />
+          </InfoCard>
+        </Grid>
+      </Grid>
+    </Content>
+  );
+};
+```

workspaces/announcements/plugins/announcements/docs/latest-announcement-banner.md

@@ -0,0 +1,25 @@
+# Display a banner for the latest announcement
+
+Adding the `NewAnnouncementBanner` component to a page will display a banner with the title and excerpt of the latest unseen announcement. This banner will update in near real-time when a new announcement is created if your Backstage instance is configured to support signals.
+
+**Note:** if there are no announcements or the latest announcement has already been seen by the user, nothing will be displayed.
+
+```ts
+import { NewAnnouncementBanner } from '@backstage-community/plugin-announcements';
+
+export const HomePage = () => {
+  return (
+    <Page themeId="home">
+      <Header title="NewAnnouncementBanner" />
+
+      <Content>
+        <Grid container>
+          <Grid item md={12}>
+            <NewAnnouncementBanner />
+          </Grid>
+        </Grid>
+      </Content>
+    </Page>
+  );
+};
+```

workspaces/announcements/plugins/announcements/docs/latest-announcements-on-page.md

@@ -0,0 +1,24 @@
+# Display latest announcements on a page
+
+Adding the `AnnouncementsCard` component to a page will display a Card with the latest announcements.
+Announcements yet unseen by the user will be prefixed by a specific icon.
+
+```ts
+import { AnnouncementsCard } from '@backstage-community/plugin-announcements';
+
+export const HomePage = () => {
+  return (
+    <Page themeId="home">
+      <Header title="AnnouncementsCard" />
+
+      <Content>
+        <Grid container>
+          <Grid item md={6}>
+            <AnnouncementsCard max={3} />
+          </Grid>
+        </Grid>
+      </Content>
+    </Page>
+  );
+};
+```

workspaces/announcements/plugins/search-backend-module-announcements/docs/search.md

@@ -0,0 +1,50 @@
+# Integration with `@backstage/plugin-search`
+
+## Installation
+
+Add the module to your backend app:
+
+```bash
+yarn add --cwd packages/backend @backstage-community/plugin-search-backend-module-announcements
+```
+
+Update `packages/backend/src/index.ts` to import the announcements search module and register it with the backend:
+
+```ts
+// ...
+const backend = createBackend();
+
+// ...
+
+backend.add(import('@backstage-community/plugin-announcements-backend'));
+backend.add(
+  import('@backstage-community/plugin-search-backend-module-announcements'),
+);
+// ...
+```
+
+## Adding search support to the frontend
+
+```tsx
+import { AnnouncementSearchResultListItem } from '@backstage-community/plugin-announcements';
+import RecordVoiceOverIcon from '@material-ui/icons/RecordVoiceOver';
+
+// ...
+<SearchType.Accordion
+  name="Result Type"
+  defaultValue="software-catalog"
+  types={[
+    // ...
+    {
+      value: 'announcements',
+      name: 'Announcements',
+      icon: <RecordVoiceOverIcon />,
+    },
+  ]}
+/>
+
+<SearchResult>
+  // ...
+  <AnnouncementSearchResultListItem />
+</SearchResult>
+```