Skip to content

RHIDP-6144: Developer-focused content for software catalogs #1094

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

RHIDP-6144: Developer-focused content for software catalogs #1094

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1ae53ac
Added content for software catalogs
pabel-rh Apr 24, 2025
5b87c73
Incorporated Heena's comments
pabel-rh Apr 24, 2025
6996de2
Incorporated Lindsey's comments
pabel-rh Apr 24, 2025
6e9293a
To maintain consistency with the templates
pabel-rh Apr 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions assemblies/assembly-about-software-catalogs.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
:_mod-docs-content-type: ASSEMBLY
:context: about-software-catalogs
[id="{context}"]
= About Software Catalogs

The {product} Software Catalog is a centralized system that gives you visibility into all the software across your ecosystem from services, websites, libraries, data pipelines, and more. You can use it to view ownership details and metadata for each component in one place. 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.

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.

//[Add a Software Catalog screenshot of the latest build]

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.

//[Add any Component screenshot of the latest build]

include::modules/software-catalogs/proc-adding-new-components-to-the-rhdh-instance.adoc[leveloffset=+1]
include::modules/software-catalogs/proc-updating-components-in-the-software-catalog.adoc[leveloffset=+1]
include::modules/software-catalogs/proc-searching-and-filter-software-catalogs.adoc[leveloffset=+1]
include::modules/software-catalogs/proc-viewing-software-catalog-yaml.adoc[leveloffset=+1]
include::modules/software-catalogs/proc-starring-components-in-the-software-catalog.adoc[leveloffset=+1]
52 changes: 52 additions & 0 deletions modules/software-catalogs/proc-adding-new-components-to-the-rhdh-instance.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
// Module included in the following assemblies:
//
// * assemblies/assembly-about-software-catalogs.adoc

:_mod-docs-content-type: PROCEDURE
[id="proc-adding-new-components-to-the-rhdh-instance_{context}"]
= Adding new components to your {product} instance

You can add components to your {product-short} instance using the following ways:

.Prerequisites

* You have installed the {product} instance.
* You have the required permissions. See link:{authorization-book-url}[{authorization-book-title}].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is fine if you are currently having challenges getting this info from a SME, but ideally, we would directly tell the user what permissions they need to perform this procedure

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, Lindsey!


.Procedure

* Register components manually using the GUI or through your `{my-app-config-file}` with the required permissions.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We already mention the required permissions in the prereq and having the required perms is a given, so you can remove this part:

with the required permissions

Also, it would be good to orient the user. What GUI? Is "use the GUI" intuitive enough or do we need to separately walk the user through the GUI steps? Does the user have enough info to know how to register components by using the file or could they use an example?

Lastly, IBM style guide advises us not to use through to mean by using. (https://www.ibm.com/docs/en/ibm-style?topic=word-usage#t)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure! I've replaced "through" with "by using".
But yes, I need to expand more on what we mean by "GUI".

* Create new components through Software Templates.
* 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].

== Registering components manually in your {product-very-short} instance
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to modularize this content now or later. If later, please coordinate with @themr0c to create a Jira ticket to modularize this in the future.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, Lindsey!


To register components in the Software Catalog manually in your {product-very-short} instance, complete the following steps:

.Prerequisites

* You have installed the {product} instance.
* You have the required permissions. See link:{authorization-book-url}[{authorization-book-title}].

.Procedure

. In your {product} instance, go to *Home > Catalog*.
. On the Catalog page, click *Register Existing Component*.
. On the Register an existing component page, enter the full URL to the YAML file you wish to register. For example: link:https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml[Artist lookup component].
. Complete the wizard instructions.

== Creating new components in your {product} instance

You can create new components in the Software Catalog in your {product-very-short} instance.

.Prerequisites

* You have installed the {product} instance.
* You have the required permissions See link:{authorization-book-url}[{authorization-book-title}].

.Procedure

. In your {product} instance, go to *Home > Catalog*.
* On the Catalog page, click *Self-service*.

{product} automatically registers all components that developers or platform engineers create using Templates in the Software Catalog.
30 changes: 30 additions & 0 deletions modules/software-catalogs/proc-searching-and-filter-software-catalogs.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
// Module included in the following assemblies:
//
// * assemblies/assembly-about-software-catalogs.adoc

:_mod-docs-content-type: PROCEDURE
[id="proc-searching-and-filtering-software-catalogs_{context}"]
= Searching and filtering Software Catalogs

