Review abstracts and headings in Managing hosts by aneta-petrova · Pull Request #4712 · theforeman/foreman-documentation

aneta-petrova · 2026-03-13T20:49:00Z

What changes are you introducing?

Reviewing abstracts and headings in Managing Hosts to ensure they conform with the requirements from CQA (content quality assessment)

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

This is a downstream requirement

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

I used the .cursor/commands/abstract.md command for most of the changes to abstracts
I used the .cursor/commands/heading.md command for most of the changes to headings (Add cursor commands for heading review #4714)

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.18/Katello 4.20 (Satellite 6.19)
Foreman 3.17/Katello 4.19
Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6 and 7.7)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
Foreman 3.13/Katello 4.15 (EL9 only)
Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
We do not accept PRs for Foreman older than 3.12.

github-actions · 2026-03-13T20:53:18Z

The PR preview for 21a3350 is available at theforeman-foreman-documentation-preview-pr-4712.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

maximiliankolb

28/121

guides/common/modules/con_administering-hosts-in-project.adoc

guides/common/modules/con_adding-content-to-a-host-collection.adoc

guides/common/modules/con_managing-packages-in-project.adoc

guides/common/modules/con_nested-host-groups.adoc

guides/common/modules/proc_adding-errata-to-a-host-collection.adoc

guides/common/modules/proc_applying-errata-to-a-host.adoc

guides/common/modules/proc_adding-packages-to-a-host-collection.adoc

guides/common/modules/proc_applying-errata-to-hosts-by-using-cli.adoc

guides/common/modules/proc_applying-errata-to-hosts-by-using-web-ui.adoc

maximiliankolb

70/121

guides/common/modules/ref_template-macros-reference.adoc

guides/common/modules/proc_using-the-api-to-obtain-ssh-keys-for-remote-execution.adoc

guides/common/modules/proc_upgrading-hosts-to-next-major-release.adoc

...on/modules/proc_setting-an-alternative-directory-for-remote-execution-jobs-in-push-mode.adoc

...on/modules/proc_setting-an-alternative-directory-for-remote-execution-jobs-in-pull-mode.adoc

guides/common/modules/proc_scheduling-a-recurring-ansible-job-for-a-host-group.adoc

guides/common/modules/proc_restarting-applications-on-a-host.adoc

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

maximiliankolb

121/121

guides/common/modules/con_host-groups-overview.adoc

maximiliankolb · 2026-03-18T08:07:19Z

guides/common/modules/con_working-with-host-groups.adoc

I would appreciate tech ACK for this change.

Hi @jeremylenz and/or @nofaralfasi, can you please review this change to an abstract? Does it summarize why a user would be interested in applying host groups?

...on/modules/proc_changing-the-lifecycle-environment-or-content-view-of-a-host-collection.adoc

guides/common/modules/proc_cloning-hosts-in-project.adoc

guides/common/modules/proc_creating-a-job-template-by-using-cli.adoc

guides/common/modules/proc_generating-host-monitoring-reports-by-using-cli.adoc

guides/common/modules/proc_generating-host-monitoring-reports-by-using-web-ui.adoc

maximiliankolb · 2026-03-18T12:25:47Z

guides/common/modules/proc_importing-all-available-ansible-playbooks.adoc

 [role="_abstract"]
-You can import all the available Ansible Playbooks to {Project} from collections installed on {SmartProxy}.
+You can import all available Ansible Playbooks to {Project} from collections installed on {SmartProxy}.
+{Project} creates a job template from each playbook so you can run them on hosts via remote execution without writing templates manually.


Suggested change

{Project} creates a job template from each playbook so you can run them on hosts via remote execution without writing templates manually.

{Project} creates a job template from each playbook so you can run them on hosts through remote execution without writing templates manually.

Actually, there's a REX job template that does exactly this: take input and run it; the input is an Ansible playbook.

But the new line in the abstract is correct, isn't it? It seems to summarize the contents of the module so it looks correct to me.

I don't think so. I ran the following steps on Foreman 3.16/Katello 4.18 to try to reproduce this:

Sync Ansible collection

url: https://galaxy.ansible.com/
requirements:

--- collections: - name: nextcloud.admin version: 2.3.1

Check all job templates for any org/loc under hosts > templates > job templates

Check via monitor > jobs > check all "Ansible *" categories.

Based on that line, I would have expected a job template under Ansible Playbooks but there's none.

-> {Project} creates a job template from each playbook looks wrong to me.

more thoughts:

-> content > content types > Ansible collections seems to provide some read-only information but they did not help me much. It's unclear what that's for:

-> https://docs.theforeman.org/nightly/Managing_Content/index-katello.html#Managing_Ansible_Content_content-management lacks information on why to do this.

