Re: [PATCH v3 1/2] ref-manual: release-process: update releases.svg

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

Hi Quentin,

On Mon Oct 28, 2024 at 3:33 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 10/28/24 2:53 PM, Antonin Godard wrote:
>> Hi Quentin,
>>
>> On Mon Oct 28, 2024 at 11:40 AM CET, Quentin Schulz wrote:
>>> Hi Antonin,
>>>
>>> On 10/23/24 9:32 AM, Antonin Godard wrote:
>>>> * Add Walnascar release.
>>>> * Remove dunfell, gatesgarth, hardknott, honister: these release are not
>>>>     supported anymore. Start from kirkstone, which is still supported.
>>>>
>>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>>>> ---
>>>>    documentation/ref-manual/svg/releases.svg | 907 ++++++++++++------------------
>>>>    1 file changed, 346 insertions(+), 561 deletions(-)
>>>>
>>>> diff --git a/documentation/ref-manual/svg/releases.svg b/documentation/ref-manual/svg/releases.svg
>>>> index 036aa467cc2e646e99bc407bbf0ea7ff8825f57b..b1036e066ceb65a7391cec616cb4304094728f3f 100644
>>>> --- a/documentation/ref-manual/svg/releases.svg
>>>> +++ b/documentation/ref-manual/svg/releases.svg
>>>> @@ -2,11 +2,14 @@
>>> [...]
>>>> +    <text
>>>> +       xml:space="preserve"
>>>> +       style="font-weight:bold;font-size:13.3333px;line-height:125%;font-family:'Nimbus Roman';-inkscape-font-specification:'Nimbus Roman, Bold';letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;fill:#fffefe;fill-opacity:1;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
>>>> +       x="1659.087"
>>>> +       y="-3.6722763"
>>>> +       id="text1185-3-55-4-0-0-0-1-1-6-4-3-5-2-2"><tspan
>>>> +         sodipodi:role="line"
>>>> +         x="1659.087"
>>>> +         y="-3.6722763"
>>>> +         style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:13.3333px;font-family:'Liberation Sans';-inkscape-font-specification:'Liberation Sans';text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none"
>>>> +         id="tspan10317-2-9-1-4-6-5-6-6-5-9-7">Current</tspan></text>
>>>
>>> This is a bit dangerous as "current" keeps its meaning while time
>>> passes. So building docs from years ago from a tarball will still say
>>> "current" event though it isn't really supported anymore. The X axis
>>> showing the dates should be enough for people to get the idea, but maybe
>>> we can also add the last update date of the SVG after Current? e.g.
>>> "Current (Oct. 2024)"?
>>
>> I agree on adding the date after current would timestamp the image and make it
>> valid for a given date. I like the idea of putting the current releases as the
>> most prominent color, so I guess we can keep "Current" but add the timestamp?
>>
>
> That's an option, yes.
>
>>> Additionally updating that SVG for all releases might be an issue. If we
>>> backport it "too far" then the release of the docs will not even be in
>>> that graph anymore, which is a bit odd. Moreover, the paragraph in the
>>> LTS section may become outdated as well.
>>
>> I would have thought that EoL releases would receive a last update that puts the
>> color of that release to the faded color, and then receive no updates to the
>> diagram anymore.
>>
>
> You would still have more recent releases in the graph, even though at
> some point those also wouldn't be supported anymore.
>
>> Is it that bad that reading the doc for an old release shows a outdated
>> "Current" state? Granted that they also show the timestamp mentioned above.
>>
>
> I am of the opinion of yes. Imagine a user getting Yocto from a vendor
> and the SVG that shows Current shows their release in there, which could
> have been EoL for a while already. It's not uncommon to have questions
> from people "stuck" on a very old release because of BSP layers from
> vendors which do not care about updating.
>
>>> A random thought I just had was to maybe treat this the same way we do
>>> with the migration manuals, that is to take the source from the last
>>> release/master and inject it into all earlier releases whenever we build
>>> the docs through the autobuilder. We could still have an outdated
>>> version if people build it from an old tarball but there's no much we
>>> can do about that sadly.
>>>
>>> What do you think?
>>
>> I guess that's the ideal solution, and it shouldn't be too hard to add too!
>> (especially if code already exists for the migration manuals)
>>
>
> It'll be a bit odd though because people looking at an old release and
> the release won't appear in the graph.

While adding it dynamically to the svg may be too hard (or is it? it is a text
file after all), we can still refer to the current release using the
`&DISTRO_NAME` syntax, maybe in a sentence above the graph.

> There's no perfect solution that comes to mind right now though. Sooo,
> best effort for now and trying to not confuse people is a good
> compromise I think :)

So perhaps:

- Add a date stamp after "Current".
- Automate the deployment of the svg file, like what's done for the migration
  manuals.
- Mention the documentation's release above the graph with &DISTRO_NAME.

Is the best we can do?

> Cheers,
> Quentin

Cheers,
Antonin

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