Skip to content

Conversation

aneta-petrova
Copy link
Member

@aneta-petrova aneta-petrova commented Sep 24, 2025

What changes are you introducing?

  • Adding [role="_abstract"] to introductions
  • Slightly changing the structure of two assemblies to be able to remove short sections that are not suitable for an abstract
  • Making minor changes to abstracts where required (for example, to ensure each abstract works as a standalone paragraph).

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

To resolve the ShortDescription issues reported by https://github.com/jhradilek/asciidoctor-dita-vale

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

Further changes to abstract are to be expected in the future because the requirements for them are evolving and asciidoctor-dita-vale will include more rules. For now, this PR at least moves us one step closer to being migration-ready.

One additional commit adds a style definition for [role="_abstract"] for easier review. This should be removed before merging.

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.16/Katello 4.18 (Satellite 6.18)
  • Foreman 3.15/Katello 4.17
  • Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4)
  • 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)
  • Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9; orcharhino 7.1 with Leapp)
  • Foreman 3.10/Katello 4.12
  • Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
  • We do not accept PRs for Foreman older than 3.9.

@github-actions 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 Sep 24, 2025
Copy link

github-actions bot commented Sep 24, 2025

@aneta-petrova 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 Sep 24, 2025
@aneta-petrova aneta-petrova force-pushed the security_abstract branch 2 times, most recently from 6753181 to 3b51194 Compare October 1, 2025 16:12
@aneta-petrova aneta-petrova added the Needs style review Requires a review from docs style/grammar perspective label Oct 1, 2025
@aneta-petrova aneta-petrova marked this pull request as ready for review October 1, 2025 16:13
@aneta-petrova
Copy link
Member Author

This should now be ready for style review. Please? :)

The list of affected guides is long but that's only because of the commit to also highlight the abstracts. That should be removed before merging. In truth, only the security compliance guide is affected:

https://theforeman-foreman-documentation-preview-pr-4299.surge.sh/nightly/Managing_Security_Compliance/index-foreman-deb.html
https://theforeman-foreman-documentation-preview-pr-4299.surge.sh/nightly/Managing_Security_Compliance/index-foreman-el.html
https://theforeman-foreman-documentation-preview-pr-4299.surge.sh/nightly/Managing_Security_Compliance/index-katello.html
https://theforeman-foreman-documentation-preview-pr-4299.surge.sh/nightly/Managing_Security_Compliance/index-orcharhino.html
https://theforeman-foreman-documentation-preview-pr-4299.surge.sh/nightly/Managing_Security_Compliance/index-satellite.html

Because this is a DITA migration prep PR, I'd like to avoid the need for a tech review. The intended scope is summarized in the PR's description. (TL;DR: I'm trying to make sure each abstract can work as a standalone paragraph and I think that's good enough for now because the requirements for abstracts keep evolving on the RH side.)

@Lennonka Lennonka 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 Oct 2, 2025
@aneta-petrova
Copy link
Member Author

Thank you @Lennonka! Per the PR's description, I'm dropping the commit that adds the style before merging.

@aneta-petrova aneta-petrova merged commit 12cd0e6 into theforeman:master Oct 3, 2025
9 of 10 checks passed
aneta-petrova added a commit that referenced this pull request Oct 3, 2025
* Add [role=_abstract]

* Group SCAP cons and refs in an assembly

This will help with adjusting the abstracts.

* Regroup modules in Configuring compliance methods assembly

* Identify and move abstract-type info to abstract

(cherry picked from commit 12cd0e6)
@aneta-petrova
Copy link
Member Author

Merged to "master" and cherry-picked:

6be0d40..f31c50c 3.16 -> 3.16

@aneta-petrova aneta-petrova deleted the security_abstract branch October 3, 2025 06:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
style review done No issues from docs style/grammar perspective
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants