-
Notifications
You must be signed in to change notification settings - Fork 685
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a section guiding through the process of rule divergence #10763
Conversation
The failures on Fedora Rawhide is expected due to OpenSCAP/openscap#1995. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the PR I have left many comments through the file.
I will note that I had hard time figuring out how the headings where working under "Aspects to consider when picking one approach" section. I would suggest at least using bold for text that you are using a header.
For example:
Stability
##### Conditionals
If I'm reading the markdown file I think that is something missing (it's not as bad when viewing the rendered file, but screen readers that depend section headers might get confused. I was assuming header was starting something new. However, I believe that you using Stability
as some sort of header that is above (logically) Conditionals.
If you have any other questions please reach out.
|
||
By design it is expected that the rules in the project will be shared and used by the supported products. And during the lifespan of a product a component may change and require that one or more rules be updated. | ||
|
||
When a component supported by CaC undergoes changes, it is essential to update and align the rules configuring it in the project accordingly. This is necessary to keep the rules in the project up to date and relevant. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One sentence per line.
|
||
- The ability to define extendable controls may mitigate the shortcomings mentioned right above. | ||
|
||
Content Clarity |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would suggest making these pseudo headings bold, to help communicate these are heading like objects.
Co-authored-by: Matthew Burket <m@tthewburket.com>
and generally improve style
Code Climate has analyzed commit 9a66afd and detected 0 issues on this pull request. The test coverage on the diff in this pull request is 100.0% (50% is the threshold). This pull request will bring the total coverage in the repository to 53.4% (0.0% change). View more on Code Climate. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the improvements, this is a great addition to the docs.
Waving the Automatus Sanity, the fail is not related to this PR. |
Description:
Expand the dev guide with content regarding how to deal with changes in systems that could be typically solved either by complicating existing rules, or creating new ones. The new section makes it easier to pick the right poison.
Rationale:
Although that class of problems typically doesn't have clearly good or clearly bad solutions, approaching the problem systematically is always beneficial.