[PATCH] docs: ABI: make the KernelVersion field optional

[PATCH] docs: ABI: make the KernelVersion field optional

[alison.schofield]

From: Alison Schofield <alison.schofield@intel.com>

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.

Signed-off-by: Alison Schofield <alison.schofield@intel.com>
---

Plan B is to remove the field entirely. 


 Documentation/ABI/README | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index ef0e6d11e919..315fffe1f831 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -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
-- 
2.37.3

Re: [PATCH] docs: ABI: make the KernelVersion field optional

[Randy Dunlap]

Hi,

On 6/25/25 7:40 PM, alison.schofield@intel.com wrote:
> From: Alison Schofield <alison.schofield@intel.com>
> 
> 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.
> 
> Signed-off-by: Alison Schofield <alison.schofield@intel.com>
> ---
> 
> Plan B is to remove the field entirely. 
> 
> 
>  Documentation/ABI/README | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/ABI/README b/Documentation/ABI/README
> index ef0e6d11e919..315fffe1f831 100644
> --- a/Documentation/ABI/README
> +++ b/Documentation/ABI/README
> @@ -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.

>  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

-- 
~Randy

Re: [PATCH] docs: ABI: make the KernelVersion field optional

[Alison Schofield]

On Wed, Jun 25, 2025 at 07:52:58PM -0700, Randy Dunlap wrote:
> Hi,
> 
> On 6/25/25 7:40 PM, alison.schofield@intel.com wrote:
> > From: Alison Schofield <alison.schofield@intel.com>
> > 
> > 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.
> > 
> > Signed-off-by: Alison Schofield <alison.schofield@intel.com>
> > ---
> > 
> > Plan B is to remove the field entirely. 
> > 
> > 
> >  Documentation/ABI/README | 4 +++-
> >  1 file changed, 3 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/ABI/README b/Documentation/ABI/README
> > index ef0e6d11e919..315fffe1f831 100644
> > --- a/Documentation/ABI/README
> > +++ b/Documentation/ABI/README
> > @@ -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.

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

> 
> >  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
> 
> -- 
> ~Randy
> 

Re: [PATCH] docs: ABI: make the KernelVersion field optional

[Randy Dunlap]

On 6/25/25 8:32 PM, Alison Schofield wrote:
> On Wed, Jun 25, 2025 at 07:52:58PM -0700, Randy Dunlap wrote:
>> Hi,
>>
>> On 6/25/25 7:40 PM, alison.schofield@intel.com wrote:
>>> From: Alison Schofield <alison.schofield@intel.com>
>>>
>>> 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.
>>>
>>> Signed-off-by: Alison Schofield <alison.schofield@intel.com>
>>> ---
>>>
>>> Plan B is to remove the field entirely. 
>>>
>>>
>>>  Documentation/ABI/README | 4 +++-
>>>  1 file changed, 3 insertions(+), 1 deletion(-)
>>>
>>> diff --git a/Documentation/ABI/README b/Documentation/ABI/README
>>> index ef0e6d11e919..315fffe1f831 100644
>>> --- a/Documentation/ABI/README
>>> +++ b/Documentation/ABI/README
>>> @@ -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.
> 
> 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. 

I see. Please continue with your patch then.

Thanks.

-- 
~Randy

Re: [PATCH] docs: ABI: make the KernelVersion field optional

[dan.j.williams]

alison.schofield@ wrote:
> From: Alison Schofield <alison.schofield@intel.com>
> 
> 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.
> 
> Signed-off-by: Alison Schofield <alison.schofield@intel.com>

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

Acked-by: Dan Williams <dan.j.williams@intel.com>

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.

> ---
> 
> 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.

Re: [PATCH] docs: ABI: make the KernelVersion field optional

[Jonathan Corbet]

alison.schofield@intel.com writes:

> From: Alison Schofield <alison.schofield@intel.com>
>
> 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.
>
> Signed-off-by: Alison Schofield <alison.schofield@intel.com>
> ---
>
> Plan B is to remove the field entirely. 
>
>
>  Documentation/ABI/README | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/ABI/README b/Documentation/ABI/README
> index ef0e6d11e919..315fffe1f831 100644
> --- a/Documentation/ABI/README
> +++ b/Documentation/ABI/README
> @@ -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