You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flink.apache.org by Dawid Wysakowicz <dw...@apache.org> on 2021/09/13 07:51:18 UTC
[DISCUSS] Purpose of release notes
Hi devs,
When working on the release notes for the upcoming 1.14.0[1] release I
spotted inconsistencies in where we add release-notes. Therefore I
wanted to ask how do we see the purpose of this page. So far the first
paragraph states:
These release notes discuss important aspects, such as
configuration, behavior, or dependencies, that changed between
Flink 1.x and Flink 1.y. Please read these notes carefully if you
are planning to upgrade your Flink version to 1.y.
Which would mean we should not put pure announcements for new feature
there (we can still do that in the announcement blogpost, imo). However,
we do that from time to time (not to point fingers, just some examples):
FLINK-20731(pulsar source), FLINK-21924 (fine grained reasource
management), FLINK-22670 (hybrid source) ...
Moreover, I think it is good to remind everyone that the target group
for this page is our user base. I think Stephan put it quite well when
reviewing the PR for 1.14.0 release-notes:
This is still too much written in a "here is what we did"
perspective, rather than from the perspective of "what does the user
need to know about this change".
Can I assume the introduction to the page is still correct and thus e.g.
remove the FLINK-20731 from there?
Best,
Dawid
[1] https://github.com/apache/flink/pull/17182
Re: [DISCUSS] Purpose of release notes
Posted by Yangze Guo <ka...@gmail.com>.
+1
Thanks Dawid for the clarification.
Best,
Yangze Guo
On Mon, Sep 13, 2021 at 4:18 PM Jark Wu <im...@gmail.com> wrote:
>
> +1
>
> I think the purpose of the release note page has not changed over the
> previous releases.
> It's a guideline for users to upgrade flink which just contains API-like
> changes.
> All notable features should be included in the announcement blog which is
> more visible to users.
>
> Best,
> Jark
>
> On Mon, 13 Sept 2021 at 15:51, Dawid Wysakowicz <dw...@apache.org>
> wrote:
>
> > Hi devs,
> >
> > When working on the release notes for the upcoming 1.14.0[1] release I
> > spotted inconsistencies in where we add release-notes. Therefore I wanted
> > to ask how do we see the purpose of this page. So far the first paragraph
> > states:
> >
> > These release notes discuss important aspects, such as configuration,
> > behavior, or dependencies, that changed between
> > Flink 1.x and Flink 1.y. Please read these notes carefully if you are
> > planning to upgrade your Flink version to 1.y.
> >
> > Which would mean we should not put pure announcements for new feature
> > there (we can still do that in the announcement blogpost, imo). However, we
> > do that from time to time (not to point fingers, just some examples): FLINK-20731(pulsar
> > source), FLINK-21924 (fine grained reasource management), FLINK-22670
> > (hybrid source) ...
> >
> > Moreover, I think it is good to remind everyone that the target group for
> > this page is our user base. I think Stephan put it quite well when
> > reviewing the PR for 1.14.0 release-notes:
> >
> > This is still too much written in a "here is what we did" perspective,
> > rather than from the perspective of "what does the user need to know about
> > this change".
> >
> > Can I assume the introduction to the page is still correct and thus e.g.
> > remove the FLINK-20731 from there?
> >
> > Best,
> >
> > Dawid
> >
> > [1] https://github.com/apache/flink/pull/17182
> >
Re: [DISCUSS] Purpose of release notes
Posted by Jark Wu <im...@gmail.com>.
+1
I think the purpose of the release note page has not changed over the
previous releases.
It's a guideline for users to upgrade flink which just contains API-like
changes.
All notable features should be included in the announcement blog which is
more visible to users.
Best,
Jark
On Mon, 13 Sept 2021 at 15:51, Dawid Wysakowicz <dw...@apache.org>
wrote:
> Hi devs,
>
> When working on the release notes for the upcoming 1.14.0[1] release I
> spotted inconsistencies in where we add release-notes. Therefore I wanted
> to ask how do we see the purpose of this page. So far the first paragraph
> states:
>
> These release notes discuss important aspects, such as configuration,
> behavior, or dependencies, that changed between
> Flink 1.x and Flink 1.y. Please read these notes carefully if you are
> planning to upgrade your Flink version to 1.y.
>
> Which would mean we should not put pure announcements for new feature
> there (we can still do that in the announcement blogpost, imo). However, we
> do that from time to time (not to point fingers, just some examples): FLINK-20731(pulsar
> source), FLINK-21924 (fine grained reasource management), FLINK-22670
> (hybrid source) ...
>
> Moreover, I think it is good to remind everyone that the target group for
> this page is our user base. I think Stephan put it quite well when
> reviewing the PR for 1.14.0 release-notes:
>
> This is still too much written in a "here is what we did" perspective,
> rather than from the perspective of "what does the user need to know about
> this change".
>
> Can I assume the introduction to the page is still correct and thus e.g.
> remove the FLINK-20731 from there?
>
> Best,
>
> Dawid
>
> [1] https://github.com/apache/flink/pull/17182
>
Re: [DISCUSS] Purpose of release notes
Posted by Thomas Weise <th...@apache.org>.
Thanks for bringing this back to the list.
The inconsistencies are probably due to different expectations of what
"release notes" in general cover (beyond Flink). I appreciate to find a
feature list as part of the release notes, but that can also be
accomplished by linking to a more comprehensive resource from said top
paragraph (something like "see blog for more information").
Also +1 for user centric descriptions.
Thomas
On Mon, Sep 13, 2021 at 12:51 AM Dawid Wysakowicz <dw...@apache.org>
wrote:
> Hi devs,
>
> When working on the release notes for the upcoming 1.14.0[1] release I
> spotted inconsistencies in where we add release-notes. Therefore I wanted
> to ask how do we see the purpose of this page. So far the first paragraph
> states:
>
> These release notes discuss important aspects, such as configuration,
> behavior, or dependencies, that changed between
> Flink 1.x and Flink 1.y. Please read these notes carefully if you are
> planning to upgrade your Flink version to 1.y.
>
> Which would mean we should not put pure announcements for new feature
> there (we can still do that in the announcement blogpost, imo). However, we
> do that from time to time (not to point fingers, just some examples): FLINK-20731(pulsar
> source), FLINK-21924 (fine grained reasource management), FLINK-22670
> (hybrid source) ...
>
> Moreover, I think it is good to remind everyone that the target group for
> this page is our user base. I think Stephan put it quite well when
> reviewing the PR for 1.14.0 release-notes:
>
> This is still too much written in a "here is what we did" perspective,
> rather than from the perspective of "what does the user need to know about
> this change".
>
> Can I assume the introduction to the page is still correct and thus e.g.
> remove the FLINK-20731 from there?
>
> Best,
>
> Dawid
>
> [1] https://github.com/apache/flink/pull/17182
>