Kernel Live Patching

[dmpop]

Description

Rewrite the Kernel Live Patching from scratch

Are there any relevant issues/feature requests?

• DOCTEAM-1270

Is this (based on) existing content?

• https://documentation.suse.com/sles/15-SP5/html/SLES-all/cha-klp.html
• https://documentation.suse.com/smart/deploy-upgrade/html/concept-klp/concept-klp.html

[taroth21]

Thank you, this works very well as a Smart Doc! Sorry for the large number of comments and suggestions but a great deal of them are about updating the metadata to the latest templates only.

Regarding the content, only some minor nitpicks. Many thanks!

[taroth21]

Suggested change

	<revhistory xml:id="rh-klp">
	<revision><date>2024-02-21</date>
	<revdescription>
	<itemizedlist>
	<!-- Group by type of change (added/removed/changed)-->
	<listitem>
	<para>
	Added sections:
	</para>
	<itemizedlist>
	<!-- Reference, but don't link to tracker items-->
	<!-- Follow https://en.opensuse.org/openSUSE:Packaging_Patches_guidelines#Current_set_of_abbreviations for tracker item references-->
	<listitem>
	<para>
	New section on <quote>foo</quote> to resolve issue
	<uri>bsc#12345</uri>
	</para>
	</listitem>
	<!-- Name sections, but don't insert links -->
	<listitem>
	<para>
	New section on <quote>foo bar</quote>
	</para>
	</listitem>
	</itemizedlist>
	</listitem>
	<listitem>
	<para>
	Removed sections:
	</para>
	<itemizedlist>
	<listitem>
	<para>
	Removed section on <quote>foo1</quote> to resolve issue
	<uri>bsc#12346</uri>
	</para>
	</listitem>
	<listitem>
	<para>
	Removed section on <quote>foo1 bar</quote>
	</para>
	</listitem>
	</itemizedlist>
	</listitem>
	<listitem>
	<para>
	Changed sections:
	</para>
	<itemizedlist>
	<listitem>
	<para>
	Changed section on <quote>foo2</quote> to resolve issue
	<uri>bsc#12347</uri>
	</para>
	</listitem>
	<listitem>
	<para>
	Changed section on <quote>foo2 bar</quote>
	</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</itemizedlist>
	</revdescription>
	</revision>
	</revhistory>
	<revhistory xml:id="rh-klp">
	<revision><date>2024-11-27</date>
	<revdescription>
	<para>
	Initial version
	</para>
	</revdescription>
	</revision>
	</revhistory>

[taroth21]

