Re: [docs] [PATCH 1/2] poky.yaml: introduce DISTRO_LATEST_TAG

["Antonin Godard" <antonin.godard@bootlin.com>]

On Thu May 15, 2025 at 9:50 AM CEST, Quentin Schulz wrote:
> Hi Antonin,
>
> On 5/13/25 10:28 AM, Antonin Godard wrote:
>> On Wed Apr 23, 2025 at 11:56 AM CEST, Quentin Schulz wrote:
>>> Hi Antonin,
>>>
>>> On 4/23/25 11:33 AM, Antonin Godard wrote:
>>> [...]
>>>>> I don't think we should be using &DISTRO; anymore? Most of the time we
>>>>> don't want to be printing .999 on the landing page of
>>>>> docs.yoctoproject.org! For the dev page, that's different.
>>>>
>>>> I would like to agree, but at the same time, wouldn't it be confusing to have a
>>>> real tag (e.g. 5.1.8) when reading for the latest tip of the branch? It would be
>>>
>>> Does it matter? We should only be doing bug fixing and ideally without
>>> breaking backward compatibility in a given release branch.
>>> Again, the development (master) branch is a different story here.
>>>
>>>> somewhat accurate, but not _stricty_ accurate as to which version of the doc you
>>>> are actually reading (the latest tip).
>>>>
>>>
>>> The issue is that this tag simply doesn't exist so we should absolutely
>>> never use it when code is involved, as the instructions will simply not
>>> work.
>> 
>> Right, so the code parts of the docs should be adapted to use DISTRO_LATEST_TAG,
>> but I still think using DISTRO in the textual parts is useful to distinguish a
>> branch tip version of the docs and a tagged version of the docs.
>> 
>
> I don't see the benefit. But we can start by fixing the code blocks to 
> not use DISTRO and postpone the rest of the discussion for another time 
> :) Progress is still progress even if it's not perfect now.
>
>>>> I'm trying to think of a way to make it clear that 999 represent the branch's
>>>> tip.
>>>>
>>>
>>> I'm failing to see how it is relevant to the user that the docs are
>>> built from the branch's tip instead of the tag?
>> 
>> There might be a reason that goes beyond my work on the docs, but it is kind of
>> useful to me to monitor changes as we go, or just to provides up-to-date links
>> to people.
>> 
>> It is questionable that this should be the default landing page though.
>> 
>
> Ah, this I disagree with :) And I think this is the reason why we have 
> this in the first place.

I think we agree actually, I also think it is a good default for the reasons you
stated below. Maybe I wasn't very clear about that. :)

> There is a very simple reason for that. We never have (or at least had, 
> I don't know if this has changed) the docs ready for the release before 
> the release is tagged (including the docs). This means if we were to 
> always show the latest tag we would be missing information, even for the 
> tagged release (e.g. recipe version bumps, cves fixed, known issues, etc.)!
>
> Even more so, we want to avoid having to wait ~1+ month for the next 
> release if there are important fixes in the documentation (e.g. 
> misleading information). This we can only achieve by using the tip of 
> the branch and not the release. This also apply to outdated releases 
> which will never receive a new tag but we may still want to patch 
> documentation (e.g. links have gone bad, misleading info, etc.).
>
>>> BTW, it seems like once you're on a tagged release, you cannot go back
>>> to the .999 from the dropdown menu, is that intended?
>> 
>> Sounds like a bug to me!
>> 
>
> I vaguely remember discussing this years ago. I think the issue is how 
> to represent this in the menu? Should we really have
>
> scarthgap (5.0.9)
> scarthgap (dev)
>
> for each release?

I don't think it's necessary to do so for each release, but only for the current
stable release, as is done today. So I think the only real bug here is that we
don't see "Walnascar (5.2.999)" in the list as it should be.

I don't really like renaming from "Walnascar (5.2.999)" to "Walnascar (dev)" (if
that's what you implied). I would rather put "latest" instead.

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com