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

[Paul Eggleton <bluelightning@bluelightning.org>]

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