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

[Alison Schofield <alison.schofield@intel.com>]

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
>