diff --git a/.cursor/skills/abstract/SKILL.md b/.cursor/skills/abstract/SKILL.md index 11aa813866f..cd87f55df38 100644 --- a/.cursor/skills/abstract/SKILL.md +++ b/.cursor/skills/abstract/SKILL.md @@ -1,6 +1,6 @@ --- name: abstract -description: Review or write abstract +description: Review or write an abstract (DITA short description) for a documentation module --- # Review or write abstract @@ -16,41 +16,18 @@ It is prefixed by the `[role="_abstract"]` AsciiDoc tag. Abstracts, also called short descriptions, help readers and AI-powered search tools find the information that they need and confirm that they are in the right place. -Abstracts typically contain the following information: - -- The "What" -- The "Why" -- Where appropriate, an example use case - ## Instructions When reviewing or writing the abstract, follow these principles: -- Ensure the abstract explains the What and the Why as defined in the section "Definition of an abstract". - - For the `What` part, state the action or feature clearly. For example, what the user must do or can do (in procedure modules), what the user needs to understand (in concept modules), or what is being listed (in reference modules). - - For the `Why` part, state the business value, benefit, or goal. For example, why the user should complete the action (in procedure modules), why the concept is important to users (in concept modules), or why the user would look up the information (in reference modules). - - For the `Example use case part`, consider including in what situations a user might find the contents of the module useful. - - Do not simply repeat the heading of the module; build upon it. -- Follow these user-centric language guidelines: - - Avoid documentation self-referential language (for example: avoid "This procedure..." or "This module"). - - Avoid feature-centric language (for example: avoid "This feature..."). - - Use user-centric language (for example: use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", "[Action] [what] to [why]"). +- Do not simply repeat the heading of the module; build upon it. +- Avoid self-referential language (for example: avoid "This procedure...", "This module...", "This table..."). +- Avoid feature-centric language (for example: avoid "This feature..."). +- Do not use sentence fragments. +- When needed, address the user as "you". - Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph. - -## Examples of good abstracts - -| Heading | Example abstract (procedure) | -| :--- | :--- | -| Browsing hosts in {ProjectWebUI} | Find and categorize your hosts within {Project} to get a quick overview of your managed infrastructure. Browsing hosts helps you understand your environment and identify specific host types for targeted actions. | -| Cloning hosts in {Project} | Clone existing hosts in {Project} to quickly create new hosts with similar configurations. This streamlines deployment processes and improves consistency across your environment. | -| Editing system purpose | Edit the system purpose attributes for your Red Hat Enterprise Linux hosts to help ensure they receive correct subscriptions and accurate reporting. This optimizes license compliance and management. | - -| Heading | Example abstract (concept) | -| :--- | :--- | -| Security considerations in {Project} | {Project} supports multiple security mechanisms to provide additional layers of protection. Implementing these security features enhances the overall security of your {Project} deployment. | -| Overview of authentication methods in {Project} | The authentication methods you can configure depend on the authentication source you are using. If the native authentication features provided by {Project} are not sufficient for your use case, use this information to decide which external authentication provider best suits your requirements. | - -| Heading | Example abstract (reference) | -| :--- | :--- | -| Subscriptions usage data | For the purposes of expense management and to optimize your spending, track your subscriptions usage data that you can get from your {Project} environment and Red Hat. You can track usage, capacity, and utilization of your Red Hat subscriptions. | -| Host global status overview | You can use the host global status in {Project} to see at a glance whether a host is OK, needs attention (Warning), or has errors. The status appears on the Hosts Overview page and helps you prioritize which hosts to investigate. | +- Write one sentence per line. +- For module-type-specific abstract rules, look up the reference file that matches the `:_mod-docs-content-type:` AsciiDoc attribute in the module (open and apply that file in full): + - `CONCEPT` → [references/concept.md](references/concept.md) + - `PROCEDURE` → [references/procedure.md](references/procedure.md) + - `REFERENCE` → [references/reference.md](references/reference.md) diff --git a/.cursor/skills/abstract/references/concept.md b/.cursor/skills/abstract/references/concept.md new file mode 100644 index 00000000000..bfc1b293b40 --- /dev/null +++ b/.cursor/skills/abstract/references/concept.md @@ -0,0 +1,15 @@ +# Abstract instructions: concept modules + +When the module has `:_mod-docs-content-type: CONCEPT`, follow these rules for the abstract (short description): + +- Introduce the concept and provide a concise answer to the question "What is this?" and in some cases "Why do I care about this?" +- If the concept is unfamiliar, start with a brief definition. +- Avoid using the short description to lead in or build up to a topic. +- Include the main point of the concept topic. + +## Examples of good abstracts + +| Heading | Example abstract (concept) | +| :--- | :--- | +| Security considerations in {Project} | {Project} supports multiple security mechanisms to provide additional layers of protection. Implementing these security features enhances the overall security of your {Project} deployment. | +| Overview of authentication methods in {Project} | The authentication methods you can configure depend on the authentication source you are using. If the native authentication features provided by {Project} are not sufficient for your use case, use this information to decide which external authentication provider best suits your requirements. | diff --git a/.cursor/skills/abstract/references/procedure.md b/.cursor/skills/abstract/references/procedure.md new file mode 100644 index 00000000000..d1047ee0317 --- /dev/null +++ b/.cursor/skills/abstract/references/procedure.md @@ -0,0 +1,17 @@ +# Abstract instructions: procedure modules + +When the module has `:_mod-docs-content-type: PROCEDURE`, follow these rules for the abstract (short description): + +- Use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", or "[Action] [what] to [why]". +- Explain the task that users can accomplish, the benefits of the task, and the purpose of the task. +- Do not simply repeat the title. +- Include information that will help users understand when the task is appropriate or necessary. +- When the abstract is too short, thin, or generic, add more information about why the task is beneficial. + +## Examples of good abstracts + +| Heading | Example abstract (procedure) | +| :--- | :--- | +| Browsing hosts in {ProjectWebUI} | Find and categorize your hosts within {Project} to get a quick overview of your managed infrastructure. Browsing hosts helps you understand your environment and identify specific host types for targeted actions. | +| Cloning hosts in {Project} | Clone existing hosts in {Project} to quickly create new hosts with similar configurations. This streamlines deployment processes and improves consistency across your environment. | +| Editing system purpose | Edit the system purpose attributes for your Red Hat Enterprise Linux hosts to help ensure they receive correct subscriptions and accurate reporting. This optimizes license compliance and management. | diff --git a/.cursor/skills/abstract/references/reference.md b/.cursor/skills/abstract/references/reference.md new file mode 100644 index 00000000000..fdf547af8c3 --- /dev/null +++ b/.cursor/skills/abstract/references/reference.md @@ -0,0 +1,12 @@ +# Abstract instructions: reference modules + +When the module has `:_mod-docs-content-type: REFERENCE`, follow these rules for the abstract (short description): + +- Briefly describe what the reference item does, what it is, or what it is used for. + +## Examples of good abstracts + +| Heading | Example abstract (reference) | +| :--- | :--- | +| Subscriptions usage data | For the purposes of expense management and to optimize your spending, track your subscriptions usage data that you can get from your {Project} environment and Red Hat. You can track usage, capacity, and utilization of your Red Hat subscriptions. | +| Host global status overview | You can use the host global status in {Project} to see at a glance whether a host is OK, needs attention (Warning), or has errors. The status appears on the Hosts Overview page and helps you prioritize which hosts to investigate. | diff --git a/guides/common/modules/con_adding-content-to-foreman.adoc b/guides/common/modules/con_adding-content-to-foreman.adoc index 64194a11b9d..91c5a0bee9f 100644 --- a/guides/common/modules/con_adding-content-to-foreman.adoc +++ b/guides/common/modules/con_adding-content-to-foreman.adoc @@ -4,4 +4,5 @@ = Adding content to {Project} [role="_abstract"] -This chapter outlines how you can import different types of {customcontent} to {Project}. +You organize content in products and repositories and secure upstream access with content credentials before you create custom products and repositories. +You synchronize from upstream URLs, upload your own content, and use repository definitions when you plan client repositories. diff --git a/guides/common/modules/con_authenticating-and-securing-content-with-content-credentials.adoc b/guides/common/modules/con_authenticating-and-securing-content-with-content-credentials.adoc index e5ec917798d..35ef72b16ce 100644 --- a/guides/common/modules/con_authenticating-and-securing-content-with-content-credentials.adoc +++ b/guides/common/modules/con_authenticating-and-securing-content-with-content-credentials.adoc @@ -4,19 +4,18 @@ = Authenticating and securing content with content credentials [role="_abstract"] -Upstream content often uses HTTPS and signed metadata or packages. -Import SSL certificates when upstream servers use custom or private certificate authorities so {Project} can connect securely. +Upstream repositories use HTTPS and signed metadata or packages; import SSL certificates when upstreams use custom or private CAs so {Project} connects securely. ifdef::katello[] -Import GPG keys so {Project} and registered hosts can verify signatures on RPM packages or metadata of Deb content. +Import GPG keys so {Project} and hosts can validate RPM packages and Debian repository metadata. endif::[] ifdef::orcharhino[] ifdef::almalinux,amazon_linux,centos,oracle_linux,red_hat_enterprise_linux,rocky_linux,suse_linux_enterprise_server[] -Import GPG keys so registered hosts can verify signatures on Yum content when they consume content from {Project}. +Import GPG keys so registered hosts can verify Yum signatures when they consume content from {Project}. endif::[] ifdef::debian,ubuntu[] -Import GPG keys so {Project} can verify signatures on metadata of Deb content. +Import GPG keys so {Project} can verify signatures on Deb repository metadata. endif::[] endif::[] ifdef::satellite[] -Import GPG keys so registered hosts can verify signatures on Yum content when they consume content from {Project}. +Import GPG keys so registered hosts can verify Yum signatures when they consume content from {Project}. endif::[] diff --git a/guides/common/modules/con_creating-products.adoc b/guides/common/modules/con_creating-products.adoc index 7f5cfaf89fe..ba90eb4508d 100644 --- a/guides/common/modules/con_creating-products.adoc +++ b/guides/common/modules/con_creating-products.adoc @@ -5,7 +5,7 @@ [role="_abstract"] A product in {Project} groups related repositories. -Create a {customproduct} before you add {customrepos}. +You create a {customproduct} before you add {customrepos}. ifndef::satellite[] [NOTE] diff --git a/guides/common/modules/con_products-and-repositories.adoc b/guides/common/modules/con_products-and-repositories.adoc index ac4d940039f..d466ca2b185 100644 --- a/guides/common/modules/con_products-and-repositories.adoc +++ b/guides/common/modules/con_products-and-repositories.adoc @@ -4,9 +4,8 @@ = Products and repositories in {Project} [role="_abstract"] -Content in {Project} is organized into products and repositories. -A repository is a collection of content, such as packages, container images, or files. -A collection of repositories forms a product. +{Project} organizes content into products, each grouping repositories that store packages, container images, or files. +The relationship between products and repositories is the same for all content types, and each custom product supplies a subscription for host access. ifdef::satellite[] Both Red Hat content and custom content in {Project} have similarities: diff --git a/guides/common/modules/con_uploading-content-to-repositories.adoc b/guides/common/modules/con_uploading-content-to-repositories.adoc index 7fc90b72055..7ee91556024 100644 --- a/guides/common/modules/con_uploading-content-to-repositories.adoc +++ b/guides/common/modules/con_uploading-content-to-repositories.adoc @@ -4,4 +4,4 @@ = Uploading content to {customrepos} [role="_abstract"] -You can upload content to {customrepos} to distribute content that you cannot synchronize from an upstream URL. +Upload content to {customrepos} when you must distribute software that is not available from any upstream synchronization URL. diff --git a/guides/common/modules/proc_adding-custom-rpm-repositories-by-using-cli.adoc b/guides/common/modules/proc_adding-custom-rpm-repositories-by-using-cli.adoc index 5d4243e6419..c24a5085256 100644 --- a/guides/common/modules/proc_adding-custom-rpm-repositories-by-using-cli.adoc +++ b/guides/common/modules/proc_adding-custom-rpm-repositories-by-using-cli.adoc @@ -4,11 +4,8 @@ = Adding {customrpm} repositories by using Hammer CLI [role="_abstract"] -You can add {customrpm} repositories to {Project} by using Hammer CLI. - -The *Products* window in the {ProjectWebUI} also provides a *Repo Discovery* function that finds all repositories from a URL and you can select which ones to add to your {customproduct}. -For example, you can use the *Repo Discovery* to search `https://download.postgresql.org/pub/repos/yum/16/redhat/` and list all repositories for different {EL} versions and architectures. -This helps users save time importing multiple repositories from a single source. +You add {customrpm} repositories to a product so hosts can synchronize or upload third-party or internal packages through {Project}. +Use Hammer CLI when you automate repository creation or repeat the same settings across environments. ifdef::satellite[] [NOTE] diff --git a/guides/common/modules/proc_adding-custom-rpm-repositories-by-using-web-ui.adoc b/guides/common/modules/proc_adding-custom-rpm-repositories-by-using-web-ui.adoc index 9862a6d6768..b57683f4596 100644 --- a/guides/common/modules/proc_adding-custom-rpm-repositories-by-using-web-ui.adoc +++ b/guides/common/modules/proc_adding-custom-rpm-repositories-by-using-web-ui.adoc @@ -4,11 +4,8 @@ = Adding {customrpm} repositories by using {ProjectWebUI} [role="_abstract"] -You can add {customrpm} repositories to {Project} by using the {ProjectWebUI}. - -The *Products* window in the {ProjectWebUI} also provides a *Repo Discovery* function that finds all repositories from a URL and you can select which ones to add to your {customproduct}. -For example, you can use the *Repo Discovery* to search `https://download.postgresql.org/pub/repos/yum/16/redhat/` and list all repositories for different {EL} versions and architectures. -This helps users save time importing multiple repositories from a single source. +You add {customrpm} repositories to a product so hosts can synchronize or upload third-party or internal packages through {Project}. +Use {ProjectWebUI} when you create repositories manually or run *Repo Discovery* against a vendor URL to import many related repositories at once. ifdef::satellite[] [NOTE] diff --git a/guides/common/modules/proc_adding-deb-repositories-by-using-cli.adoc b/guides/common/modules/proc_adding-deb-repositories-by-using-cli.adoc index 839f0f6085e..7f9fc8bf612 100644 --- a/guides/common/modules/proc_adding-deb-repositories-by-using-cli.adoc +++ b/guides/common/modules/proc_adding-deb-repositories-by-using-cli.adoc @@ -4,7 +4,8 @@ = Adding Deb repositories by using Hammer CLI [role="_abstract"] -You can add Deb repositories to {Project} by using Hammer CLI. +You add Deb repositories in {Project} to mirror Debian or Ubuntu suites for managed hosts. +Use Hammer CLI when you define releases, components, and architectures from the command line. .Prerequisites * You have extracted and imported the GPG key that you want to use to verify signatures of the `Release` files. diff --git a/guides/common/modules/proc_adding-deb-repositories-by-using-web-ui.adoc b/guides/common/modules/proc_adding-deb-repositories-by-using-web-ui.adoc index be50d41b841..d869b2e69bd 100644 --- a/guides/common/modules/proc_adding-deb-repositories-by-using-web-ui.adoc +++ b/guides/common/modules/proc_adding-deb-repositories-by-using-web-ui.adoc @@ -4,7 +4,8 @@ = Adding Deb repositories by using {ProjectWebUI} [role="_abstract"] -You can add Deb repositories to {Project} by using the {ProjectWebUI}. +You add Deb repositories in {Project} to mirror Debian or Ubuntu suites for managed hosts. +Use {ProjectWebUI} when you configure distribution paths, components, and upstream URLs interactively. .Prerequisites * You have extracted and imported the GPG key that you want to use to verify signatures of the `Release` files. diff --git a/guides/common/modules/proc_creating-a-custom-product-by-using-cli.adoc b/guides/common/modules/proc_creating-a-custom-product-by-using-cli.adoc index ecbada88d29..e0f2bf19201 100644 --- a/guides/common/modules/proc_creating-a-custom-product-by-using-cli.adoc +++ b/guides/common/modules/proc_creating-a-custom-product-by-using-cli.adoc @@ -4,7 +4,8 @@ = Creating a {customproduct} by using Hammer CLI [role="_abstract"] -Create a {customproduct} so that you can add repositories to the {customproduct}. +You create a {customproduct} in {Project} to group repositories and optional SSL or GPG credentials under one manageable label. +Use Hammer CLI when you automate product creation alongside repositories and credentials. .Procedure * Create a product: diff --git a/guides/common/modules/proc_creating-a-custom-product-by-using-web-ui.adoc b/guides/common/modules/proc_creating-a-custom-product-by-using-web-ui.adoc index 94f8b3171b8..d3a9e4832c0 100644 --- a/guides/common/modules/proc_creating-a-custom-product-by-using-web-ui.adoc +++ b/guides/common/modules/proc_creating-a-custom-product-by-using-web-ui.adoc @@ -4,7 +4,8 @@ = Creating a {customproduct} by using {ProjectWebUI} [role="_abstract"] -Create a {customproduct} so that you can add repositories to the {customproduct}. +You create a {customproduct} in {Project} to group repositories and optional SSL or GPG credentials under one manageable label. +Use a dedicated product when you want lifecycle, permissions, and sync plans scoped separately from other software you publish. .Procedure . In the {ProjectWebUI}, navigate to *Content* > *Products*, click *Create Product*. diff --git a/guides/common/modules/proc_enabling-red-hat-repositories-by-using-cli.adoc b/guides/common/modules/proc_enabling-red-hat-repositories-by-using-cli.adoc index fbe62f30489..ef792716f3a 100644 --- a/guides/common/modules/proc_enabling-red-hat-repositories-by-using-cli.adoc +++ b/guides/common/modules/proc_enabling-red-hat-repositories-by-using-cli.adoc @@ -4,6 +4,9 @@ = Enabling Red{nbsp}Hat repositories by using Hammer CLI [role="_abstract"] +You enable Red{nbsp}Hat repository sets in {Project} so subscribed product content can synchronize into Library before hosts consume it. +Use Hammer CLI when you script enablement or integrate it with other server automation. + If outside network access requires usage of an HTTP proxy, configure a default HTTP proxy for your {ProjectServer}. For more information, see {InstallingServerDocURL}adding-a-default-http-proxy-by-using-cli[Adding a default HTTP proxy to {Project}]. diff --git a/guides/common/modules/proc_enabling-red-hat-repositories-by-using-web-ui.adoc b/guides/common/modules/proc_enabling-red-hat-repositories-by-using-web-ui.adoc index 152aaca2f1a..d8bbb488f20 100644 --- a/guides/common/modules/proc_enabling-red-hat-repositories-by-using-web-ui.adoc +++ b/guides/common/modules/proc_enabling-red-hat-repositories-by-using-web-ui.adoc @@ -4,6 +4,9 @@ = Enabling Red{nbsp}Hat repositories by using {ProjectWebUI} [role="_abstract"] +You enable Red{nbsp}Hat repository sets in {Project} so subscribed product content can synchronize into Library before hosts consume it. +Use {ProjectWebUI} when you want to browse recommended sets and enable release versions and base architectures interactively. + If outside network access requires usage of an HTTP proxy, configure a default HTTP proxy for your {ProjectServer}. For more information, see {InstallingServerDocURL}adding-a-default-http-proxy-by-using-web-ui[Adding a default HTTP proxy to {Project}]. diff --git a/guides/common/modules/proc_extracting-gpg-public-key-fingerprints-from-release-files.adoc b/guides/common/modules/proc_extracting-gpg-public-key-fingerprints-from-release-files.adoc index c86aed4d17e..09f44e85825 100644 --- a/guides/common/modules/proc_extracting-gpg-public-key-fingerprints-from-release-files.adoc +++ b/guides/common/modules/proc_extracting-gpg-public-key-fingerprints-from-release-files.adoc @@ -4,8 +4,7 @@ = Extracting GPG public key fingerprints from Release files [role="_abstract"] -You can use GPG public keys to verify the authenticity of Deb repositories by verifying the signature of the `Release` file. -This example verifies the signature for the `Release` file from Debian 11. +You extract GPG public key fingerprints from signed `Release` files so you can import the matching keys that secure Deb repositories in {Project}. .Procedure . Download the `Release` and `Release.gpg` files: diff --git a/guides/common/modules/proc_importing-a-custom-gpg-key-by-using-cli.adoc b/guides/common/modules/proc_importing-a-custom-gpg-key-by-using-cli.adoc index 6de10829049..fdaa7699416 100644 --- a/guides/common/modules/proc_importing-a-custom-gpg-key-by-using-cli.adoc +++ b/guides/common/modules/proc_importing-a-custom-gpg-key-by-using-cli.adoc @@ -4,8 +4,8 @@ = Importing a {customgpg} key by using Hammer CLI [role="_abstract"] -When hosts consume signed {customcontent}, ensure that the hosts are configured to validate the installation of packages with the appropriate GPG Key. -This helps to ensure that only packages from authorized sources can be installed. +You import a {customgpg} key into {Project} when you synchronize signed {customcontent} so repository metadata and hosts can validate packages against the public key your vendor publishes. +Approved keys help ensure hosts install only packages that carry signatures from sources you trust. ifdef::satellite[] Red{nbsp}Hat content is already configured with the appropriate GPG key and thus GPG Key management of Red{nbsp}Hat repositories is not supported. diff --git a/guides/common/modules/proc_importing-a-custom-gpg-key-by-using-web-ui.adoc b/guides/common/modules/proc_importing-a-custom-gpg-key-by-using-web-ui.adoc index 38803f41807..f04591be526 100644 --- a/guides/common/modules/proc_importing-a-custom-gpg-key-by-using-web-ui.adoc +++ b/guides/common/modules/proc_importing-a-custom-gpg-key-by-using-web-ui.adoc @@ -4,8 +4,8 @@ = Importing a {customgpg} key by using {ProjectWebUI} [role="_abstract"] -When hosts consume signed {customcontent}, ensure that the hosts are configured to validate the installation of packages with the appropriate GPG Key. -This helps to ensure that only packages from authorized sources can be installed. +You import a {customgpg} key into {Project} when you synchronize signed {customcontent} so repository metadata and hosts can validate packages against the public key your vendor publishes. +Approved keys help ensure hosts install only packages that carry signatures from sources you trust. ifdef::satellite[] Red{nbsp}Hat content is already configured with the appropriate GPG key and thus GPG Key management of Red{nbsp}Hat repositories is not supported. diff --git a/guides/common/modules/proc_importing-custom-ssl-certificates-by-using-cli.adoc b/guides/common/modules/proc_importing-custom-ssl-certificates-by-using-cli.adoc index 2d61b11709a..58502263bb3 100644 --- a/guides/common/modules/proc_importing-custom-ssl-certificates-by-using-cli.adoc +++ b/guides/common/modules/proc_importing-custom-ssl-certificates-by-using-cli.adoc @@ -4,10 +4,7 @@ = Importing {customssl} certificates by using Hammer CLI [role="_abstract"] -Before you synchronize {customcontent} from an external source, you might need to import SSL certificates into your {Project}. -This might include client certs and keys or CA certificates for the upstream repositories you want to synchronize. - -If you require SSL certificates and keys to download packages, you can add them to {Project}. +You import SSL certificates or keys into {Project} so upstream synchronization over HTTPS can trust custom certificate authorities or present client credentials when vendors require mutual TLS. .Procedure . Copy the SSL certificate to your {ProjectServer}: diff --git a/guides/common/modules/proc_importing-custom-ssl-certificates-by-using-web-ui.adoc b/guides/common/modules/proc_importing-custom-ssl-certificates-by-using-web-ui.adoc index de0de6e333e..1721b4bff0c 100644 --- a/guides/common/modules/proc_importing-custom-ssl-certificates-by-using-web-ui.adoc +++ b/guides/common/modules/proc_importing-custom-ssl-certificates-by-using-web-ui.adoc @@ -4,10 +4,7 @@ = Importing {customssl} certificates by using {ProjectWebUI} [role="_abstract"] -Before you synchronize {customcontent} from an external source, you might need to import SSL certificates into your {Project}. -This might include client certs and keys or CA certificates for the upstream repositories you want to synchronize. - -If you require SSL certificates and keys to download packages, you can add them to {Project}. +You import SSL certificates or keys into {Project} so upstream synchronization over HTTPS can trust custom certificate authorities or present client credentials when vendors require mutual TLS. .Procedure . In the {ProjectWebUI}, navigate to *Content* > *Content Credentials*. diff --git a/guides/common/modules/proc_uploading-content-to-custom-rpm-repositories-by-using-cli.adoc b/guides/common/modules/proc_uploading-content-to-custom-rpm-repositories-by-using-cli.adoc index dfe61880fe2..10436d31968 100644 --- a/guides/common/modules/proc_uploading-content-to-custom-rpm-repositories-by-using-cli.adoc +++ b/guides/common/modules/proc_uploading-content-to-custom-rpm-repositories-by-using-cli.adoc @@ -4,7 +4,7 @@ = Uploading content to {customrpm} repositories by using Hammer CLI [role="_abstract"] -You can upload individual RPMs and source RPMs to {customrpm} repositories by using Hammer CLI. +You upload RPM or source RPM packages with Hammer CLI when you need scripted bulk uploads or source RPM support beyond the web UI. .Procedure * Upload an RPM package: diff --git a/guides/common/modules/proc_uploading-content-to-custom-rpm-repositories-by-using-web-ui.adoc b/guides/common/modules/proc_uploading-content-to-custom-rpm-repositories-by-using-web-ui.adoc index 60ab363716c..5b37e9c8ac0 100644 --- a/guides/common/modules/proc_uploading-content-to-custom-rpm-repositories-by-using-web-ui.adoc +++ b/guides/common/modules/proc_uploading-content-to-custom-rpm-repositories-by-using-web-ui.adoc @@ -4,10 +4,8 @@ = Uploading content to {customrpm} repositories by using {ProjectWebUI} [role="_abstract"] -You can upload individual RPMs to {customrpm} repositories by using {ProjectWebUI}. - -You must use the Hammer CLI to upload source RPMs. -For more information, see xref:uploading-content-to-custom-rpm-repositories-by-using-cli[]. +You upload binary RPM packages in {ProjectWebUI} to populate custom repositories without synchronizing from an upstream URL. +Use Hammer CLI when you must upload source RPM packages. .Procedure . In the {ProjectWebUI}, navigate to *Content* > *Products*. diff --git a/guides/common/modules/proc_uploading-content-to-deb-repositories-by-using-cli.adoc b/guides/common/modules/proc_uploading-content-to-deb-repositories-by-using-cli.adoc index 8300d9cf431..c9a131186ee 100644 --- a/guides/common/modules/proc_uploading-content-to-deb-repositories-by-using-cli.adoc +++ b/guides/common/modules/proc_uploading-content-to-deb-repositories-by-using-cli.adoc @@ -4,8 +4,8 @@ = Uploading content to Deb repositories by using Hammer CLI [role="_abstract"] -You can upload individual Deb packages to Deb repositories by using Hammer CLI. -Do not upload packages to a repository if you have set the *Upstream URL*. +You upload `.deb` packages with Hammer CLI when the repository has no upstream URL so local builds can join your managed repositories. +Do not upload packages to a repository that already defines an upstream URL because that configuration expects the mirror to supply content. .Procedure * Upload a Deb package: diff --git a/guides/common/modules/proc_uploading-content-to-deb-repositories-by-using-web-ui.adoc b/guides/common/modules/proc_uploading-content-to-deb-repositories-by-using-web-ui.adoc index e0a9865264d..e569021ed2f 100644 --- a/guides/common/modules/proc_uploading-content-to-deb-repositories-by-using-web-ui.adoc +++ b/guides/common/modules/proc_uploading-content-to-deb-repositories-by-using-web-ui.adoc @@ -4,7 +4,7 @@ = Uploading content to Deb repositories by using {ProjectWebUI} [role="_abstract"] -You can upload individual Deb packages to Deb repositories by using {ProjectWebUI}. +You upload `.deb` packages in {ProjectWebUI} when a repository has no upstream URL so locally acquired packages become available in your content pipeline. .Procedure . In the {ProjectWebUI}, navigate to *Content* > *Products*. diff --git a/guides/common/modules/ref_best-practices-for-products-and-repositories.adoc b/guides/common/modules/ref_best-practices-for-products-and-repositories.adoc index ca2de9e257c..2cacf9b06c2 100644 --- a/guides/common/modules/ref_best-practices-for-products-and-repositories.adoc +++ b/guides/common/modules/ref_best-practices-for-products-and-repositories.adoc @@ -4,7 +4,7 @@ = Best practices for products and repositories [role="_abstract"] -{Team} recommends following best practices for products and repositories in {Project}. +These guidelines help you structure products and content views, serve file repositories over HTTP, automate bulk creation, and keep uploads separate from synchronized upstream repositories. * Use one content type per product and content view, for example, {client-content-type} content only. ifdef::orcharhino[] diff --git a/guides/common/modules/ref_repository-definitions-for-almalinux.adoc b/guides/common/modules/ref_repository-definitions-for-almalinux.adoc index cf889b53d32..a7f67638acc 100644 --- a/guides/common/modules/ref_repository-definitions-for-almalinux.adoc +++ b/guides/common/modules/ref_repository-definitions-for-almalinux.adoc @@ -4,7 +4,7 @@ = Repository definitions for AlmaLinux [role="_abstract"] -Upstream repositories for AlmaLinux include BaseOS, AppStream, extras, and the optional {project-client-name}. +Use these example repository names and upstream URLs when you synchronize AlmaLinux BaseOS, AppStream, extras, and the optional {project-client-name} content. [id="almalinux-10"] .AlmaLinux 10 diff --git a/guides/common/modules/ref_repository-definitions-for-centos-stream.adoc b/guides/common/modules/ref_repository-definitions-for-centos-stream.adoc index be7d4370036..179394552b3 100644 --- a/guides/common/modules/ref_repository-definitions-for-centos-stream.adoc +++ b/guides/common/modules/ref_repository-definitions-for-centos-stream.adoc @@ -4,7 +4,7 @@ = Repository definitions for CentOS Stream [role="_abstract"] -Upstream repositories for CentOS Stream include BaseOS, AppStream, extras, and the optional {project-client-name}. +Use these example repository names and upstream URLs when you synchronize CentOS Stream BaseOS, AppStream, extras, and the optional {project-client-name} content. [id="centos-stream-10"] .CentOS Stream 10 diff --git a/guides/common/modules/ref_repository-definitions-for-client-operating-systems.adoc b/guides/common/modules/ref_repository-definitions-for-client-operating-systems.adoc index 96179ea0e17..cb52d4311cd 100644 --- a/guides/common/modules/ref_repository-definitions-for-client-operating-systems.adoc +++ b/guides/common/modules/ref_repository-definitions-for-client-operating-systems.adoc @@ -4,8 +4,8 @@ = Repository definitions for client operating systems [role="_abstract"] -A repository definition represents the upstream repository information that you enter in {Project} when creating a repository for an operating system. -Each table contains a *Repository name* as you might enter it, together with fields required for synchronization. +A repository definition captures the upstream URLs, names, and synchronization fields you mirror for a client operating system in {Project}. +Use the following tables to copy example repository names and field values when you create each repository. .Additional resources * xref:creating-a-custom-product-by-using-web-ui[] diff --git a/guides/common/modules/ref_repository-definitions-for-debian.adoc b/guides/common/modules/ref_repository-definitions-for-debian.adoc index 318851244d1..4ee8aa1f2a8 100644 --- a/guides/common/modules/ref_repository-definitions-for-debian.adoc +++ b/guides/common/modules/ref_repository-definitions-for-debian.adoc @@ -4,7 +4,7 @@ = Repository definitions for Debian [role="_abstract"] -Upstream repositories for Debian include *main*, *updates*, *security*, and the {project-client-name}. +Use these example repository names, upstream URLs, releases, components, and architectures when you synchronize Debian main, updates, security, and {project-client-name} content. [id="debian-13"] .Debian 13 diff --git a/guides/common/modules/ref_repository-definitions-for-oracle-linux-on-public-yum-servers.adoc b/guides/common/modules/ref_repository-definitions-for-oracle-linux-on-public-yum-servers.adoc index fd8303e0284..35a5a7f65e8 100644 --- a/guides/common/modules/ref_repository-definitions-for-oracle-linux-on-public-yum-servers.adoc +++ b/guides/common/modules/ref_repository-definitions-for-oracle-linux-on-public-yum-servers.adoc @@ -4,7 +4,7 @@ = Repository definitions for Oracle Linux on public yum servers [role="_abstract"] -Upstream repositories for Oracle Linux include BaseOS, AppStream, and addons on `yum.oracle.com`, and the {project-client-name}. +Use these example repository names and upstream URLs when you synchronize Oracle Linux BaseOS, AppStream, addons on yum.oracle.com, and {project-client-name} content. include::snip_important-oracle-linux-content.adoc[] diff --git a/guides/common/modules/ref_repository-definitions-for-oracle-linux-on-uln.adoc b/guides/common/modules/ref_repository-definitions-for-oracle-linux-on-uln.adoc index 983b26da349..2c43cb4c642 100644 --- a/guides/common/modules/ref_repository-definitions-for-oracle-linux-on-uln.adoc +++ b/guides/common/modules/ref_repository-definitions-for-oracle-linux-on-uln.adoc @@ -4,7 +4,8 @@ = Repository definitions for Oracle Linux on ULN [role="_abstract"] -You can synchronize content from Oracle Unbreakable Linux Network (ULN) to {Project}. +You synchronize Oracle Linux packages from Unbreakable Linux Network (ULN) channels using uln:// URLs and mandatory upstream credentials in {Project}. +Use the channel labels from the ULN web UI as the path after the protocol prefix when you add each repository. There are two main differences compared to generic Yum content: diff --git a/guides/common/modules/ref_repository-definitions-for-rocky-linux.adoc b/guides/common/modules/ref_repository-definitions-for-rocky-linux.adoc index 9441525a12e..e52d88faf3d 100644 --- a/guides/common/modules/ref_repository-definitions-for-rocky-linux.adoc +++ b/guides/common/modules/ref_repository-definitions-for-rocky-linux.adoc @@ -4,7 +4,7 @@ = Repository definitions for Rocky Linux [role="_abstract"] -Upstream repositories for Rocky Linux include BaseOS, AppStream, extras, and the optional {project-client-name}. +Use these example repository names and upstream URLs when you synchronize Rocky Linux BaseOS, AppStream, extras, and the optional {project-client-name} content. [id="rocky-linux-10"] .Rocky Linux 10 diff --git a/guides/common/modules/ref_repository-definitions-for-ubuntu-under-esm.adoc b/guides/common/modules/ref_repository-definitions-for-ubuntu-under-esm.adoc index 2b30f58ec59..d5fdbcd8b13 100644 --- a/guides/common/modules/ref_repository-definitions-for-ubuntu-under-esm.adoc +++ b/guides/common/modules/ref_repository-definitions-for-ubuntu-under-esm.adoc @@ -4,8 +4,8 @@ = Repository definitions for Ubuntu under ESM [role="_abstract"] -Ubuntu Expanded Security Maintenance (ESM) provides extended security updates for selected releases through authenticated Deb repositories. -Extract the values from your subscribed Ubuntu host to create Ubuntu ESM repositories in {Project}. +Ubuntu Expanded Security Maintenance (ESM) exposes authenticated Deb repositories that extend security support for selected releases. +You reuse URL, distribution, component, and key values from an attached ESM host when you create matching repositories in {Project}. [IMPORTANT] ==== diff --git a/guides/common/modules/ref_repository-definitions-for-ubuntu.adoc b/guides/common/modules/ref_repository-definitions-for-ubuntu.adoc index c6238525a10..90debb7539c 100644 --- a/guides/common/modules/ref_repository-definitions-for-ubuntu.adoc +++ b/guides/common/modules/ref_repository-definitions-for-ubuntu.adoc @@ -4,7 +4,7 @@ = Repository definitions for Ubuntu [role="_abstract"] -Upstream repositories for Ubuntu include *main*, *updates*, and *security* repositories under Standard Security Maintenance, and the {project-client-name} repository, for supported LTS releases. +Use these example names, URLs, releases, components, and architectures when you synchronize Ubuntu main, updates, security under Standard Security Maintenance, plus {project-client-name} for supported LTS releases. [id="ubuntu-26-04"] .Ubuntu 26.04