Quick sync: what goes in migration guide vs release notes?

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Quick sync: what goes in migration guide vs release notes?

Sean Owen-2
A few different takes surfaced:


No significant disagreements, just might be worth clarifying a consensus policy.

"I feel this is a tiny thing that we should put into the migration guide, not release notes? ... it depends on the definition of migration guide and release notes: If I upgrade to 3.0 and hit compiler error, which one should I read?"

"I think it's the other way around: some things are worth noting, but there is no meaningful migration to guide. So they go in release notes, not a migration guide, if anything. Do we have a different understanding?"

"Migration guide: legitimate improvements yet that are breaking. If that's too trivial or minor, I wouldn't document. It depends on a committer's call.
Release note: significant breaking changes including the bug fixes and/or improvement. One JIRA could appear in both migration guide and release notes if it's worthwhile."
Reply | Threaded
Open this post in threaded view
|

Re: Quick sync: what goes in migration guide vs release notes?

cloud0fan
My 2 cents:

Since we have a migration guide, I think people who hit problems when upgrading Spark will read it. We should mention all the breaking changes there, except for trivial ones like obvious bug fixes. Even if there is no meaningful migration to guide for things like removing a deprecated API, it's still useful to have an item in the migration guide, to explain why we remove it.

Release notes, on the other hand, should include all the major things, like new features, improvements, new APIs, bug fixes, breaking changes, etc., as long as they are major. For example, dropping Scala 2.11 is a major breaking change and should be put in the release notes. That said, we may have some items in both the migration guide and the release notes.

Release notes can be read by many people and I think it's better to not make it too verbose.



On Tue, Jun 9, 2020 at 10:33 PM Sean Owen <[hidden email]> wrote:
A few different takes surfaced:


No significant disagreements, just might be worth clarifying a consensus policy.

"I feel this is a tiny thing that we should put into the migration guide, not release notes? ... it depends on the definition of migration guide and release notes: If I upgrade to 3.0 and hit compiler error, which one should I read?"

"I think it's the other way around: some things are worth noting, but there is no meaningful migration to guide. So they go in release notes, not a migration guide, if anything. Do we have a different understanding?"

"Migration guide: legitimate improvements yet that are breaking. If that's too trivial or minor, I wouldn't document. It depends on a committer's call.
Release note: significant breaking changes including the bug fixes and/or improvement. One JIRA could appear in both migration guide and release notes if it's worthwhile."
Reply | Threaded
Open this post in threaded view
|

Re: Quick sync: what goes in migration guide vs release notes?

Sean Owen-2
This seems like a change to current practice, as breaking changes are marked for release notes with release-notes, etc: https://spark.apache.org/contributing.html
My only concrete concern, is this seems to imply (?) that many JIRAs with release-notes and Docs text are not going to get included in release notes. They aren't anywhere then (3.0 is done, so not the migration guide). Some are important.
Change could be OK but how about proposing this going forward?


On Wed, Jun 10, 2020 at 10:35 AM Wenchen Fan <[hidden email]> wrote:
My 2 cents:

Since we have a migration guide, I think people who hit problems when upgrading Spark will read it. We should mention all the breaking changes there, except for trivial ones like obvious bug fixes. Even if there is no meaningful migration to guide for things like removing a deprecated API, it's still useful to have an item in the migration guide, to explain why we remove it.

Release notes, on the other hand, should include all the major things, like new features, improvements, new APIs, bug fixes, breaking changes, etc., as long as they are major. For example, dropping Scala 2.11 is a major breaking change and should be put in the release notes. That said, we may have some items in both the migration guide and the release notes.

Release notes can be read by many people and I think it's better to not make it too verbose.



On Tue, Jun 9, 2020 at 10:33 PM Sean Owen <[hidden email]> wrote:
A few different takes surfaced:


No significant disagreements, just might be worth clarifying a consensus policy.

"I feel this is a tiny thing that we should put into the migration guide, not release notes? ... it depends on the definition of migration guide and release notes: If I upgrade to 3.0 and hit compiler error, which one should I read?"

"I think it's the other way around: some things are worth noting, but there is no meaningful migration to guide. So they go in release notes, not a migration guide, if anything. Do we have a different understanding?"

"Migration guide: legitimate improvements yet that are breaking. If that's too trivial or minor, I wouldn't document. It depends on a committer's call.
Release note: significant breaking changes including the bug fixes and/or improvement. One JIRA could appear in both migration guide and release notes if it's worthwhile."
Reply | Threaded
Open this post in threaded view
|

Re: Quick sync: what goes in migration guide vs release notes?

Hyukjin Kwon
I think the proposal doesn't mean to don't add the JIRAs with release-notes into the release notes (?).
People will still label the JIRAs when the change is significant or breaking whether it's a bug or not, and they will be in the release notes.
I guess the proposal TL;DR is:
  - If that's a legitimate breaking improvement, it goes to migration guides.
  - If the change is significant or breaking whether it's a bug or not, we label JIRA with release-notes, and add it into the release note.



But yeah since we're here, I guess it's better to articulate and document them.



2020년 6월 11일 (목) 오전 12:39, Sean Owen <[hidden email]>님이 작성:
This seems like a change to current practice, as breaking changes are marked for release notes with release-notes, etc: https://spark.apache.org/contributing.html
My only concrete concern, is this seems to imply (?) that many JIRAs with release-notes and Docs text are not going to get included in release notes. They aren't anywhere then (3.0 is done, so not the migration guide). Some are important.
Change could be OK but how about proposing this going forward?


On Wed, Jun 10, 2020 at 10:35 AM Wenchen Fan <[hidden email]> wrote:
My 2 cents:

Since we have a migration guide, I think people who hit problems when upgrading Spark will read it. We should mention all the breaking changes there, except for trivial ones like obvious bug fixes. Even if there is no meaningful migration to guide for things like removing a deprecated API, it's still useful to have an item in the migration guide, to explain why we remove it.

Release notes, on the other hand, should include all the major things, like new features, improvements, new APIs, bug fixes, breaking changes, etc., as long as they are major. For example, dropping Scala 2.11 is a major breaking change and should be put in the release notes. That said, we may have some items in both the migration guide and the release notes.

Release notes can be read by many people and I think it's better to not make it too verbose.



On Tue, Jun 9, 2020 at 10:33 PM Sean Owen <[hidden email]> wrote:
A few different takes surfaced:


No significant disagreements, just might be worth clarifying a consensus policy.

"I feel this is a tiny thing that we should put into the migration guide, not release notes? ... it depends on the definition of migration guide and release notes: If I upgrade to 3.0 and hit compiler error, which one should I read?"

"I think it's the other way around: some things are worth noting, but there is no meaningful migration to guide. So they go in release notes, not a migration guide, if anything. Do we have a different understanding?"

"Migration guide: legitimate improvements yet that are breaking. If that's too trivial or minor, I wouldn't document. It depends on a committer's call.
Release note: significant breaking changes including the bug fixes and/or improvement. One JIRA could appear in both migration guide and release notes if it's worthwhile."
Reply | Threaded
Open this post in threaded view
|

Re: Quick sync: what goes in migration guide vs release notes?

cloud0fan
Yea we can't update the 3.0.0 migration guide now, but AFAIK we do mention most of the breaking changes there, except for the ML module. I think we can still put all the ML breaking changes in the release notes this time. But in the future, shall we put breaking changes in the migration guide? It also saves the release manager's time to write the release notes.

On Thu, Jun 11, 2020 at 9:53 AM Hyukjin Kwon <[hidden email]> wrote:
I think the proposal doesn't mean to don't add the JIRAs with release-notes into the release notes (?).
People will still label the JIRAs when the change is significant or breaking whether it's a bug or not, and they will be in the release notes.
I guess the proposal TL;DR is:
  - If that's a legitimate breaking improvement, it goes to migration guides.
  - If the change is significant or breaking whether it's a bug or not, we label JIRA with release-notes, and add it into the release note.



But yeah since we're here, I guess it's better to articulate and document them.



2020년 6월 11일 (목) 오전 12:39, Sean Owen <[hidden email]>님이 작성:
This seems like a change to current practice, as breaking changes are marked for release notes with release-notes, etc: https://spark.apache.org/contributing.html
My only concrete concern, is this seems to imply (?) that many JIRAs with release-notes and Docs text are not going to get included in release notes. They aren't anywhere then (3.0 is done, so not the migration guide). Some are important.
Change could be OK but how about proposing this going forward?


On Wed, Jun 10, 2020 at 10:35 AM Wenchen Fan <[hidden email]> wrote:
My 2 cents:

Since we have a migration guide, I think people who hit problems when upgrading Spark will read it. We should mention all the breaking changes there, except for trivial ones like obvious bug fixes. Even if there is no meaningful migration to guide for things like removing a deprecated API, it's still useful to have an item in the migration guide, to explain why we remove it.

Release notes, on the other hand, should include all the major things, like new features, improvements, new APIs, bug fixes, breaking changes, etc., as long as they are major. For example, dropping Scala 2.11 is a major breaking change and should be put in the release notes. That said, we may have some items in both the migration guide and the release notes.

Release notes can be read by many people and I think it's better to not make it too verbose.



On Tue, Jun 9, 2020 at 10:33 PM Sean Owen <[hidden email]> wrote:
A few different takes surfaced:


No significant disagreements, just might be worth clarifying a consensus policy.

"I feel this is a tiny thing that we should put into the migration guide, not release notes? ... it depends on the definition of migration guide and release notes: If I upgrade to 3.0 and hit compiler error, which one should I read?"

"I think it's the other way around: some things are worth noting, but there is no meaningful migration to guide. So they go in release notes, not a migration guide, if anything. Do we have a different understanding?"

"Migration guide: legitimate improvements yet that are breaking. If that's too trivial or minor, I wouldn't document. It depends on a committer's call.
Release note: significant breaking changes including the bug fixes and/or improvement. One JIRA could appear in both migration guide and release notes if it's worthwhile."
Reply | Threaded
Open this post in threaded view
|

Re: Quick sync: what goes in migration guide vs release notes?

Sean Owen-2
If you are proposing to keep all important changes in release notes as usual:
Sure, add more to the migration guide, too. It can't hurt, going forward. But many release-note changes have not much more to say about migration.

If you're proposing to not mention most things in the release notes, which is a change:
OK, are the migration guides the new release notes? propose a change to the process I guess?

But, what does this accomplish? Shorter release notes = longer migration guide. Is that saving time?
Why is compiling the release notes a big deal, assuming the JIRAs have "Docs text" snippets to compile? OK, I'll buy the idea that it's better to compile them along the way rather than make the RM pull them from JIRA.

If the goal is a TL;DR summary of major changes, neither of these accomplishes that. That's valuable, but is what a summary blog is for.

I can't feel strongly about this, so, would just say, propose process changes for 3.1 and codify in the contributing guide but stick with what we have for 3.0.


On Wed, Jun 10, 2020 at 10:04 PM Wenchen Fan <[hidden email]> wrote:
Yea we can't update the 3.0.0 migration guide now, but AFAIK we do mention most of the breaking changes there, except for the ML module. I think we can still put all the ML breaking changes in the release notes this time. But in the future, shall we put breaking changes in the migration guide? It also saves the release manager's time to write the release notes.

On Thu, Jun 11, 2020 at 9:53 AM Hyukjin Kwon <[hidden email]> wrote:
I think the proposal doesn't mean to don't add the JIRAs with release-notes into the release notes (?).
People will still label the JIRAs when the change is significant or breaking whether it's a bug or not, and they will be in the release notes.
I guess the proposal TL;DR is:
  - If that's a legitimate breaking improvement, it goes to migration guides.
  - If the change is significant or breaking whether it's a bug or not, we label JIRA with release-notes, and add it into the release note.



But yeah since we're here, I guess it's better to articulate and document them.



2020년 6월 11일 (목) 오전 12:39, Sean Owen <[hidden email]>님이 작성:
This seems like a change to current practice, as breaking changes are marked for release notes with release-notes, etc: https://spark.apache.org/contributing.html
My only concrete concern, is this seems to imply (?) that many JIRAs with release-notes and Docs text are not going to get included in release notes. They aren't anywhere then (3.0 is done, so not the migration guide). Some are important.
Change could be OK but how about proposing this going forward?


On Wed, Jun 10, 2020 at 10:35 AM Wenchen Fan <[hidden email]> wrote:
My 2 cents:

Since we have a migration guide, I think people who hit problems when upgrading Spark will read it. We should mention all the breaking changes there, except for trivial ones like obvious bug fixes. Even if there is no meaningful migration to guide for things like removing a deprecated API, it's still useful to have an item in the migration guide, to explain why we remove it.

Release notes, on the other hand, should include all the major things, like new features, improvements, new APIs, bug fixes, breaking changes, etc., as long as they are major. For example, dropping Scala 2.11 is a major breaking change and should be put in the release notes. That said, we may have some items in both the migration guide and the release notes.

Release notes can be read by many people and I think it's better to not make it too verbose.



On Tue, Jun 9, 2020 at 10:33 PM Sean Owen <[hidden email]> wrote:
A few different takes surfaced:


No significant disagreements, just might be worth clarifying a consensus policy.

"I feel this is a tiny thing that we should put into the migration guide, not release notes? ... it depends on the definition of migration guide and release notes: If I upgrade to 3.0 and hit compiler error, which one should I read?"

"I think it's the other way around: some things are worth noting, but there is no meaningful migration to guide. So they go in release notes, not a migration guide, if anything. Do we have a different understanding?"

