Skip to contentSkip to conversation

docs: ABI: make the KernelVersion field optional

PATCH Applied [email protected] 4 participants 6 messages Jun 26, 2025 – Jul 1, 2025 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: ABI: make the KernelVersion field optional

From: Alison Schofield <[email protected]>

The KernelVersion field has limited practical value. Git history provides more accurate tracking of when features were introduced and target kernel versions often change during development and merge.

Label it optional.

---

Plan B is to remove the field entirely.

 Documentation/ABI/README | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/ABI/README +3 -1
index ef0e6d11e919..315fffe1f831 100644
@@ -46,7 +46,9 @@ Every file in these directories will contain the following information:
 
 What:		Short description of the interface
 Date:		Date created
-KernelVersion:	Kernel version this feature first showed up in.
+KernelVersion:	(Optional) Kernel version this feature first showed up in.
+		Note: git history often provides more accurate version
+		info, so this field may be omitted.
 Contact:	Primary contact for this interface (may be a mailing list)
 Description:	Long description of the interface and how to use it.
 Users:		All users of this interface who wish to be notified when
Signature · 1 line
2.37.3
reviewer
#1 lore raw

Hi,

Quoted 23 lines · On 6/25/25 7:40 PM, [email protected] wrote:

From: Alison Schofield <[email protected]>

The KernelVersion field has limited practical value. Git history provides more accurate tracking of when features were introduced and target kernel versions often change during development and merge.

Label it optional.

---

Plan B is to remove the field entirely.

 Documentation/ABI/README | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/ABI/README +0 -0
index ef0e6d11e919..315fffe1f831 100644

Documentation/ABI/README Every file in these directories will contain the following information: · line 51

Quoted 7 lines
Documentation/ABI/README +3 -1
@@ -46,7 +46,9 @@ Every file in these directories will contain the following information:
 
 What:		Short description of the interface
 Date:		Date created
-KernelVersion:	Kernel version this feature first showed up in.
+KernelVersion:	(Optional) Kernel version this feature first showed up in.
+		Note: git history often provides more accurate version
+		info, so this field may be omitted.

ISTM that ABI files and git history have different users/audiences. Sure, KernelVersion may be incorrect (but close?), but telling a "user" that they should install git and clone linux.git to determine the kernel version is a lot to ask -- and then they need git instructions for how to look up the kernel version.

Quoted 3 lines
Documentation/ABI/README +0 -0
 Contact:	Primary contact for this interface (may be a mailing list)
 Description:	Long description of the interface and how to use it.
 Users:		All users of this interface who wish to be notified when
Signature · 1 line
~Randy
#2 lore raw
Quoted 27 lines · Randy Dunlap

Hi,

Quoted 24 lines · On 6/25/25 7:40 PM, [email protected] wrote:

From: Alison Schofield <[email protected]>

The KernelVersion field has limited practical value. Git history provides more accurate tracking of when features were introduced and target kernel versions often change during development and merge.

Label it optional.

---

Plan B is to remove the field entirely.

 Documentation/ABI/README | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/ABI/README +0 -0
index ef0e6d11e919..315fffe1f831 100644
@@ -46,7 +46,9 @@ Every file in these directories will contain the following information:
 
Quoted 12 lines

Documentation/ABI/README Every file in these directories will contain the following information: · line 51

Quoted 6 lines
Documentation/ABI/README +3 -1
 What:		Short description of the interface
 Date:		Date created
-KernelVersion:	Kernel version this feature first showed up in.
+KernelVersion:	(Optional) Kernel version this feature first showed up in.
+		Note: git history often provides more accurate version
+		info, so this field may be omitted.

ISTM that ABI files and git history have different users/audiences. Sure, KernelVersion may be incorrect (but close?), but telling a "user" that they should install git and clone linux.git to determine the kernel version is a lot to ask -- and then they need git instructions for how to look up the kernel version.

Hi Randy,

Thanks for the user viewpoint.

As Dan mentioned, it was his feedback on my use of the field that inspired this. I poked around a bit to see if omitting was becoming common practice and found that in ABI/testing, 41% of the entries omit the KernelVersion field (1423 out of 3431), and it's the same 41% for all of ABI/. That led me to believe this field is already being treated as optional by kernel developers.

I guess this is just shedding light on current practice. I have no insight into whether users are hollering about the missing KernelVersion fields.

--Alison