You can search and filter Software Catalogs by its *Kind* or by using the *Filter* field.

== Searching and Filtering Software Catalogs by Kind

To filter a Software Catalog by its *Kind*, complete the following steps:

.Procedure

. In your {product} instance, go to *Home > Catalog*.
. On the Catalog page, click the *Kind* drop-down list.
. Select the type of Kind you want to filter.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it the type of Kind or the type/kind of software catalog that you want to filter?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Type of Kind, Lindsey. :)

+
The available filter dropdowns vary based on the Kind you select, displaying options relevant to that specific entity type.

== Searching and Filtering Software Catalogs using the Filter field

To filter a Software Catalog using the *Filter* field, complete the following steps:

.Procedure

. In your {product} instance, go to *Home > Catalog*.
. Enter the text you want to use to filter the components.
19 changes: 19 additions & 0 deletions modules/software-catalogs/proc-starring-components-in-the-software-catalog.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
// Module included in the following assemblies:
//
// * assemblies/assembly-about-software-catalogs.adoc

:_mod-docs-content-type: PROCEDURE
[id="proc-starring-components-in-the-software-catalog_{context}"]
= Starring components in the Software Catalog

To quickly access the Software Catalogs that you visit regularly, complete the following steps:

.Procedure

. In your {product} instance, go to *Home > Catalog*.
. On the Home page, click *Catalog*.
. On the Red Hat Catalog page, on the Software Catalog that you want to star, under *Actions*, select the *Add to favorites* icon.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it more like click Actions and select... or use the Actions menu to select...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's like an Action Tile.

The "Add to favorites" icon is within the Actions tile. These are available for every entity record..


.Verification

. The starred component is listed under *Your Starred Entities* on your Home page.
24 changes: 24 additions & 0 deletions modules/software-catalogs/proc-updating-components-in-the-software-catalog.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
// Module included in the following assemblies:
//
// * assemblies/assembly-about-software-catalogs.adoc

:_mod-docs-content-type: PROCEDURE
[id="proc-updating-components-in-the-software-catalog_{context}"]
= Updating components in the Software Catalog in your {product} instance

To update components in the Software Catalog in your {product} instance, complete the following steps:

.Prerequisites

* You have installed the {product} instance.
* You have the required permissions. See link:{authorization-book-url}[{authorization-book-title}].

.Procedure

. In your {product} instance, go to *Home > Catalog*.
. On *Home page > Catalog*, on the entity that you want to edit, under *Actions*, select the *Edit* icon.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider this

Or you might be able to break this into multiple steps. Maybe something like the following:

Suggested change
. On *Home page > Catalog*, on the entity that you want to edit, under *Actions*, select the *Edit* icon.
. On the {product} *Home* page, click *Catalog*
. On the *Catalog* page, open the entity that you want to edit.
. From the *Actions* menu, select the *Edit* icon.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're not really opening the entity that we want to edit. The Actions tile contains the Edit icon. This Actions tile is next to every entity record listed in the Catalog page.

+
This action redirects you to the YAML file on GitHub.
. On your version control system, update your YAML file.
+
Once you merge your changes, the updated metadata in the Software Catalog appears after some time.
16 changes: 16 additions & 0 deletions modules/software-catalogs/proc-viewing-software-catalog-yaml.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
// Module included in the following assemblies:
//
// * assemblies/assembly-about-software-catalogs.adoc

:_mod-docs-content-type: PROCEDURE
[id="proc-viewing-software-catalog-yaml_{context}"]
= Viewing the Software Catalog YAML file in your {product} instance

To view the Software Catalog YAML file in your {product} instance, complete the following steps:

.Procedure

. In your {product} instance, go to *Home > Catalog*.
. On the Red Hat Catalog page, on the Software Catalog that you want to star, under *Actions*, select the *View* icon.
+
This action redirects you to the YAML file on your version control.
5 changes: 5 additions & 0 deletions titles/customizing/master.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,18 @@ include::modules/customizing/proc-customizing-the-backend-secret.adoc[leveloffse
include::assemblies/assembly-configuring-templates.adoc[leveloffset=+1]


include::assemblies/assembly-about-software-catalogs.adoc[leveloffset=+1]


include::assemblies/assembly-customizing-the-learning-paths.adoc[leveloffset=+1]


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


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


include::modules/customizing-the-tech-radar-page/proc-customize-rhdh-tech-radar-page.adoc[leveloffset=+1]


Expand Down