Add CLI procedure for syncing content view

[bangelic]

A CLI procedure for synchronizing a content view has been added to the
Content Management Guide related to
https://issues.redhat.com/browse/SAT-13027.

• 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.11/Katello 4.13
• Foreman 3.10/Katello 4.12
• Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
• Foreman 3.8/Katello 4.10
• Foreman 3.7/Katello 4.9 (Satellite 6.14)
• Foreman 3.6/Katello 4.8
• Foreman 3.5/Katello 4.7 (Satellite 6.13; orcharhino 6.6/6.7)
• We do not accept PRs for Foreman older than 3.5.

[github-actions]

The PR preview for 4b4b514 is available at theforeman-foreman-documentation-preview-pr-3235.surge.sh

The following output files are affected by this PR:

• Managing_Content/index-katello.html
• Managing_Content/index-orcharhino.html
• Managing_Content/index-satellite.html

show diff

show diff as HTML

[maximiliankolb]

hammer proxy content synchronize is present on Foreman 3.11 ✔️

However, I think we should drop the output from "--help" and instead add a short description of what it does and which options are required.

I also have concerns about the title: It indicates that you can synchronize remote content to Foreman based on content views. However, the Hammer CLI command looks like it's about synchronizing CVs from Foreman Server to Smart Proxy Servers based on CVs. Please clarify or correct me.

[asteflova]

@bangelic Can you provide more details about why you are adding this? For example, if this is a new command, I would argue that you don't need a full section (just a release note could be enough). If there is a customer case that requests documenting the command, you could just mention it in another section (preferably in a procedure that customer was following when they hit the issue).

Without further clarification as to where the request to add the command comes from, I would not support adding a section like this. I find it hard to imagine a scenario where adding this section would do more than simply duplicate a --help output.

[ianballou]

@asteflova I think some documentation mentioning that this functionality is available past a release note would be helpful, it's a unique feature in that you can only do it via hammer. Users might not think to look in the hammer help text to discover that the feature is possible.
If an entire new section is too much, how about mentioning it (without too many details?) wherever we document syncing smart proxies in general?

[asteflova]

@asteflova I think some documentation mentioning that this functionality is available past a release note would be helpful, it's a unique feature in that you can only do it via hammer. Users might not think to look in the hammer help text to discover that the feature is possible.

Fair enough, thanks for the details.

If an entire new section is too much, how about mentioning it (without too many details?) wherever we document syncing smart proxies in general?

That could definitely work. If we have a procedure during which users might need that new command, it would be good to mention it there.

If we don't have an existing procedure like that, I think the new command should also appear in the Hammer CLI guide, right? So a release note could link to the appropriate section in the Hammer CLI guide.

[bangelic]

hammer proxy content synchronize is present on Foreman 3.11 ✔️

However, I think we should drop the output from "--help" and instead add a short description of what it does and which options are required.

I also have concerns about the title: It indicates that you can synchronize remote content to Foreman based on content views. However, the Hammer CLI command looks like it's about synchronizing CVs from Foreman Server to Smart Proxy Servers based on CVs. Please clarify or correct me.

@maximiliankolb I think that @ianballou will be able to clarify but he will be on PTO until 9/13. Will check with him when he returns.

[ianballou]

However, I think we should drop the output from "--help" and instead add a short description of what it does and which options are required.

I think this would be covered by the short discussion I had with @asteflova above. No need for the help text, but an addition to the smart proxy syncing guide that mentions hammer can be used to sync content views (and even repositories!) from Foreman to smart proxies via hammer {hammer-smart-proxy} content synchronize. I don't think more details are needed since the user can use the hammer help text.

I also have concerns about the title: It indicates that you can synchronize remote content to Foreman based on content views. However, the Hammer CLI command looks like it's about synchronizing CVs from Foreman Server to Smart Proxy Servers based on CVs. Please clarify or correct me.

I agree. This comment might have different context now based on what I mentioned above, but just make sure it's clear the syncing is from Foreman to smart proxies.