"Migration guide: legitimate improvements yet that are breaking. If that's too trivial or minor, I wouldn't document. It depends on a committer's call.
Release note: significant breaking changes including the bug fixes and/or improvement. One JIRA could appear in both migration guide and release notes if it's worthwhile."
Reply | Threaded
Open this post in threaded view
|

Re: Quick sync: what goes in migration guide vs release notes?

cloud0fan
How about we treat the migration guide as a part of the release notes? e.g. in the "breaking changes" section, just point to the migration guide.

Thus, we don't change what to put in the release notes, but just move the breaking changes to a sub-doc.

On Thu, Jun 11, 2020 at 11:13 AM Sean Owen <[hidden email]> wrote:
If you are proposing to keep all important changes in release notes as usual:
Sure, add more to the migration guide, too. It can't hurt, going forward. But many release-note changes have not much more to say about migration.

If you're proposing to not mention most things in the release notes, which is a change:
OK, are the migration guides the new release notes? propose a change to the process I guess?

But, what does this accomplish? Shorter release notes = longer migration guide. Is that saving time?
Why is compiling the release notes a big deal, assuming the JIRAs have "Docs text" snippets to compile? OK, I'll buy the idea that it's better to compile them along the way rather than make the RM pull them from JIRA.

If the goal is a TL;DR summary of major changes, neither of these accomplishes that. That's valuable, but is what a summary blog is for.

I can't feel strongly about this, so, would just say, propose process changes for 3.1 and codify in the contributing guide but stick with what we have for 3.0.


On Wed, Jun 10, 2020 at 10:04 PM Wenchen Fan <[hidden email]> wrote:
Yea we can't update the 3.0.0 migration guide now, but AFAIK we do mention most of the breaking changes there, except for the ML module. I think we can still put all the ML breaking changes in the release notes this time. But in the future, shall we put breaking changes in the migration guide? It also saves the release manager's time to write the release notes.

On Thu, Jun 11, 2020 at 9:53 AM Hyukjin Kwon <[hidden email]> wrote:
I think the proposal doesn't mean to don't add the JIRAs with release-notes into the release notes (?).
People will still label the JIRAs when the change is significant or breaking whether it's a bug or not, and they will be in the release notes.
I guess the proposal TL;DR is:
  - If that's a legitimate breaking improvement, it goes to migration guides.
  - If the change is significant or breaking whether it's a bug or not, we label JIRA with release-notes, and add it into the release note.



But yeah since we're here, I guess it's better to articulate and document them.



2020년 6월 11일 (목) 오전 12:39, Sean Owen <[hidden email]>님이 작성:
This seems like a change to current practice, as breaking changes are marked for release notes with release-notes, etc: https://spark.apache.org/contributing.html
My only concrete concern, is this seems to imply (?) that many JIRAs with release-notes and Docs text are not going to get included in release notes. They aren't anywhere then (3.0 is done, so not the migration guide). Some are important.
Change could be OK but how about proposing this going forward?


On Wed, Jun 10, 2020 at 10:35 AM Wenchen Fan <[hidden email]> wrote:
My 2 cents:

Since we have a migration guide, I think people who hit problems when upgrading Spark will read it. We should mention all the breaking changes there, except for trivial ones like obvious bug fixes. Even if there is no meaningful migration to guide for things like removing a deprecated API, it's still useful to have an item in the migration guide, to explain why we remove it.

Release notes, on the other hand, should include all the major things, like new features, improvements, new APIs, bug fixes, breaking changes, etc., as long as they are major. For example, dropping Scala 2.11 is a major breaking change and should be put in the release notes. That said, we may have some items in both the migration guide and the release notes.

Release notes can be read by many people and I think it's better to not make it too verbose.



On Tue, Jun 9, 2020 at 10:33 PM Sean Owen <[hidden email]> wrote:
A few different takes surfaced:


No significant disagreements, just might be worth clarifying a consensus policy.

"I feel this is a tiny thing that we should put into the migration guide, not release notes? ... it depends on the definition of migration guide and release notes: If I upgrade to 3.0 and hit compiler error, which one should I read?"

"I think it's the other way around: some things are worth noting, but there is no meaningful migration to guide. So they go in release notes, not a migration guide, if anything. Do we have a different understanding?"

"Migration guide: legitimate improvements yet that are breaking. If that's too trivial or minor, I wouldn't document. It depends on a committer's call.
Release note: significant breaking changes including the bug fixes and/or improvement. One JIRA could appear in both migration guide and release notes if it's worthwhile."