Agree that "creates a job template from each playbook" doesn't sound correct. I'm sure Adam will have more to say.

Huh, looking at the code we actually seem to have something like that, but only accessible through api (and it doesn't use katello's ansible-collection syncing). Considering noone seems to know its there and whether and how it works, maybe we shouldn't document it?

There is one other flow that can "import playbooks" - when you import roles it can also sort of pick up playbooks as well, but they will appear as ansible roles (not job templates) and sadly will break things when (relevant community thread) .

I can de-emphasize summarizing the contents of the module and instead focus on why this is relevant to users.

@adamruzicka Can you please review the new version of the abstract?

maximiliankolb · 2026-03-18T12:27:28Z

guides/common/modules/proc_importing-an-ansible-playbook-by-name.adoc

I am unsure about this. Would appreciate a tech ACK.

@adamruzicka Can you please review this abstract?

guides/common/modules/proc_changing-the-host-group-of-a-host.adoc

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

maximiliankolb

Looks good so far; three more minor suggestion & one open thread remain.

119/120.

guides/common/modules/proc_changing-the-host-group-of-a-host.adoc

...on/modules/proc_changing-the-lifecycle-environment-or-content-view-of-a-host-collection.adoc

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

aneta-petrova · 2026-03-19T15:24:20Z

A couple of clarifying questions, one very polite pushback on the whole via/through issue :) (https://github.com/theforeman/foreman-documentation/pull/4712/changes#r2960387106). I still need to find someone to tech review the updates where @maximiliankolb asked for an additional tech check.

maximiliankolb · 2026-03-20T07:10:16Z

one very polite pushback on the whole via/through issue

I am OK either way!

guides/common/modules/con_working-with-host-groups.adoc

guides/common/modules/con_adding-content-to-a-host-collection.adoc

guides/common/modules/con_configuring-host-collections.adoc

guides/common/modules/con_remote-execution-workflow.adoc

guides/common/modules/con_transport-modes-for-remote-execution.adoc

guides/common/modules/proc_enabling-custom-repositories-on-hosts.adoc

jeremylenz · 2026-03-24T13:07:12Z

guides/common/modules/proc_importing-all-available-ansible-playbooks.adoc

 [role="_abstract"]
-You can import all the available Ansible Playbooks to {Project} from collections installed on {SmartProxy}.
+You can import all available Ansible Playbooks to {Project} from collections installed on {SmartProxy}.
+{Project} creates a job template from each playbook so you can run them on hosts via remote execution without writing templates manually.


Agree that "creates a job template from each playbook" doesn't sound correct. I'm sure Adam will have more to say.

guides/common/modules/proc_installing-packages-on-a-host.adoc

guides/common/modules/proc_removing-a-package-from-a-host.adoc

guides/common/modules/proc_removing-content-from-a-host-collection.adoc

Update the reasoning for choosing transport modes to describe actual decision criteria (scalability vs. port restrictions) rather than circular descriptions of what each mode does. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Fix host collection and errata terminology Change "adding errata/content to host collections" to "applying errata" to accurately reflect that errata application is a remote execution operation, not adding content to collections. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Rename a module Rename a module Fix wording for installing packages on hosts in a host collection

Co-authored-by: Jeremy Lenz <jlenz@redhat.com>

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

Co-authored-by: Jeremy Lenz <jlenz@redhat.com>

nofaralfasi

I’d like to review this PR after addressing Jeremy’s comments (not all of them have been resolved yet). In addition, I think it would be best to get a review from someone on the Rocket team, especially for the network documentation part - perhaps Leos or Shim.

I also added a few small comments.

guides/common/modules/con_host-groups-overview.adoc

guides/common/modules/con_administering-hosts-in-project.adoc

guides/common/modules/proc_adding-errata-to-a-host.adoc

guides/common/modules/proc_restarting-applications-on-a-host.adoc

guides/common/modules/proc_applying-errata-to-hosts-in-a-host-collection.adoc

guides/common/modules/proc_adding-errata-to-a-host.adoc

guides/common/modules/proc_installing-packages-on-hosts-in-a-host-collection.adoc

guides/common/modules/con_managing-host-content-with-host-collections.adoc

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

guides/common/modules/con_configuring-host-collections.adoc

guides/common/modules/proc_removing-content-from-hosts-in-a-host-collection.adoc

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

aneta-petrova · 2026-03-30T13:18:22Z

I believe I've addressed all concerns. There are some pending requests for re-review. Thanks, everyone, for your inputs so far!

pr-processor bot added the Not yet reviewed label Mar 13, 2026

github-actions bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Mar 13, 2026

aneta-petrova removed Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Mar 13, 2026

aneta-petrova added 2 commits March 16, 2026 10:08

Review abstracts

f44d1d6

Update ID and file name to match heading

57cf580

aneta-petrova force-pushed the cqa-managing-hosts branch 3 times, most recently from 1ea9528 to 63ea89f Compare March 16, 2026 15:44

aneta-petrova changed the title ~~Review abstracts~~ Review abstracts and headings Mar 16, 2026

aneta-petrova force-pushed the cqa-managing-hosts branch from 63ea89f to 9b2dd4e Compare March 16, 2026 19:44

aneta-petrova added 2 commits March 16, 2026 20:58

Review headings

6f67491

Update module type

7a3d011

aneta-petrova force-pushed the cqa-managing-hosts branch from 9b2dd4e to 7a3d011 Compare March 16, 2026 19:59

aneta-petrova marked this pull request as ready for review March 16, 2026 20:05

maximiliankolb self-requested a review March 17, 2026 06:48

maximiliankolb reviewed Mar 17, 2026

View reviewed changes

pr-processor bot removed the Not yet reviewed label Mar 17, 2026

maximiliankolb reviewed Mar 17, 2026

View reviewed changes

Apply easy fixes from style review

7764c28

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

aneta-petrova changed the title ~~Review abstracts and headings~~ Review abstracts and headings in Managing hosts Mar 18, 2026

maximiliankolb reviewed Mar 18, 2026

View reviewed changes

aneta-petrova added this to the Prepare for DITA migration (RH) milestone Mar 18, 2026

aneta-petrova and others added 3 commits March 19, 2026 10:36

Apply suggestions from style review

8ca09d2

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

Apply suggestions from style review

b5c64d3

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

Apply feedback from style review

c1faa6c

aneta-petrova added 2 commits March 19, 2026 10:51

Rename a module

f04f183

Readd lines removed by mistake

c180412

maximiliankolb reviewed Mar 19, 2026

View reviewed changes

guides/common/modules/proc_changing-the-host-group-of-a-host.adoc Outdated Show resolved Hide resolved

...on/modules/proc_changing-the-lifecycle-environment-or-content-view-of-a-host-collection.adoc Outdated Show resolved Hide resolved

Apply suggestions from style review

36ad736

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

jeremylenz reviewed Mar 24, 2026

View reviewed changes

aneta-petrova and others added 6 commits March 27, 2026 22:03

Fix transport mode selection reasoning

dc8a7ac

Update the reasoning for choosing transport modes to describe actual decision criteria (scalability vs. port restrictions) rather than circular descriptions of what each mode does. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Apply suggestion from @jeremylenz

d750a9c

Co-authored-by: Jeremy Lenz <jlenz@redhat.com>

Apply suggestion from @maximiliankolb

7dd3a2c

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

Apply suggestion from @maximiliankolb

c87a0cf

Apply suggestion from @jeremylenz

2e634d7

Co-authored-by: Jeremy Lenz <jlenz@redhat.com>

nofaralfasi reviewed Mar 29, 2026

View reviewed changes

maximiliankolb reviewed Mar 30, 2026

View reviewed changes

aneta-petrova and others added 5 commits March 30, 2026 10:53

Apply easy fixes from tech review

7587d4c

Apply suggestions from style review

ebff0e0

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

Apply suggestions from style review

8b2f7b0

Apply feedback from tech review

cd67408

Reword abstract highlighted by tech review

b1c5ba0

maximiliankolb reviewed Mar 30, 2026

View reviewed changes

guides/common/modules/con_configuring-host-collections.adoc Outdated Show resolved Hide resolved

guides/common/modules/proc_removing-content-from-hosts-in-a-host-collection.adoc Outdated Show resolved Hide resolved

aneta-petrova and others added 3 commits March 30, 2026 14:03

Add the 'why' to an abstract about rex workflow

a047bc7

Apply ID fixes from style review

21a3350

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

Review Ansible playbook abstract to explain the 'why'

c5afe2e

aneta-petrova force-pushed the cqa-managing-hosts branch from 846daca to c5afe2e Compare March 30, 2026 12:39

	{Project} creates a job template from each playbook so you can run them on hosts via remote execution without writing templates manually.
	{Project} creates a job template from each playbook so you can run them on hosts through remote execution without writing templates manually.

Conversation

aneta-petrova commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

Uh oh!

github-actions bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

aneta-petrova commented Mar 19, 2026

Uh oh!

maximiliankolb commented Mar 20, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aneta-petrova commented Mar 13, 2026 •

edited

Loading

github-actions bot commented Mar 13, 2026 •

edited

Loading