I'd like to bring up another problem that I see with the current FLIP
process, which relates to what happens after a FLIP has been implemented.
A few months ago I read through all of the then existing FLIPs. My reason
for doing so is that on a great many topics, the only "documentation" we
have is the FLIPs, and there were several parts of Flink that I wanted to
understand better.
But I put documentation in "quotes" above because there are significant
problems with trying to rely on the FLIPs to know what's going on:
(1) As has already been pointed out, in quite a few cases the status was
never updated.
(2) In some cases, what was ultimately implemented does not match the FLIP.
Often these discrepancies are pretty minor: for example, during the
implementation classes get renamed from what had been proposed, interfaces
get adjusted a bit, etc. And sometimes a FLIP is only partially
implemented.
(3) And I believe there are cases where past FLIPs have been made at least
partially obsolete by more recent development.
As a step toward making the FLIPs more useful, I would like to propose that
when the author(s) go back to update the status from Accepted to Released,
if they would add a section at the end outlining any ways in which the
implementation being released differs from what is described in the FLIP.
David
On Thu, Feb 20, 2020 at 1:05 PM Hequn Cheng <he...@apache.org> wrote:
> Hi everyone,
>
> I appreciate all the feedback! Let me try to explain more.
>
> As there are a lot of people show concerns about the google doc.
> Let’s make an assumption first that the comment on the google doc is not
> allowed!
> Let’s make an assumption first that the comment on the google doc is not
> allowed!!
> Let’s make an assumption first that the comment on the google doc is not
> allowed!!!
> (As for whether to allow (minor)comments on the google doc. I will raise
> another discussion if we reach a consensus on this one.)
>
> The main purpose of this discussion is to improve the current FLIP process.
> Before we introduce the improvements, let’s first take a look at the
> problems we have. This is the motivation why this discussion is raised. The
> problems I find are listed as follows:
> 1. During the FLIP discussion, whenever there is a change, we need to pick
> the change to the wiki page. This is somehow redundant.
> 2. Even after the proposal has been finalized, the wiki page can be changed
> as it is editable to everyone. However, any change to an adopted FLIP
> requires a new voting process.
> 3. The FLIP page is not well maintained, e.g., the status of many FLIPs
> were not updated in time. You can find there are a lot of FLIPs with the
> target release of 1.10 on the current wiki page.
>
> Next, let’s see how the problems listed above can be solved by the new
> process. I will list the new process again for discussion convenience.
>
> 1. Raise the discussion on the mailing list. The subject of the thread is
> of the format [DISCUSS][FLIP] {your FLIP heading}. Also, the design doc
> should follow the FLIP-Template strictly. (The [FLIP] tag is used to inform
> people that it is a FLIP discussion and more attention should be paid.)
> 2. Create a FLIP wiki page(by a committer who wants to shepherd the FLIP)
> once we reach an agreement on the discussion. We can simply copy the google
> doc into the FLIP wiki page. The name of the shepherd should also be listed
> on the wiki page.
> 3. Once the proposal is finalized, call a vote to have the proposal
> adopted. It should be noted that we should always vote on a FLIP wiki page
> instead of a google doc. The wiki page is the final version of the google
> doc.
>
> According to the new process:
> Problem1 can be improved since we only create the FLIP wiki page when we
> reached an agreement.
> Problem2 can be improved since we can make the FLIP wiki page committer
> editable. Not everyone can change the wiki page freely as it is now.
> Problem3 can be improved as the FLIP wiki page is created and updated by
> the committer. Committers are assumed to be more active than contributors.
> This can also be easier to info the guy who is responsible for updating the
> wiki page.
>
> Looking forward to your feedback!
>
> Best,
> Hequn
>
> On Wed, Feb 19, 2020 at 10:20 PM Till Rohrmann <trohrm...@apache.org>
> wrote:
>
> > +1 for Aljoscha's proposal.
> >
> > This, of course, does not mean that one cannot use Google docs in order
> to
> > prepare the FLIP discussion.
> >
> > Cheers,
> > Till
> >
> > On Wed, Feb 19, 2020 at 11:15 AM Xintong Song <tonysong...@gmail.com>
> > wrote:
> >
> > > I'm also not a fun of discussing FLIPs with google docs.
> > >
> > > I think google docs is probably ok for smaller scope early discussions
> > > before raising the discussion on the mailing list, when the draft is
> not
> > > completed and is expected to change frequently. Once it is proposed to
> > the
> > > community, as many people already mentioned, google doc changes are
> very
> > > hard to track.
> > >
> > > If I understand correctly, what Jincheng suggested is to use google doc
> > but
> > > not allowing discussions and modifications on it, except for minor
> > issues.
> > > Regarding that, my concerns are:
> > > - How do we define "minor issues"? Are these typo and grammar issues
> > only?
> > > - If so, I think it is the proposer's responsibility to provide
> > > well-written docs with less such mistakes, if not none. Most editors
> > > provide helpful spelling and grammar checks.
> > > - If not, then people may have different opinions on whether a
> comment
> > is
> > > minor or not.
> > >
> > > Another advantage for the wiki page is that, once you watch it you can
> > > always get email notifications on modifications to that page. AFAIK,
> for
> > > google doc you get notifications only if someone replies your comments,
> > > unless you're the owner of the doc.
> > >
> > > Thank you~
> > >
> > > Xintong Song
> > >
> > >
> > >
> > > On Wed, Feb 19, 2020 at 12:57 PM jincheng sun <
> sunjincheng...@gmail.com>
> > > wrote:
> > >
> > > > Hi all,
> > > >
> > > > Thanks for bring up the discussion @Hequn!
> > > >
> > > > I agree with some concerns raised above, however, I would like to
> give
> > my
> > > > +1 for the proposal and I would like to share my thoughts:
> > > >
> > > > If I understand correctly, the proposal doesn’t encourage people to
> > > discuss
> > > > in the google doc, the first step of the proposal is to raise the
> > > > discussion on the mailing list.
> > > >
> > > > It’s common sense to discuss on the mailing list even with a google
> > doc.
> > > > This is also the current status and works well. Most people know that
> > we
> > > > should focus the discussion on the mailing list especially for those
> > > about
> > > > architecture or something pretty important for discussing which is
> what
> > > we
> > > > want to left the history.
> > > >
> > > > I believe the google doc brings more benefits for us than costs. The
> > > > problem is how we use it, not eliminate it. There are still some
> > benefits
> > > > that we can get from it. For example, It is a good place to comment
> on
> > > the
> > > > document for some minor problems, e.g., typos or grammatical
> problems.
> > > > Correcting these problems could help us to achieve a high-quality
> > > document.
> > > > It is also unnecessarily to left history for these kinds of problems.
> > If
> > > we
> > > > put all these comments into the mailing list. The mailing list would
> be
> > > > flooded. Meanwhile, it’s hard to comment on these problems on the
> > mailing
> > > > list if the document is very long.
> > > >
> > > > As for the FLIP process, it’s a good idea to make our wiki
> “immutable”
> > so
> > > > that we can make the wiki management better, i.e., only editable by
> PMC
> > > or
> > > > committer(This can be discussed in another thread).
> > > >
> > > > What do you think? Would be great if more people can share thoughts
> > here!
> > > >
> > > > Best,
> > > > Jincheng
> > > >
> > > >
> > > > Yuan Mei <yuanmei.w...@gmail.com> 于2020年2月19日周三 下午12:41写道：
> > > >
> > > > > It is difficult to draw a clear cut between small and big issues.
> > > Hence I
> > > > > would prefer to stick to only one way for discussion.
> > > > >
> > > > > I would try to avoid Google Docs if having other ways mainly
> because
> > of
> > > > two
> > > > > reasons:
> > > > >
> > > > > 1. Google Docs are not always accessible to everyone.
> > > > >
> > > > > 2. Discussion on Google docs is difficult to track
> > > > > - new comments are notified through email
> > > > > - discussion history is hard to follow once a comment is
> resolved
> > > > > - limited spaces on the page to display e.t.c
> > > > >
> > > > >
> > > > > Best
> > > > >
> > > > > Yuan
> > > > >
> > > > > On Wed, Feb 19, 2020 at 11:52 AM Jingsong Li <
> jingsongl...@gmail.com
> > >
> > > > > wrote:
> > > > >
> > > > > > Hi all, thanks for launching this discussion.
> > > > > >
> > > > > > About eliminating Google Docs. I agree with Zhijiang, I share my
> > > > concern
> > > > > > about it.
> > > > > >
> > > > > > If the FLIP Driver is a Flink newer or the FLIP is very big and
> > > > > > complicated. His/Her design maybe need change many many things,
> in
> > > this
> > > > > > situation, Google doc is good to be reviewed by community. If all
> > > > > > discussions are in ML, It's going to be very messy.
> > > > > >
> > > > > > So I think can keep this principle:
> > > > > > - Small issues can be discussed on Google doc.
> > > > > > - Big issues, or fundamental design issues, or API issues, are
> > > > discussed
> > > > > in
> > > > > > ML.
> > > > > >
> > > > > > Best,
> > > > > > Jingsong Lee
> > > > > >
> > > > > > On Wed, Feb 19, 2020 at 1:22 AM Zhijiang <
> > wangzhijiang...@aliyun.com
> > > > > > .invalid>
> > > > > > wrote:
> > > > > >
> > > > > > > Thanks for launching this discussion and also agree with the
> > > opinions
> > > > > of
> > > > > > > Kostas, Timo and Aljoscha.
> > > > > > >
> > > > > > > The proposed reasons for eliminating google doc are very
> > > reasonable,
> > > > > > > especially the access limitation for some people in China.
> > > > > > >
> > > > > > > Besides that, another conservative option is to make google doc
> > as
> > > an
> > > > > > > optional procedure, not a must procedure in practice, and
> > > > > > > the ML discussion is still the formal must procedure to follow
> > > > firstly.
> > > > > > > And we can also kindly list these specific
> considerations/reasons
> > > > > > > for google doc concerns as said below in the guideline doc.
> > > > > > >
> > > > > > > To do so, we still retain this option for some people who
> prefer
> > to
> > > > > > google
> > > > > > > doc or willing to provide it in some corner cases.
> > > > > > > Of course I am also happy to eliminate google doc completely.
> > > > > > >
> > > > > > > Best,
> > > > > > > Zhijiang
> > > > > > >
> > > > > > >
> > > > > > >
> > ------------------------------------------------------------------
> > > > > > > From:Kostas Kloudas <kklou...@gmail.com>
> > > > > > > Send Time:2020 Feb. 18 (Tue.) 23:03
> > > > > > > To:dev <dev@flink.apache.org>
> > > > > > > Subject:Re: [DISCUSS] Improvements on FLIP Process
> > > > > > >
> > > > > > > +1 to what Aljoscha and Timo are proposing.
> > > > > > >
> > > > > > > I would lean towards eliminating Google Docs altogether.
> > > > > > > I think they served a purpose when discussions were among 3 to
> 4
> > > > > > > people but with the current size of the community and the
> amount
> > of
> > > > > > > participants per discussion they become difficult to follow.
> > > > > > >
> > > > > > > Best,
> > > > > > > Kostas
> > > > > > >
> > > > > > > On Tue, Feb 18, 2020 at 3:36 PM Timo Walther <
> twal...@apache.org
> > >
> > > > > wrote:
> > > > > > > >
> > > > > > > > +1 to what Aljoscha said.
> > > > > > > >
> > > > > > > > The past has shown that discussions in Google docs do not
> reach
> > > all
> > > > > > > > interested parties and the tracability of design decisions
> > > becomes
> > > > > > > > difficult. Google services are also partially inaccessible in
> > > > certain
> > > > > > > > parts of world.
> > > > > > > >
> > > > > > > > We should actually do the opposite and not allow Google docs
> as
> > > > FLIPs
> > > > > > > > anymore. Commenting should be disabled by default.
> > > > > > > >
> > > > > > > > Regards,
> > > > > > > > Timo
> > > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > On 18.02.20 15:20, Aljoscha Krettek wrote:
> > > > > > > > > Hi,
> > > > > > > > >
> > > > > > > > > thanks for starting this discussion!
> > > > > > > > >
> > > > > > > > > However, I have a somewhat opposing opinion to this: we
> > should
> > > > > > disallow
> > > > > > > > > using Google Docs for FLIPs and FLIP discussions and follow
> > the
> > > > > > already
> > > > > > > > > established process more strictly.
> > > > > > > > >
> > > > > > > > > My reasons for this are:
> > > > > > > > > - discussions on the Google Doc are not reflected in
> Apache
> > > > > > > > > infrastructure
> > > > > > > > > - discussions on Google Docs are non-linear and hard to
> > > follow
> > > > > > > > > - when discussions on Google Docs are resolved these
> > > > discussions
> > > > > > are
> > > > > > > > > not visible/re-readable anymore (I know there's history,
> but
> > > meh)
> > > > > > > > > - if discussion is kept purely to the ML this is easily
> > > > > observable
> > > > > > > for
> > > > > > > > > any interested parties and it's there if somewhat want's to
> > > > recheck
> > > > > > the
> > > > > > > > > discussion in the future
> > > > > > > > > - going from Google Doc to Wiki is an extra step that
> seems
> > > > > > > > > unnecessary to me (but that's just personal opinion, I
> mean,
> > I
> > > > > don't
> > > > > > > > > have to do the extra work here...)
> > > > > > > > >
> > > > > > > > > Best,
> > > > > > > > > Aljoscha
> > > > > > > > >
> > > > > > > > > On 18.02.20 09:02, Hequn Cheng wrote:
> > > > > > > > >> Hi everyone,
> > > > > > > > >>
> > > > > > > > >> Currently, when we create a FLIP we follow the FLIP
> process
> > in
> > > > the
> > > > > > > Flink
> > > > > > > > >> Improvement Proposals wiki[1]. The process mainly includes
> > the
> > > > > > > following
> > > > > > > > >> steps:
> > > > > > > > >> 1. Create a FLIP wiki page.
> > > > > > > > >> 2. Raise the discussion on the mailing list.
> > > > > > > > >> 3. Once the proposal is finalized, call a vote to have the
> > > > > proposal
> > > > > > > > >> adopted.
> > > > > > > > >> There is also a discussion[2] on the FLIP process which
> may
> > be
> > > > > > helpful
> > > > > > > > >> for
> > > > > > > > >> you.
> > > > > > > > >>
> > > > > > > > >> As it is not allowed commented on the wiki, we usually
> have
> > a
> > > > > google
> > > > > > > doc
> > > > > > > > >> for the discussion at step 2 and whenever there is a
> change
> > we
> > > > > need
> > > > > > to
> > > > > > > > >> pick
> > > > > > > > >> it to the wiki page. This makes things somehow redundant.
> To
> > > > solve
> > > > > > > > >> this, we
> > > > > > > > >> can rearrange the step a little bit and avoid the pick:
> > > > > > > > >> 1. Raise the discussion on the mailing list. The subject
> of
> > > the
> > > > > > > thread is
> > > > > > > > >> of the format [DISCUSS][FLIP] {your FLIP heading}. Also,
> the
> > > > > design
> > > > > > > doc
> > > > > > > > >> should follow the FLIP-Template strictly. (The [FLIP] tag
> is
> > > > used
> > > > > to
> > > > > > > > >> inform
> > > > > > > > >> people that it is a FLIP discussion and more attention
> > should
> > > be
> > > > > > > paid.)
> > > > > > > > >> 2. Create a FLIP wiki page once we reached an agreement on
> > the
> > > > > > > > >> discussion.
> > > > > > > > >> We can simply copy the google doc into the FLIP wiki page.
> > > > > > > > >> 3. Once the proposal is finalized, call a vote to have the
> > > > > proposal
> > > > > > > > >> adopted. It should be noted that we should always vote on
> a
> > > FLIP
> > > > > > wiki
> > > > > > > > >> page
> > > > > > > > >> instead of a google doc. The wiki page is the final
> version
> > of
> > > > the
> > > > > > > google
> > > > > > > > >> doc.
> > > > > > > > >>
> > > > > > > > >> This can bring some benefits:
> > > > > > > > >> 1. Make the discussion more effective as we force people
> to
> > > > write
> > > > > > and
> > > > > > > > >> discuss on a google doc that follows the FLIP template
> which
> > > > > > > > >> includes necessary information such as Motivation,
> > Interfaces,
> > > > > > > Proposed
> > > > > > > > >> changes, etc.
> > > > > > > > >> 2. Avoid redundant pick from google doc to Flink wiki
> page.
> > > Once
> > > > > we
> > > > > > > > >> reached
> > > > > > > > >> an agreement on the discussion, we can simply copy the
> > google
> > > > doc
> > > > > > into
> > > > > > > > >> the
> > > > > > > > >> FLIP wiki page.
> > > > > > > > >> 3. As adopted FLIP should mostly be "immutable", we can
> even
> > > > make
> > > > > > the
> > > > > > > > >> wiki
> > > > > > > > >> page PMC or committer editable since it just needs a
> simple
> > > copy
> > > > > > from
> > > > > > > the
> > > > > > > > >> google doc.
> > > > > > > > >>
> > > > > > > > >> Looking forward to your feedback!
> > > > > > > > >>
> > > > > > > > >> Best,
> > > > > > > > >> Hequn
> > > > > > > > >>
> > > > > > > > >> [1]
> > > > > > > > >>
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
> https://cwiki.apache.org/confluence/display/FLINK/Flink+Improvement+Proposals
> > > > > > > > >>
> > > > > > > > >> [2]
> > > > > > > > >>
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
> http://apache-flink-mailing-list-archive.1008284.n3.nabble.com/DISCUSS-META-FLIP-Sticking-or-not-to-a-strict-FLIP-voting-process-td29978.html#a29988
> > > > > > > > >>
> > > > > > > > >>
> > > > > > > >
> > > > > > >
> > > > > > >
> > > > > >
> > > > > > --
> > > > > > Best, Jingsong Lee
> > > > > >
> > > > >
> > > >
> > >
> >
>
