Skip to contentSkip to conversation

3.0 release notes / migration guide

DISCUSSION Paul Eggleton 2 participants 4 messages Oct 2, 2019

lore
Share & tools
lore
#0 lore raw

Hi folks

So it's that time again - we need to start building up the raw material for the release notes and migration guide for the upcoming 3.0 release, and I'd like to request some help with some parts of it - read on for details.

For the migration guide we have a wiki page serving as a staging area:

https://wiki.yoctoproject.org/wiki/FutureMigrationGuide

Things that should go in the migration guide: *anything* in the release that would require someone who is upgrading to take some form of action (i.e. change their configuration / recipes / etc.) Help with this from people who implemented the changes or have already thought about / dealt with their impact would be much appreciated.

There is a process where I look through all the commits since the last release and pull out the ones that need to be mentioned in some form - other than the migration guide items, the following needs to be gathered for the release notes:

1) Features - new functionality. We need to capture what the feature is and hopefully express the impact to the user succinctly.

2) Recipe upgrades - straightforward

3) CVE fixes - fairly straightforward, I just look for commits that explicitly mention "CVE". If I can easily do so I'll also note where a recipe upgrade fixes a CVE, but that isn't often readily available information.

4) Known issues - generally this is difficult to get from the commits since we either find out about them after the commit that introduced the issue, or we don't know that they aren't addressed until right at the end of the release. We don't want to note *all* open bugs, but if there's something that the user is likely to hit that wasn't an issue in the previous release then we should note it.

For the release notes I need help with #4 and #1 in particular, so if you know about anything in this release that falls into these categories then let me know - just a pointer to the commit and any extra comments that you would want to make would be helpful. In the mean time I will start the process of looking through the commits and will add things to the migration guide page, but bear in mind I don't always have all of the context for every change.

Thanks!
Paul

Signature · 2 lines
Paul Eggleton
Intel Open Source Technology Centre
#1 lore raw

Paul,

Quoted 9 lines · Paul Eggleton

Hi folks

So it's that time again - we need to start building up the raw material for the release notes and migration guide for the upcoming 3.0 release, and I'd like to request some help with some parts of it - read on for details.

For the migration guide we have a wiki page serving as a staging area:

https://wiki.yoctoproject.org/wiki/FutureMigrationGuide

Thanks for putting this together.

Quoted 7 lines

Things that should go in the migration guide: *anything* in the release that would require someone who is upgrading to take some form of action (i.e. change their configuration / recipes / etc.) Help with this from people who implemented the changes or have already thought about / dealt with their impact would be much appreciated.

Quoted 7 lines

There is a process where I look through all the commits since the last release and pull out the ones that need to be mentioned in some form - other than the migration guide items, the following needs to be gathered for the release notes:

1) Features - new functionality. We need to capture what the feature is and hopefully express the impact to the user succinctly.

We remove LSB support.

Quoted 5 lines

2) Recipe upgrades - straightforward

3) CVE fixes - fairly straightforward, I just look for commits that explicitly mention "CVE". If I can easily do so I'll also note where a recipe upgrade fixes a CVE, but that isn't often readily available information.

So how can the community help in this case? Better commit messages?

Quoted 7 lines

4) Known issues - generally this is difficult to get from the commits since we either find out about them after the commit that introduced the issue, or we don't know that they aren't addressed until right at the end of the release. We don't want to note *all* open bugs, but if there's something that the user is likely to hit that wasn't an issue in the previous release then we should note it.

Well, aren't open defects not fixed by the time we release time but we intend on fixing after release a form of known issues ?

- armin

Quoted 10 lines

For the release notes I need help with #4 and #1 in particular, so if you know about anything in this release that falls into these categories then let me know - just a pointer to the commit and any extra comments that you would want to make would be helpful. In the mean time I will start the process of looking through the commits and will add things to the migration guide page, but bear in mind I don't always have all of the context for every change.

Thanks!
Paul

#2 lore raw
Quoted 10 lines · On Thursday, 3 October 2019 11:44:53 AM NZDT akuster808 wrote:
Quoted 7 lines · Paul Eggleton

