From: Prarit Bhargava prarit@redhat.com
redhat/docs: Add a description of kernel naming
Add a file that describes how kernel NVRs are constructed.
Signed-off-by: Prarit Bhargava prarit@redhat.com
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:NamingGuideline... <https://fedoraproject.org/wiki/Packaging:Naming?rd=Packaging:NamingGuideline....
-- https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779
From: Herton R. Krzesinski on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9452479...
I think you mean SPECKSUBLEVEL at the beginning here.
From: Thorsten Leemhuis on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9454636...
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?
From: Thorsten Leemhuis on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9455572...
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?
From: Prarit Bhargava on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458311...
Yep. Fixed.
From: Prarit Bhargava on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458377...
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.
From: Prarit Bhargava on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458461...
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.
From: Thorsten Leemhuis on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458546...
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?
From: Thorsten Leemhuis on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458729...
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
From: Prarit Bhargava on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9458776...
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?
From: Neal Gompa on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9466352...
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.
From: Thorsten Leemhuis on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9468546...
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.
From: Herton R. Krzesinski on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9482542...
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.
From: Justin M. Forbes on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9483789...
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.
From: Patrick Talbert on gitlab.com https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1779#note_9714239...
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.
kernel@lists.fedoraproject.org
-
Herton R. Krzesinski (via Email Bridge) -
Justin M. Forbes (via Email Bridge)
-
Neal Gompa (via Email Bridge)
-
Patrick Talbert (via Email Bridge)
-
Prarit Bhargava (via Email Bridge)
-
Thorsten Leemhuis (via Email Bridge)