My suggestion is about adjusting the revhistory to the latest, simplified template (see https://github.com/openSUSE/doc-kit/blob/main/smart-doc/articles/assembly.asm.xml#L69 for reference)

[taroth21]

Suggested change

	<meta name="maintainer" content="" its:translate="no"/>
	<meta name="maintainer" content="[email protected]" its:translate="no"/>

[taroth21]

Suggested change

	<meta name="updated" content="2037-11-16" its:translate="no"/>
	<meta name="updated" content="2024-11-27" its:translate="no"/>

[taroth21]

Suggested change

	<dm:bugtracker>
	<dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
	<dm:component>Smart Docs</dm:component>
	<dm:product>Documentation</dm:product>
	<!-- provide your BUGZILLA e-mail address, otherwise this does not work correctly-->
	<dm:assignee>[email protected]</dm:assignee>
	</dm:bugtracker>
	<dm:bugtracker>
	<dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
	<dm:component>Documentation</dm:component>
	<dm:product>SUSE Linux Enterprise Server 16.0</dm:product>
	<dm:assignee>[email protected]</dm:assignee>
	</dm:bugtracker>

[taroth21]

Using the latest template for Bugzilla pointers (see https://github.com/openSUSE/doc-kit/blob/main/smart-doc/articles/assembly.asm.xml#L111 for reference)

[taroth21]

Suggested change

	<meta name="productname" its:translate="no">
	<!-- enter product name and version --><productname version="X.Y">&productname;</productname>
	<meta name="productname" its:translate="no">
	<productname version="15 SP6">&sles;</productname>

[taroth21]

Add missing metadata

[taroth21]

Suggested change

	<meta name="social-descr" its:translate="yes">&klp; on &slsa;</meta>
	<meta name="social-descr" its:translate="yes">Perform kernel live patching on &productnameshort;</meta>

[taroth21]

Suggested change

	The scope of &slea; Live Patching includes fixes for SUSE Common
	Vulnerability Scoring System (CVSS; SUSE CVSS is based on the CVSS v3.0
	system) level 7+ vulnerabilities and bug fixes related to system
	stability or data corruption. However, it may not be technically feasible
	to create live patches for all fixes that fall under the specified
	categories. &suse; therefore reserves the right to skip fixes in
	situations where creating a kernel live patch is not possible for
	technical reasons. Currently, over 95% of qualifying fixes are released
	as live patches. For more information on CVSS (the base for the SUSE CVSS
	rating), see <link xlink:href="https://www.first.org/cvss/">Common
	Vulnerability Scoring System SIG</link>.
	The scope of &slea; Live Patching includes fixes for SUSE Common
	Vulnerability Scoring System (CVSS) level 7+ vulnerabilities and bug fixes related to system
	stability or data corruption. However, it may not be technically feasible
	to create live patches for all fixes that fall under the specified
	categories. &suse; therefore reserves the right to skip fixes in
	situations where creating a kernel live patch is not possible for
	technical reasons. Currently, over 95% of qualifying fixes are released
	as live patches. SUSE CVSS is based on the CVSS v3.0
	system. For more information on CVSS, see <link xlink:href="https://www.first.org/cvss/">Common
	Vulnerability Scoring System SIG</link>.

[taroth21]

I suggested to move a part of the first sentences (content in parentheses) into a separate sentence at the end of the paragraph. That way it suits the link in the following sentence and makes the first sentence shorter and easier to grasp.

[taroth21]

Right now, "Live patches versus kernel updates" is a 'lone' section within section 2, which means there is section 2.1 but no 2.2 or 2.3. As the overall content of "Understanding kernel live patches" is brief, it does not make sense to subdivide the remaining content into more subsection. To avoid the lone section (see also https://documentation.suse.com/style/current/html/docu_styleguide/sec-structure.html#sec-outline-level) I would suggest to move the following content directly into the parent section and add a title to the figure below. This would help to avoid the lone section, while still highlighting the relationship/difference between live patches and kernel updates by adding a figure title.

[taroth21]

Suggested change

	<informalfigure>
	<mediaobject>
	<imageobject role="fo">
	<imagedata fileref="klp.png" width="100%"/>
	</imageobject>
	<imageobject role="html">
	<imagedata fileref="klp.png" width="100%"/>
	</imageobject>
	</mediaobject>
	</informalfigure>
	<figure>
	<title>Relationship between live patches and kernel updates</title>
	<mediaobject>
	<imageobject role="fo">
	<imagedata fileref="klp.png" width="100%"/>
	</imageobject>
	<imageobject role="html">
	<imagedata fileref="klp.png" width="100%"/>
	</imageobject>
	</mediaobject>
	</figure>

[taroth21]

I would turn the informalfigure into a <figure> and give it a title. This also makes it easier to see what the diagram is about when readers are just skimming the article.

[taroth21]

While this topic is categorized as 'task', the content of this topic is mixed. Some of the items below qualify as tasks, others are more of informational purpose. From my point of view, its content would fit well into other topics that already exist:

• Maybe you could move the first three items (and the last one) into the 'Troubleshooting' section and turn them into separate subsections there?

• I would move the content of the 4th listitem into the 'Understanding kernel live patches' section. It would fit well to the paragraphs where you talk about live patches vs. kernel versions.

Then you could remove this topic completely.