Split Administering hosts into multiple assemblies by aneta-petrova · Pull Request #4758 · theforeman/foreman-documentation

aneta-petrova · 2026-04-08T20:27:18Z

What changes are you introducing?

Introducing several smaller, focused assemblies in place of the existing catch-all "Administering hosts" assembly.

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

Each assembly should cover a single user story (this is part of the downstream Content Quality Assessment (CQA) initiative.)

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

I'm not changing anything about the modules themselves, I'm just moving them around.

I used the skill from #4723 for a first draft and I'd say it got about half of the changes right on the first try, so it did a lot of heavy lifting for me, which was very useful.

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-04-08T20:31:41Z

The PR preview for 9ce5abc is available at theforeman-foreman-documentation-preview-pr-4758.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

Each assembly should describe a single user story only Assisted-by: Cursor

maximiliankolb

Great PR overall. I made some suggestions.

maximiliankolb · 2026-04-09T05:53:39Z

+= Managing host placement and associations
+
+[role="_abstract"]
+Use {Project} to link each host to a compute resource, organization, location, and content view environment.


This feels very vague to me.

What does "link" mean? You cannot just say "move host A from Azure to GCE". Instead, you'd have to redeploy it and delete the old one. That only works well if you have its configuration as code.

Would "associate" work better? That's what I tried to address your comment.

maximiliankolb · 2026-04-09T05:57:50Z

+
+[role="_abstract"]
+Use {Project} to link each host to a compute resource, organization, location, and content view environment.
+Detach host records when hosts move or retire so your host list stays current.


Suggested change

Detach host records when hosts move or retire so your host list stays current.

Detach host records when hosts move or retire so your host list stays current and {Project} no longer tries to manage it.

Unsure about this too. Does detach mean unregister on the Client or mark as unassociated in Foreman/delete in Foreman?

This was an attempt to describe the use case. I struggled to come up with a better one. If the new use case description is off too, then perhaps we don't have to add a use case and the first line of the abstract could also be enough?

Lennonka · 2026-04-09T07:52:24Z

This might be out of scope for this PR, but it would be great if we could move 20. Host status in Foreman under the first chapter Reviewing hosts... Just for your consideration :)

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

aneta-petrova · 2026-04-13T08:42:29Z

This might be out of scope for this PR, but it would be great if we could move 20. Host status in Foreman under the first chapter Reviewing hosts... Just for your consideration :)

Still within the scope of creating a new assembly and a good idea, thanks! Implemented.

aneta-petrova · 2026-04-13T08:59:56Z

I addressed all comments, and would appreciate @maximiliankolb's re-review to see if I interpreted his hints correctly.

Lennonka

LGTM

maximiliankolb · 2026-04-14T18:56:11Z

@aneta-petrova I can have a look at it on Monday. Please ping me if there's no comment by Monday 3pm.

maximiliankolb · 2026-04-20T11:42:01Z

+= Managing host placement and associations
+
+[role="_abstract"]
+Use {Project} to associate each host with a compute resource, organization, location, and content view environment.


this is unclear to me. What do you mean by "associate"?

I would split this: You can assign an org/loc to a host; a host may run on a compute resource (unless bare metal); a host may have a CV env (if katello; even then it is optional IMHO).

It's proving difficult to meet the requirements for abstracts when the assembly is somewhat generic :/ The guidelines I'm working with are written down in https://github.com/theforeman/foreman-documentation/pull/4778/changes. And I'm trying to avoid just listing the features in the included procedures because that's not what an abstract should be about.

I gave this another try. This time, I'm carefully avoiding the verb 'associate' and also the term 'infrastructure resources'. I thought that perhaps 'context-defining resources' could work? I'm just trying to find one term that describes the stuff you use to manage the hosts in the procedures included in the assembly :) What do you think now @maximiliankolb? Am I getting closer to something acceptable?

maximiliankolb · 2026-04-20T11:42:18Z

+
+[role="_abstract"]
+Use {Project} to associate each host with a compute resource, organization, location, and content view environment.
+This helps you keep your hosts aligned with appropriate infrastructure resources.


This is also unclear to me.

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

Assisted-by: Cursor

maximiliankolb

One last suggestion.

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

maximiliankolb

Thanks Anet, LGTM.

* Split Administering hosts into multiple assemblies Each assembly should describe a single user story only Assisted-by: Cursor --------- Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de> (cherry picked from commit 9f4cabf) (cherry picked from commit b7b0b1e)

* Split Administering hosts into multiple assemblies Each assembly should describe a single user story only Assisted-by: Cursor --------- Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de> (cherry picked from commit 9f4cabf)

aneta-petrova · 2026-04-21T12:45:17Z

Merged to "master" and cherry-picked:

855d1da..96a9074 3.18 -> 3.18
98ae3ce..b7b0b1e 3.17 -> 3.17
7c8eab9..e559981 3.16 -> 3.16

* Split Administering hosts into multiple assemblies Each assembly should describe a single user story only Assisted-by: Cursor --------- Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

pr-processor Bot added the Not yet reviewed label Apr 8, 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 Apr 8, 2026

aneta-petrova force-pushed the ustory-administering-hosts branch from b70be75 to 61922e5 Compare April 8, 2026 20:44

aneta-petrova removed Needs tech review Requires a review from the technical perspective Needs testing Requires functional testing labels Apr 8, 2026

Split Administering hosts into multiple assemblies

6a01de6

Each assembly should describe a single user story only Assisted-by: Cursor

aneta-petrova force-pushed the ustory-administering-hosts branch from 61922e5 to 6a01de6 Compare April 8, 2026 20:50

aneta-petrova marked this pull request as ready for review April 8, 2026 20:57

maximiliankolb reviewed Apr 9, 2026

View reviewed changes

pr-processor Bot removed the Not yet reviewed label Apr 9, 2026

Lennonka added the Waiting on contributor Requires an action from the author label Apr 9, 2026

Apply suggestion from @maximiliankolb

9a90646

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

pr-processor Bot added Needs re-review and removed Waiting on contributor Requires an action from the author labels Apr 13, 2026

aneta-petrova and others added 3 commits April 13, 2026 10:29

Apply suggestion from @maximiliankolb

6854315

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

Exclude tracer assebmly from non-katello builds as a whole

e666ee1

Move host status to reviewing host status

69f936c

Update abstract to avoid the verb 'link'

fed517e

pr-processor Bot removed the Needs re-review label Apr 13, 2026

aneta-petrova force-pushed the ustory-administering-hosts branch from ed8453e to 370478e Compare April 13, 2026 08:58

aneta-petrova requested a review from maximiliankolb April 13, 2026 08:59

Replace an inaccurate use case from in an abstract

7e96489

aneta-petrova force-pushed the ustory-administering-hosts branch from 370478e to 7e96489 Compare April 13, 2026 10:21

Lennonka approved these changes Apr 14, 2026

View reviewed changes

maximiliankolb requested changes Apr 20, 2026

View reviewed changes

pr-processor Bot added the Waiting on contributor Requires an action from the author label Apr 20, 2026

Apply suggestion from @maximiliankolb

041c500

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

pr-processor Bot added Needs re-review and removed Waiting on contributor Requires an action from the author labels Apr 20, 2026

Rewrite abstract to clarify 'what' and 'why'

42353b5

Assisted-by: Cursor

pr-processor Bot removed the Needs re-review label Apr 20, 2026

Lennonka reviewed Apr 20, 2026

View reviewed changes

Comment thread guides/common/assembly_managing-host-placement-and-associations.adoc

maximiliankolb reviewed Apr 21, 2026

View reviewed changes

Comment thread guides/common/modules/con_managing-host-placement-and-associations.adoc Outdated

Apply suggestion from @maximiliankolb

9ce5abc

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

aneta-petrova force-pushed the ustory-administering-hosts branch from 3d1b111 to 9ce5abc Compare April 21, 2026 06:49

aneta-petrova requested a review from maximiliankolb April 21, 2026 06:50

maximiliankolb approved these changes Apr 21, 2026

View reviewed changes

maximiliankolb added style review done No issues from docs style/grammar perspective and removed Needs style review Requires a review from docs style/grammar perspective labels Apr 21, 2026

aneta-petrova merged commit 9f4cabf into theforeman:master Apr 21, 2026
10 of 11 checks passed

aneta-petrova deleted the ustory-administering-hosts branch April 21, 2026 12:37

This was referenced Apr 21, 2026

Add Cursor skill to review assemblies for single user story #4723

Open

Split Registering hosts into multiple assemblies #4793

Merged

	Detach host records when hosts move or retire so your host list stays current.
	Detach host records when hosts move or retire so your host list stays current and {Project} no longer tries to manage it.

Conversation

aneta-petrova commented Apr 8, 2026

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 Apr 8, 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!

maximiliankolb Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

aneta-petrova Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

maximiliankolb Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

aneta-petrova Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Lennonka commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aneta-petrova commented Apr 13, 2026

Uh oh!

aneta-petrova commented Apr 13, 2026

Uh oh!

Lennonka left a comment

Choose a reason for hiding this comment

Uh oh!

maximiliankolb commented Apr 14, 2026

Uh oh!

maximiliankolb Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

aneta-petrova Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

maximiliankolb Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

maximiliankolb left a comment

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!

aneta-petrova commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Apr 8, 2026 •

edited

Loading

Lennonka commented Apr 9, 2026 •

edited

Loading