Re: [docs] [PATCH] manuals: add 3.4 and 3.4.1 release notes after migration information

Re: [docs] [PATCH] manuals: add 3.4 and 3.4.1 release notes after migration information

[Michael Opdenacker]

On 1/19/22 8:09 PM, Michael Opdenacker wrote:
> Only done for release 3.4 and 3.4.1 so far.
> Release notes are kept under the migration-guides/ directory for
> the moment, for easier reviewing.
>
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>


See the resulting HTML on
https://bootlin.com/~mike/pub/yocto-project/docs-2021-01-19/migration-guides/migration-3.4.html

I really need your feedback on the way the notes are laid out. This is a
good time to review what we put in our release notes. Here are questions...

  * Are the repository links really important? Could we simplify them?
    Could we just have the Poky details and downloads?
  * Do we really want to have lists of commits? Wouldn't a link to the
    corresponding git tag be enough? If so, we may need to add links to
    them, but that's going to be very verbose in the source code.
  * Are these really notes clear enough and are the main points
    highlighted well enough?

Once we agree on the contents, I'll be able to migrate older release
notes and also update the scripts that generate the corresponding content.

Thanks in advance
Cheers
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] manuals: add 3.4 and 3.4.1 release notes after migration information

[Paul Eggleton]

Hi Michael

On Thursday, 20 January 2022 08:19:38 NZDT Michael Opdenacker wrote:
> On 1/19/22 8:09 PM, Michael Opdenacker wrote:
> > Only done for release 3.4 and 3.4.1 so far.
> > Release notes are kept under the migration-guides/ directory for
> > the moment, for easier reviewing.
> 
> See the resulting HTML on
> https://bootlin.com/~mike/pub/yocto-project/docs-2021-01-19/migration-guides
> /migration-3.4.html
> 
> I really need your feedback on the way the notes are laid out. This is a
> good time to review what we put in our release notes.

This is a great move. Formatting and links are definitely something I've
struggled without in the release notes and this solves that.
 
>   * Are the repository links really important? Could we simplify them?
>     Could we just have the Poky details and downloads?

I think we'd need more than that, but what is included and what isn't is
definitely debatable. I know we've asked in the past if the tarballs were
useful, I'd be really surprised if anyone needed them now.

>   * Do we really want to have lists of commits? Wouldn't a link to the
>     corresponding git tag be enough? 

This is what we do for minor releases. I think it might be useful to some, 
but you'd probably have to survey our users to really know whether they benefit 
from it. One easy alternative would be to just provide a cgit link e.g. for 
dunfell-23.0.13 :

  https://git.yoctoproject.org/poky/log/?qt=range&q=dunfell-23.0.12..dunfell-23.0.13

>     If so, we may need to add links to
>     them, but that's going to be very verbose in the source code.

If we do continue to do this ideally we would be auto-generating the content
(prior to check-in I mean), so at least it shouldn't be hard to manage.

>   * Are these really notes clear enough and are the main points
>     highlighted well enough?

So we could probably use formatting (e.g. bold) on some of the more key
points /sections of the release notes new feature list. Unfortunately our
project generally isn't that visual so there's not much chance of including
images in the list (unless we go to icons or similar).

One of my go-to examples for documentation that I think looks great is Django -
for their release notes they tend to break it up more into subsections e.g.
 https://docs.djangoproject.com/en/4.0/releases/4.0/
It would be nice to do that at least for major features so we can explain the
benefits of each one in a bit more detail. 

(Honestly though I don't think it's worth spending the effort prettying up
the release notes for older releases, it's more something we can think about
for upcoming ones.)

Cheers,
Paul

Re: [docs] [PATCH] manuals: add 3.4 and 3.4.1 release notes after migration information

[Michael Opdenacker]

Hi Paul,

Many thanks for your review and feeback!

On 1/25/22 23:18, Paul Eggleton wrote:
>  
>>   * Are the repository links really important? Could we simplify them?
>>     Could we just have the Poky details and downloads?
> I think we'd need more than that, but what is included and what isn't is
> definitely debatable. I know we've asked in the past if the tarballs were
> useful, I'd be really surprised if anyone needed them now.


Good to know. I'd propose to just keep the tarballs for Poky. I guess
they would be sufficient, right?

>
>>   * Do we really want to have lists of commits? Wouldn't a link to the
>>     corresponding git tag be enough? 
> This is what we do for minor releases. I think it might be useful to some, 
> but you'd probably have to survey our users to really know whether they benefit 
> from it. One easy alternative would be to just provide a cgit link e.g. for 
> dunfell-23.0.13 :
>
>   https://git.yoctoproject.org/poky/log/?qt=range&q=dunfell-23.0.12..dunfell-23.0.13


This sounds like a good idea, but we'd lose the specific list of fixed
vulnerabilities.

>
>>     If so, we may need to add links to
>>     them, but that's going to be very verbose in the source code.
> If we do continue to do this ideally we would be auto-generating the content
> (prior to check-in I mean), so at least it shouldn't be hard to manage.


Right, this will have to be done this way. Do you manually differentiate
the security fixes from the normal ones for the moment?

>
>>   * Are these really notes clear enough and are the main points
>>     highlighted well enough?
> So we could probably use formatting (e.g. bold) on some of the more key
> points /sections of the release notes new feature list. Unfortunately our
> project generally isn't that visual so there's not much chance of including
> images in the list (unless we go to icons or similar).
>
> One of my go-to examples for documentation that I think looks great is Django -
> for their release notes they tend to break it up more into subsections e.g.
>  https://docs.djangoproject.com/en/4.0/releases/4.0/
> It would be nice to do that at least for major features so we can explain the
> benefits of each one in a bit more detail. 

Well, we already have subsections on
https://bootlin.com/~mike/pub/yocto-project/docs-2021-01-19/migration-guides/migration-3.4.html#release-3-4-honister,
corresponding to the main changes we want to highlight. Isn't this what
you're suggesting?


>
> (Honestly though I don't think it's worth spending the effort prettying up
> the release notes for older releases, it's more something we can think about
> for upcoming ones.)


Indeed, tt make sense to start with Honister to know what format we
want, in order to be ready for Kirstone. However, how about the Dunfell
updates? Would they continue to be released through the old text release
notes?

Thanks again
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com