So it's that time again - we need to start building up the raw material for the release notes and migration guide for the upcoming 3.0 release, and I'd like to request some help with some parts of it - read on for details.

For the migration guide we have a wiki page serving as a staging area:

https://wiki.yoctoproject.org/wiki/FutureMigrationGuide

Thanks for putting this together.

No problem!

Quoted 11 lines
Quoted 11 lines

Things that should go in the migration guide: *anything* in the release that would require someone who is upgrading to take some form of action (i.e. change their configuration / recipes / etc.) Help with this from people who implemented the changes or have already thought about / dealt with their impact would be much appreciated.

There is a process where I look through all the commits since the last release and pull out the ones that need to be mentioned in some form - other than the migration guide items, the following needs to be gathered for the release notes:

Quoted 4 lines
Quoted 2 lines

1) Features - new functionality. We need to capture what the feature is and hopefully express the impact to the user succinctly.

We remove LSB support.

Thanks - I've just added that to the migration guide and will note it in the release notes.

Quoted 7 lines
Quoted 5 lines

2) Recipe upgrades - straightforward

3) CVE fixes - fairly straightforward, I just look for commits that explicitly mention "CVE". If I can easily do so I'll also note where a recipe upgrade fixes a CVE, but that isn't often readily available information.

So how can the community help in this case? Better commit messages?

That would be great - but it does require the person doing the upgrade to look upstream, and of course every upstream is different. Unfortunately with some upstreams finding fixed CVE information is quite difficult indeed.

Quoted 2 lines

Well, aren't open defects not fixed by the time we release time but we intend on fixing after release a form of known issues ?

Yes, that's true - I will say we haven't been particularly systematic about the known issues in past releases so perhaps we should drive the list from bugzilla. I would want the list to be kept as short as possible though and each item should succinctly describe the issue.

Cheers
Paul

Signature · 2 lines
Paul Eggleton
Intel Open Source Technology Centre
#3 lore raw
Quoted 38 lines · Paul Eggleton
Quoted 9 lines · On Thursday, 3 October 2019 11:44:53 AM NZDT akuster808 wrote:
Quoted 7 lines · Paul Eggleton

So it's that time again - we need to start building up the raw material for the release notes and migration guide for the upcoming 3.0 release, and I'd like to request some help with some parts of it - read on for details.

For the migration guide we have a wiki page serving as a staging area:

https://wiki.yoctoproject.org/wiki/FutureMigrationGuide

Thanks for putting this together.

No problem!

Quoted 6 lines
Quoted 6 lines

Things that should go in the migration guide: *anything* in the release that would require someone who is upgrading to take some form of action (i.e. change their configuration / recipes / etc.) Help with this from people who implemented the changes or have already thought about / dealt with their impact would be much appreciated.

Quoted 8 lines
Quoted 7 lines

There is a process where I look through all the commits since the last release and pull out the ones that need to be mentioned in some form - other than the migration guide items, the following needs to be gathered for the release notes:

1) Features - new functionality. We need to capture what the feature is and hopefully express the impact to the user succinctly.

We remove LSB support.

Thanks - I've just added that to the migration guide and will note it in the release notes.

Quoted 6 lines
Quoted 5 lines

2) Recipe upgrades - straightforward

3) CVE fixes - fairly straightforward, I just look for commits that explicitly mention "CVE". If I can easily do so I'll also note where a recipe upgrade fixes a CVE, but that isn't often readily available information.

So how can the community help in this case? Better commit messages?

That would be great - but it does require the person doing the upgrade to look upstream, and of course every upstream is different. Unfortunately with some upstreams finding fixed CVE information is quite difficult indeed.

Quoted 6 lines
Quoted 2 lines

Well, aren't open defects not fixed by the time we release time but we intend on fixing after release a form of known issues ?

Yes, that's true - I will say we haven't been particularly systematic about the known issues in past releases so perhaps we should drive the list from bugzilla. I would want the list to be kept as short as possible though and each item should succinctly describe the issue.

Maybe something the Yocto Bug triage team could possible assist in.   I will bring it up tomorrow morning.

- armin

Quoted 3 lines

Cheers
Paul