Skip to content

Commit 650d42a

Browse files
openshift-cherrypick-robotpabel-rh
openshift-cherrypick-robot
and
pabel-rh
authored
[release-1.6] RHIDP-6144: Developer-focused content for software catalogs (#1163)
* Added content for software catalogs * Incorporated Heena's comments * Incorporated Lindsey's comments * To maintain consistency with the templates * Incorporated Lindsey's comments * Adding manually * Incorporated Ben's comments * Incorporated Judy's comments * Incorporated Fabrice's comments * Removed level 2 headings --------- Co-authored-by: Priyanka Abel <[email protected]>
1 parent be535a1 commit 650d42a

9 files changed

+231
-0
lines changed

‎assemblies/assembly-about-software-catalogs.adoc

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
:context: about-software-catalogs
3+
[id="{context}"]
4+
= About Software Catalogs
5+
6+
The {product} Software Catalog is a centralized system that gives you visibility into all the software across your ecosystem, including services, websites, libraries, and data pipelines. You can use it to view ownership details and metadata for each component in one place.
7+
8+
The metadata for the components in your Software Catalog is stored as YAML files that live alongside your code in your version control system. The version control repositories can include one or many metadata files. Software Catalog organizes items as entities, which include Components, Resources, and APIs, and other related types. Each entity includes associated metadata such as its owner, type, and other relevant details.
9+
10+
By storing metadata in YAML files alongside the code, you allow {product} to process and display this information through a clear, visual interface. With the Software Catalog, you can manage and maintain your software, stay aware of all software available in your ecosystem, and take ownership of your services and tools.
11+
12+
//[Add a Software Catalog screenshot of the latest build]
13+
14+
The *Overview* page for a component provides key information such as links to the source code, documentation, dependencies, and ownership details. You can customize this page with plugins to suit specific needs.
15+
16+
//[Add any Component screenshot of the latest build]
17+
18+
include::modules/software-catalogs/proc-adding-new-components-to-the-rhdh-instance.adoc[leveloffset=+1]
19+
20+
include::modules/software-catalogs/proc-creating-new-components-in-the-rhdh-instance.adoc[leveloffset=+2]
21+
22+
include::modules/software-catalogs/proc-registering-components-manually-in-the-rhdh-instance.adoc[leveloffset=+2]
23+
24+
include::modules/software-catalogs/proc-updating-components-in-the-software-catalog.adoc[leveloffset=+1]
25+
26+
include::modules/software-catalogs/proc-searching-and-filter-software-catalogs.adoc[leveloffset=+1]
27+
28+
include::modules/software-catalogs/proc-viewing-software-catalog-yaml.adoc[leveloffset=+1]
29+
30+
include::modules/software-catalogs/proc-starring-components-in-the-software-catalog.adoc[leveloffset=+1]

‎modules/software-catalogs/proc-adding-new-components-to-the-rhdh-instance.adoc

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-about-software-catalogs.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-adding-new-components-to-the-rhdh-instance_{context}"]
7+
= Adding new components to your {product} instance
8+
9+
.Prerequisites
10+
11+
* You have installed and configured the {product} instance.
12+
* You have the required permissions. See link:{authorization-book-url}[{authorization-book-title}].
13+
14+
.Procedure
15+
16+
You can add components to your {product-very-short} instance using the following methods:
17+
18+
* Register components manually using the GUI or by using your `{my-app-config-file}` with the required permissions.
19+
* Create new components by using Software Templates.
20+
* Use the bulk import plugin with the required permissions. For more information, see link:{configuring-dynamic-plugins-book-url}#bulk-importing-github-repositories[the bulk import plugin].

‎modules/software-catalogs/proc-creating-new-components-in-the-rhdh-instance.adoc

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-about-software-catalogs.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-creating-new-components-in-the-rhdh-instance_{context}"]
7+
== Creating new components in your {product} instance
8+
9+
You can create new components in the Software Catalog in your {product-very-short} instance. {product} automatically registers all components that developers or platform engineers create using Templates in the Software Catalog.
10+
11+
.Prerequisites
12+
13+
* You have installed and configured the {product} instance.
14+
* You have the required permissions. See link:{authorization-book-url}[{authorization-book-title}].
15+
16+
.Procedure
17+
18+
. In your {product} navigation menu, click *Catalog*.
19+
. On the *Catalog* page, click *Self-service*.

‎modules/software-catalogs/proc-registering-components-manually-in-the-rhdh-instance.adoc

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-about-software-catalogs.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-registering-components-manually-in-the-rhdh-instance_{context}"]
7+
= Registering components manually in your {product-very-short} instance
8+
9+
To manually register components in your {product-very-short} instance, create a `catalog-info.yaml` file and register it with your {product} instance. The `catalog-info.yaml` file contains the metadata you wish to register for your software component.
10+
11+
.Prerequisites
12+
13+
* You have installed and configured the {product} instance.
14+
* You have the required permissions. See link:{authorization-book-url}[{authorization-book-title}].
15+
16+
.Procedure
17+
18+
. In the root directory of your software project, create a file named `catalog-info.yaml`.
19+
+
20+
.Example of a `catalog-info.yaml` file
21+
[source,yaml]
22+
----
23+
apiVersion: backstage.io/v1alpha1
24+
kind: Component
25+
metadata:
26+
name: _<your_software_component>_
27+
description: _<software_component_brief_description>_
28+
tags:
29+
- example
30+
- service
31+
annotations:
32+
github.com/project-slug: _<repo_link_of_your_component_to_register>_
33+
spec:
34+
type: _<your_service>_
35+
owner: _<your_team_name>_
36+
lifecycle: _<your_lifecycle>_
37+
----
38+
. Commit the `catalog-info.yaml` file to the root of your project source code repository.
39+
. In your {product} navigation menu, go to *Catalog* > *Self-service*.
40+
. On the *Self-service* page, click *Register Existing Component*.
41+
. On the *Register an existing component* page, enter the full URL of the `catalog-info.yaml` file in your repository. For example: link:https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml[Artist lookup component].
42+
. Complete the wizard instructions.
43+
44+
.Verification
45+
46+
* Your software component is listed in the Software Catalog. You can view its details and ensure all the metadata is accurate.

‎modules/software-catalogs/proc-searching-and-filter-software-catalogs.adoc

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-about-software-catalogs.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-searching-and-filtering-software-catalogs_{context}"]
7+
= Searching and Filtering Software Catalogs
8+
9+
You can search and filter Software Catalogs by its *Kind* or by using the *Filter* field.
10+
11+
== Searching and Filtering Software Catalogs by Kind
12+
13+
To filter a Software Catalog by its *Kind*, complete the following steps:
14+
15+
.Procedure
16+
17+
. In your {product} navigation menu, click *Catalog*.
18+
. On the *Catalog* page, click the *Kind* drop-down list.
19+
. Select the type of *Kind* you want to filter.
20+
+
21+
[NOTE]
22+
====
23+
The available filter dropdowns vary based on the *Kind* you select, displaying options relevant to that specific entity type.
24+
====
25+
26+
== Searching and Filtering Software Catalogs using the Filter field
27+
28+
To filter a Software Catalog using the *Filter* field, complete the following steps:
29+
30+
.Procedure
31+
32+
. In your {product} navigation menu, click *Catalog*.
33+
. In the *Search* box, enter the text you want to use to filter the components.

‎modules/software-catalogs/proc-starring-components-in-the-software-catalog.adoc

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-about-software-catalogs.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-starring-components-in-the-software-catalog_{context}"]
7+
= Starring components in the Software Catalog
8+
9+
10+
You can use the *Add to favorites* icon to add the software catalogs that you visit regularly to the *Starred* category.
11+
12+
.Procedure
13+
14+
To quickly access the Software Catalogs that you visit regularly, complete the following steps:
15+
16+
. In your {product} navigation menu, click *Catalog*.
17+
. Find the software component that you want to add as a favorite, then click the *Add to favorites* icon under *Actions*.
18+
19+
.Verification
20+
21+
* The starred component is listed under *Your Starred Entities* on your *Home* page.

‎modules/software-catalogs/proc-updating-components-in-the-software-catalog.adoc

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-about-software-catalogs.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-updating-components-in-the-software-catalog_{context}"]
7+
= Updating components in the Software Catalog in your {product} instance
8+
9+
You can update components in the Software Catalog in your {product} instance.
10+
11+
.Prerequisites
12+
13+
* You have installed and configured the {product} instance.
14+
* You have the required permissions. See link:{authorization-book-url}[{authorization-book-title}].
15+
16+
.Procedure
17+
18+
To update components in the Software Catalog in your {product} instance, complete the following steps:
19+
20+
. In your {product} navigation menu, click *Catalog*.
21+
. Find the software component that you want to edit, then click the *Edit* icon under *Actions*.
22+
23+
+
24+
[NOTE]
25+
====
26+
This action redirects you to the YAML file on GitHub.
27+
====
28+
29+
. On your remote repository UI, update your YAML file.
30+
31+
+
32+
[NOTE]
33+
====
34+
After you merge your changes, the updated metadata in the Software Catalog appears after some time.
35+
====

‎modules/software-catalogs/proc-viewing-software-catalog-yaml.adoc

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-about-software-catalogs.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-viewing-software-catalog-yaml_{context}"]
7+
= Viewing the Software Catalog YAML file in your {product} instance
8+
9+
You can view the Software Catalog YAML file in your {product} instance. The YAML file displays the metadata for the components in your Software Catalog.
10+
11+
.Procedure
12+
13+
To view the Software Catalog YAML file in your {product} instance, complete the following steps:
14+
15+
. In your {product} navigation menu, click *Catalog*.
16+
. Find the software component that you want to view, then click the *View* icon under *Actions*.
17+
18+
+
19+
[NOTE]
20+
====
21+
These steps redirect you to the YAML file on your remote repository.
22+
====

‎titles/customizing/master.adoc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,17 @@ include::modules/customizing/proc-customizing-the-backend-secret.adoc[leveloffse
2020
include::assemblies/assembly-configuring-templates.adoc[leveloffset=+1]
2121

2222

23+
include::assemblies/assembly-about-software-catalogs.adoc[leveloffset=+1]
24+
25+
2326
include::assemblies/assembly-customizing-the-learning-paths.adoc[leveloffset=+1]
2427

2528
include::assemblies/assembly-configuring-the-global-header.adoc[leveloffset=+1]
2629

30+
2731
include::assemblies/assembly-configuring-a-floating-action-button.adoc[leveloffset=+1]
2832

33+
2934
include::assemblies/assembly-customizing-the-tech-radar-page.adoc[leveloffset=+1]
3035

3136

0 commit comments

Comments
 (0)