Quoted 8 lines
Quoted 4 lines
Documentation/ABI/README +0 -0
 Contact:	Primary contact for this interface (may be a mailing list)
 Description:	Long description of the interface and how to use it.
 Users:		All users of this interface who wish to be notified when
Signature · 1 line
~Randy
reviewer
#3 lore raw
Quoted 52 lines · Alison Schofield
Quoted 27 lines · Randy Dunlap

Hi,

Quoted 24 lines · On 6/25/25 7:40 PM, [email protected] wrote:

From: Alison Schofield <[email protected]>

The KernelVersion field has limited practical value. Git history provides more accurate tracking of when features were introduced and target kernel versions often change during development and merge.

Label it optional.

---

Plan B is to remove the field entirely.

 Documentation/ABI/README | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/ABI/README +0 -0
index ef0e6d11e919..315fffe1f831 100644
@@ -46,7 +46,9 @@ Every file in these directories will contain the following information:
 
Quoted 12 lines

Documentation/ABI/README Every file in these directories will contain the following information: · line 51

Quoted 6 lines
Documentation/ABI/README +3 -1
 What:		Short description of the interface
 Date:		Date created
-KernelVersion:	Kernel version this feature first showed up in.
+KernelVersion:	(Optional) Kernel version this feature first showed up in.
+		Note: git history often provides more accurate version
+		info, so this field may be omitted.

ISTM that ABI files and git history have different users/audiences. Sure, KernelVersion may be incorrect (but close?), but telling a "user" that they should install git and clone linux.git to determine the kernel version is a lot to ask -- and then they need git instructions for how to look up the kernel version.

Hi Randy,

Thanks for the user viewpoint.

As Dan mentioned, it was his feedback on my use of the field that inspired this. I poked around a bit to see if omitting was becoming common practice and found that in ABI/testing, 41% of the entries omit the KernelVersion field (1423 out of 3431), and it's the same 41% for all of ABI/. That led me to believe this field is already being treated as optional by kernel developers.

Quoted 3 lines

I guess this is just shedding light on current practice. I have no insight into whether users are hollering about the missing KernelVersion fields.

I see. Please continue with your patch then.

Thanks.

Signature · 1 line
~Randy
Acked-by on v1 1/1
#4 lore raw
In reply to [email protected]
Quoted 10 lines · alison.schofield@ wrote:

From: Alison Schofield <[email protected]>

The KernelVersion field has limited practical value. Git history provides more accurate tracking of when features were introduced and target kernel versions often change during development and merge.

Label it optional.

I gave this feedback as a review comment and support this.

However, this document is quite old and, for example, says about "Users:":

"This is very important for interfaces in the 'testing' stage,"

The Users: tag only appears in 49 out of the 564 testing/ files.

Moreover, the testing/ stable/ distinction has lost meaning over time.

So, yes, marking KernelVersion: as explicitly optional is maybe an improvement, but there are wider issues here, and leaving well enough alone is also a reasonable outcome in that light.

Quoted 3 lines

---

Plan B is to remove the field entirely.

I do not want to motivate a slew of "cleanup" patches removing it from other files, so "optional" makes sense.

I think What: and Description: are mandatory, everything else is optional and maybe note that an ABI is "stable" the moment it is in a released kernel and a real world use case starts depending on it.

The pain of removing or renaming the stable/ and testing/ directories is probably not worth it given the potential to break links that people have to these Documentation files.

maintainer Applied
#5 lore raw
In reply to [email protected]
Quoted 23 lines · [email protected] writes:

From: Alison Schofield <[email protected]>

The KernelVersion field has limited practical value. Git history provides more accurate tracking of when features were introduced and target kernel versions often change during development and merge.

Label it optional.

---

Plan B is to remove the field entirely.

 Documentation/ABI/README | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/ABI/README +0 -0
index ef0e6d11e919..315fffe1f831 100644

Documentation/ABI/README Every file in these directories will contain the following information: · line 52

Quoted 8 lines
Documentation/ABI/README +3 -1
@@ -46,7 +46,9 @@ Every file in these directories will contain the following information:
 
 What:		Short description of the interface
 Date:		Date created
-KernelVersion:	Kernel version this feature first showed up in.
+KernelVersion:	(Optional) Kernel version this feature first showed up in.
+		Note: git history often provides more accurate version
+		info, so this field may be omitted.
 Contact:	Primary contact for this interface (may be a mailing list)

Applied, thanks.

jon