[OS-BUILD PATCH] redhat/docs: Add a description of kernel naming

[Prarit Bhargava (via Email Bridge)]

From: Prarit Bhargava <prarit(a)redhat.com&gt;

redhat/docs: Add a description of kernel naming

Add a file that describes how kernel NVRs are constructed.

Signed-off-by: Prarit Bhargava <prarit(a)redhat.com&gt;

diff --git a/redhat/docs/index.rst b/redhat/docs/index.rst
index blahblah..blahblah 100644
--- a/redhat/docs/index.rst
+++ b/redhat/docs/index.rst
@@ -111,6 +111,7 @@ Contributor Guide
    submitting-contributions
    faq
    makefile-changes
+   kernel-naming
 
 
 Maintainer Guide
diff --git a/redhat/docs/kernel-naming.rst b/redhat/docs/kernel-naming.rst
new file mode 100644
index blahblah..blahblah 100644
--- /dev/null
+++ b/redhat/docs/kernel-naming.rst
@@ -0,0 +1,44 @@
+.. _kernel-naming:
+
+=============
+Kernel Naming
+=============
+
+The kernel NVR looks like, for example,
+kernel-5.17.0-0.rc8.551acdc3c3d2.124.test.fc35.  This string contains
+information about the upstream release, a unique build number, and information
+about the distribution the RPM was targeted for.  An explanation of each of the
+fields and how the fields are used in the kernel NVR, is below.
+
+**PACKAGE_NAME**: This is the name of the package.  By default this is
+'kernel', but a well-known variant is kernel-rt.
+
+**SPECKVERSION**: This is the VERSION variable defined in the top-level linux
+Makefile.
+
+**SPECKPATCHLEVEL**: This is the PATCHLEVEL variable defined in the top-level
+linux Makefile.
+
+**SUBLEVEL**: This is the SUBLEVEL variable defined in the top-level linux
+Makefile.
+
+**UPSTREAMBUILD**: This is a representation of the upstream build information.
+It includes the EXTRAVERSION variable (defined in the top-level Makefile) or
+'rc0' if the tree is based on an a specific upstream release.  If the tree is
+not based on a specific "rc" release, this field also contains a git hash
+reference to the top of tree commit.
+
+**BUILD**: This is the RHEL_RELEASE variable defined in the top-level linux
+Makefile.rhelver.
+
+**LOCALVERSION**: By default, this variable is set to ".test".  This value can
+be overriden by defining a string in redhat/localversion.
+
+**DIST**:  This is the dist release suffix used in the package release, eg.
+.fc34 or .el9.
+
+The kernel name is constructed as
+
+$(PACKAGE_NAME)-$(SPECKVERSION).$(SPECKPATCHLEVEL).$(SPECKSUBLEVEL)-$(UPSTREAMBUILD)$(BUILD)$(LOCALVERSION)$(DIST)
+
+In general, the kernel follows the Fedora Naming Guidelines,
`https://fedoraproject.org/wiki/Packaging:Naming?rd=Packaging:NamingGuidelines
<https://fedoraproject.org/wiki/Packaging:Naming?rd=Packaging:NamingGuidel....

--
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779

[Herton R. Krzesinski (via Email Bridge)]

From: Herton R. Krzesinski on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9452...

I think you mean SPECKSUBLEVEL at the beginning here.

[Thorsten Leemhuis (via Email Bridge)]

From: Thorsten Leemhuis on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9454...

Just out of curiosity, as it looks inconsistent (but I guess there might be a
deeper reasoning behind if): why has one variable a "PACKAGE" prefix (with
underscore behind it), and two a "SPECK" prefix (with no underscore after it)
and the other one no prefix at all?

[Thorsten Leemhuis (via Email Bridge)]

From: Thorsten Leemhuis on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9455...

Ohh, and another quick comment: with all the changes you are currently
preparing for the makefiles, how hard would it be to start making things like
this a bit more neutral for non-RHEL platforms? Something like
s/RHEL_RELEASE/ARK_RELEASE/ maybe?

[Prarit Bhargava (via Email Bridge)]

From: Prarit Bhargava on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458...

Yep.  Fixed.

[Prarit Bhargava (via Email Bridge)]

From: Prarit Bhargava on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458...

> Just out of curiosity, as it looks inconsistent (but I guess there
> might be a 
deeper reasoning behind if): why has one variable a "PACKAGE"
prefix (with
underscore behind it), and two a "SPECK" prefix (with no underscore after it)
and the other one no prefix at all?

@knurd42, variables prefixed with SPEC are those variables that are copied
into the specfile.  Other variables currently have no naming convention.
I added the "SPEC" rule because it was not possible to track which
variables directly affected the SPEC file and which were used for other
reasons in the Makefile.

FWIW, I don't like PACKAGE_NAME either.  I considered changing it to
PKGNAME but unfortunately there are SIGs and likely other clones using it.
the kernel-rt group certainly is setting PACKAGE_NAME="kernel-rt" for
their builds.  Changing it would require a significant effort for those
groups and it isn't a big deal.

[Prarit Bhargava (via Email Bridge)]

From: Prarit Bhargava on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458...

> Ohh, and another quick comment: with all the changes you are currently
preparing for the makefiles, how hard would it be to start making things like
this a bit more neutral for non-RHEL platforms? Something like
s/RHEL_RELEASE/ARK_RELEASE/ maybe?

I've seen two trains of thought on these types of changes and I'm leaning
towards not making these types of changes.  The first, is that changing
RHEL/rhel references to ARK/(ark or dist) is not worth it and is a
significant amount of change.  It's also a headache for the RHEL
maintainers when ARK is snapshotted for a particular RHEL release.

The second, which is one you are advocating for, is that we should be (as
you said) "more neutral" for non-RHEL clones.  There is some merit in
that, but one comment I heard when I tried to de-rhel-ify some of the code
and Makefiles was that it wasn't worth it to make these types of changes.

Of course, as with all things code related, I can be convinced otherwise.

[Thorsten Leemhuis (via Email Bridge)]

From: Thorsten Leemhuis on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458...

>  which variables directly affected the SPEC file and which were used
> for 
other reasons in the Makefile.

But is that relevant for people that do anything with kernel-ark or only
useful to make the Makefiles more readable? If it's just the latter I'd say
it's more confusing then helpful.

This got me thinking: the document added by this patch afaics doesn't even
tell me what I can do with the variable names I just learned from that text.
Or am I missing something?

I assume I can pass them to make (say `make dist-srpm BUILD=123` ?), but
shouldn't the text explain this?

[Thorsten Leemhuis (via Email Bridge)]

From: Thorsten Leemhuis on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458...

>  that changing RHEL/rhel references to ARK/(ark or dist) is not worth
> it 
I'd say they are, as such small details send a subliminal message to external
participators and IMHO can be discouraging for them, as they give some small
"this is a RHEL thing, don't interfere" vibes. But no worries, not your
fault,
I guess some higher ups first need to decide that some de-redhating is a good
idea and rest my case :-D

[Prarit Bhargava (via Email Bridge)]

From: Prarit Bhargava on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458...

> > which variables directly affected the SPEC file and which were
> used for 
other reasons in the Makefile.
> But is that relevant for people that do anything with kernel-ark or only 
useful to
make the Makefiles more readable? If it's just the latter I'd say
it's more confusing then helpful.
>  
I'd argue it's to make the Makefile more readable and easier for us to
debug.  But I would disagree with the confusing statement.  The variables
that users can use are defined in redhat/Makefile.variables (see rest of
my answer below)

> This got me thinking: the document added by this patch afaics
> doesn't even 
tell me what I can do with the variable names I just learned from
that text.
Or am I missing something?
>  
redhat/docs/makefile-changes.rst already exists and explains the layout.
I think that is sufficient but since documentation can ALWAYS be improved
patches are definitely welcomed :)

> I assume I can pass them to make (say `make dist-srpm BUILD=123` ?),
> but 
shouldn't the text explain this?

Maybe adding something like "Variables in this file can be overridden on
the command line." to the Makefile.variables section with your example?

[Neal Gompa (via Email Bridge)]

From: Neal Gompa on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9466...

Well, on the flip side: ARK _is_ the RHEL configuration. Pretending it isn't
does everyone a disservice. I actually wish that they just called it "rhel",
since changes there need to be approved by RHEL anyway.

[Thorsten Leemhuis (via Email Bridge)]

From: Thorsten Leemhuis on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9468...

>  Well, on the flip side: ARK is the RHEL configuration. 
Sorry, can't follow, so: Why? Some people will use kernel-ark just to build a
new Fedora kernel (or some distro based on Fedora) and won't care about RHEL
at all. Same for CentOS Stream and external RHEL clones, but there the
connection to RHEL obviously is closer.

[Herton R. Krzesinski (via Email Bridge)]

From: Herton R. Krzesinski on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9482...

I have the same feeling as Neal, in which ark is rhel and we can have it as
rhel. We have ark for historic reasons when the common kernel was introduced
for rhel/fedora (except for config differences, flavours in spec files, some
rhel only patches mostly). So either it's rhel or fedora the common base of
all, if it wasn't for rhel in the name, it would be fedora may be, not a
common name (I don't remember a case like other project which have a common
name where others inherit, it's always a project which is released and other
built upon that). But that's not something bad or discouraging I think, just
the way it is due history, rhel was more secret in the past but that's not
true anymore with the way centos is today.

[Justin M. Forbes (via Email Bridge)]

From: Justin M. Forbes on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9483...

A lot of the places RHEL is referenced are because they are RHEL bits. Fedora
doesn't care what RHEL release is set to.  The only real interaction I have
with RHEL bits doing Fedora specific work is if I change something in common,
and the RHEL config breaks (ELN is a different story as that is the RHEL
kernel). I also do some  stripping out of RHEL specific patches for Fedora
stable releases, though many of those are being removed from the tree anyway.
So I don't feel that most people working with Fedora have to care about the
RHEL specific bits at all really.  But there is no reason to hide that they do
exist.

[Patrick Talbert (via Email Bridge)]

From: Patrick Talbert on gitlab.com
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9714...

I am resolving this for now. If need be the discussion can be carried on in
the mailing list or as a GL Issue here.