Received-SPF: pass (google.com: domain of linux-kernel+bounces-148787-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
Precedence: bulk
MIME-Version: 1.0
References: <20240329133458.323041-2-valla.francesco@gmail.com>
 <20240329133458.323041-3-valla.francesco@gmail.com> <CAMZ6RqKLaYb+8EaeoFMHofcaBT5G2-qdqSb4do73xrgMvWMZaA@mail.gmail.com>
 <9f5ad308-f2a0-47be-85f3-d152bc98099a@hartkopp.net> <CAMZ6RqKGKcYd4hAM8AVV72t78H-Kt92NXowx6Q+YCw=AuSxKuw@mail.gmail.com>
 <64586257-3cf6-4c10-a30b-200b1ecc5e80@hartkopp.net> <Zh6qiDwbEnaJtTvl@fedora> <d4a55991-0ccc-4e8f-8acb-56077600c9e0@hartkopp.net>
In-Reply-To: <d4a55991-0ccc-4e8f-8acb-56077600c9e0@hartkopp.net>
From: Vincent Mailhol <vincent.mailhol@gmail.com>
Date: Thu, 18 Apr 2024 00:21:40 +0900
Message-ID: <CAMZ6RqJUHJdq30CrAzT26_RqpDOH_iMP8A6SKSAYrWBe-T+Oww@mail.gmail.com>
Subject: Re: [PATCH v2 1/1] Documentation: networking: document ISO 15765-2:2016
To: Oliver Hartkopp <socketcan@hartkopp.net>
Cc: Francesco Valla <valla.francesco@gmail.com>, Marc Kleine-Budde <mkl@pengutronix.de>, 
	linux-can@vger.kernel.org, netdev@vger.kernel.org, 
	linux-kernel@vger.kernel.org, Simon Horman <horms@kernel.org>, 
	Bagas Sanjaya <bagasdotme@gmail.com>, fabio@redaril.me
Content-Type: text/plain; charset="UTF-8"

On Wed. 17 Apr. 2024 at 02:19, Oliver Hartkopp <socketcan@hartkopp.net> wrote:
> Hi Francesco and Vincent,
>
> On 16.04.24 18:42, Francesco Valla wrote:
> > On Sun, Apr 14, 2024 at 10:21:33PM +0200, Oliver Hartkopp wrote:
> >> On 14.04.24 06:03, Vincent Mailhol wrote:
>
> >>> Regardless, here is a verbatim extract from the Foreworld section of
> >>> ISO 15765-2:2024
> >>>
> >>>     This fourth edition cancels and replaces the third edition (ISO
> >>>     15765-2:2016), which has been technically revised.
> >>>
> >>>     The main changes are as follows:
> >>>
> >>>       - restructured the document to achieve compatibility with OSI
> >>>         7-layers model;
> >>>
> >>>       - introduced T_Data abstract service primitive interface to
> >>>         achieve compatibility with ISO 14229-2;
> >>>
> >>>       - moved all transport layer protocol-related information to Clause 9;
> >>>
> >>>       - clarification and editorial corrections
> >>>
> >>
> >> Yes, I've checked the release notes on the ISO website too.
> >> This really looks like editorial stuff that has nothing to do with the data
> >> protocol and its segmentation.
> >>
> >
> > The :2016 suffix is cited both here and inside the Kconfig. We can:
> > - keep the :2016 here and then update both the documentation and the
> >    Kconfig once the standard has been checked
> > - move to :2024 both here and inside the Kconfig
> > - drop the :2016 from everywhere (leaving only ISO 15765) and move to
> >    ISO 15765:2024 only inside the "Specifications used" paragraph
> >
> > What do you think? Shall the modifications to the Kconfig be done as part of
> > this series?

If we bump the version to :2024, then I suggest to:

  - add a first patch in this series to update Kconfig.
  - add your documentation as a second patch directly with the :2024 version.

Generally speaking, when a feature requires any kind of clean-up, I
think it is better to do that clean-up first, prior to introducing the
feature.

I am also supportive of your idea to drop the year suffix in most
places and only keep it once.

> So here is my completely new view on this version topic ... ;-D
>
> I would vote for ISO 15765-2:2016 in all places.
>
> The ISO 15765-2:2016 is the first ISO 15765-2 standard which supports
> CAN FD and ISO 15765-2:2024 does not bring any functional change neither
> to the standard nor to the implementation in the Linux kernel.
>
> For that reason ISO 15765-2:2016 is still correct and relevant (due to
> the CAN FD support) and does not confuse the users whether the 2024
> version has some completely new feature or is potentially incompatible
> to the 2016 version.

ISO publications are backward compatible (if you dig enough, you may
find exceptions, but it is *extremely* uncommon that a newer revision
would break the specification from a prior publication). Without prior
knowledge, if I see ISO 15765-2:2024, I would know that it is the
latest and that I can thus expect support for both ISO 15765-2:2016
and ISO 15765-2:2024. If I see ISO 15765-2:2016, I may think that the
newer ISO 15765-2:2024 is not supported.

I can also use ISO 11898-1 as an example. Our documentation says that
we support ISO 11898-1:2015. The previous version: ISO 11898-1:2003 is
not mentioned a single time in the full kernel tree. Yet, I do not
think that any one was ever confused that the kernel may not be
compatible with ISO 11898-1:2003.

If you really think that there is a risk of confusion, then maybe just
adding a sentence to say that we support ISO 15765-2:2024 and all
previous versions would be enough?

But overall, I do not see the benefit to keep the older version.

> Best regards,
> Oliver