Thanks, everyone, for the positive feedback :-) @Robert - It probably makes sense to break this down into various pages, like PR, general code style guide, Java, component specific guides, formats, etc.
Best, Stephan On Fri, Jun 21, 2019 at 4:29 PM Robert Metzger <rmetz...@apache.org> wrote: > It seems that the discussion around this topic has settled. > > I'm going to turn the Google Doc into a markdown file (maybe also multiple, > I'll try out different things) and then open a pull request for the Flink > website. > I'll post a link to the PR here once I'm done. > > On Fri, Jun 14, 2019 at 9:36 AM zhijiang <wangzhijiang...@aliyun.com > .invalid> > wrote: > > > Thanks for providing this useful guide for benefiting both contributors > > and committers in consistency. > > > > I just reviewed and learned the whole doc which covers a lot of > > information. Wish it further categoried and put onto somewhere for easily > > traced future. > > > > Best, > > Zhijiang > > ------------------------------------------------------------------ > > From:Robert Metzger <rmetz...@apache.org> > > Send Time:2019年6月14日(星期五) 14:24 > > To:dev <dev@flink.apache.org> > > Subject:Re: [DISCUSS] Adopting a Code Style and Quality Guide > > > > Thanks a lot for putting this together! > > > > I'm in the process of reworking the "How to contribute" pages [1] and I'm > > happy to add the guide to the Flink website, once the discussion here is > > over. > > > > [1] https://github.com/apache/flink-web/pull/217 > > > > On Fri, Jun 14, 2019 at 3:21 AM Kurt Young <ykt...@gmail.com> wrote: > > > > > Big +1 and thanks for preparing this. > > > > > > I think wha't more important is making sure most all the contributors > can > > > follow > > > the same guide, a clear document is definitely a great start. > Committers > > > can > > > first try to follow the guide by self, and spread the standard during > > code > > > reviewing. > > > > > > Best, > > > Kurt > > > > > > > > > On Thu, Jun 13, 2019 at 8:28 PM Congxian Qiu <qcx978132...@gmail.com> > > > wrote: > > > > > > > +1 for this, I think all contributors can benefit from this. > > > > > > > > Best, > > > > Congxian > > > > > > > > > > > > Aljoscha Krettek <aljos...@apache.org> 于2019年6月13日周四 下午8:14写道： > > > > > > > > > +1 I think this is a very good effort and should put to rest some > > > > > back-and-forth discussions on PRs and some differences in “style” > > > between > > > > > committers. ;-) > > > > > > > > > > > On 13. Jun 2019, at 10:21, JingsongLee <lzljs3620...@aliyun.com > > > > .INVALID> > > > > > wrote: > > > > > > > > > > > > big +1, the content is very useful and enlightening. > > > > > > But it's really too long to look at. > > > > > > +1 for splitting it and expose it to contributors. > > > > > > > > > > > > Even I think it's possible to put its link on the default > > description > > > > of > > > > > > pull request, so that the user has to see it when submits the > code. > > > > > > > > > > > > Best, JingsongLee > > > > > > > > > > > > > > > > > > > ------------------------------------------------------------------ > > > > > > From:Piotr Nowojski <pi...@ververica.com> > > > > > > Send Time:2019年6月13日(星期四) 16:03 > > > > > > To:dev <dev@flink.apache.org> > > > > > > Subject:Re: [DISCUSS] Adopting a Code Style and Quality Guide > > > > > > > > > > > > +1 for it and general content and thank everybody that was > involved > > > in > > > > > creating & writing this down. > > > > > > > > > > > > +1 for splitting it up into some easily navigable topics. > > > > > > > > > > > > Piotrek > > > > > > > > > > > >> On 13 Jun 2019, at 09:54, Stephan Ewen <se...@apache.org> > wrote: > > > > > >> > > > > > >> This should definitely be split up into topics, agreed. > > > > > >> And it should be linked form the "how to contribute" page or the > > PR > > > > > >> template to make contributors aware. > > > > > >> > > > > > >> On Thu, Jun 13, 2019 at 9:51 AM Zili Chen <wander4...@gmail.com > > > > > > wrote: > > > > > >> > > > > > >>> Thanks for creating this guide Stephan. It is also > > > > > >>> a good start point to internals doc. > > > > > >>> > > > > > >>> One suggestion is we could finally separate the guide > > > > > >>> into separated files each of which focus on a specific > > > > > >>> topic. Besides, add the guide to our repository should > > > > > >>> make contributors more aware of it. > > > > > >>> > > > > > >>> Best, > > > > > >>> tison. > > > > > >>> > > > > > >>> > > > > > >>> Jeff Zhang <zjf...@gmail.com> 于2019年6月13日周四 下午3:35写道： > > > > > >>> > > > > > >>>> Thanks for the proposal, Stephan. Big +1 on this. > > > > > >>>> > > > > > >>>> This is definitely helpful and indispensable for flink's code > > > > quality > > > > > and > > > > > >>>> healthy community growth. > > > > > >>>> It would also benefit downstream project to integrate flink > > > easier. > > > > > >>>> > > > > > >>>> > > > > > >>>> Till Rohrmann <trohrm...@apache.org> 于2019年6月13日周四 下午3:29写道： > > > > > >>>> > > > > > >>>>> Thanks for creating this code style and quality guide > Stephan. > > I > > > > > think > > > > > >>>>> Flink can benefit from such a guide. Thus +1 for introducing > > and > > > > > >>> adhering > > > > > >>>>> to it. > > > > > >>>>> > > > > > >>>>> Cheers, > > > > > >>>>> Till > > > > > >>>>> > > > > > >>>>> On Thu, Jun 13, 2019 at 5:26 AM Bowen Li < > bowenl...@gmail.com> > > > > > wrote: > > > > > >>>>> > > > > > >>>>>> Hi Stephan, > > > > > >>>>>> > > > > > >>>>>> Definitely a good guide in principle IMO! I personally > already > > > > find > > > > > >>> it > > > > > >>>>>> useful in practice to learn from it myself, and also promote > > and > > > > > >>>>> cultivate > > > > > >>>>>> a better coding habit around by referencing it. So big +1 to > > > adopt > > > > > >>> it. > > > > > >>>>>> > > > > > >>>>>> Also want to highlight that we need to make real use of it, > > and > > > > keep > > > > > >>>>>> ensuring people are aware of its existence. Adding it to > Flink > > > > > >>> website > > > > > >>>>>> would be nice. We can also adding noticeable link for it to > > the > > > > > >>>> template > > > > > >>>>> of > > > > > >>>>>> github PR (where this guide really matters) to get attention > > and > > > > > >>>>> exposure. > > > > > >>>>>> > > > > > >>>>>> BTW, what's the plan on how people can raise new > > > > > coding-style/quality > > > > > >>>>>> related questions, how to expand and adjust the content over > > > time, > > > > > >>> how > > > > > >>>> to > > > > > >>>>>> inform the community of such updates and changes? Maybe we > can > > > use > > > > > >>> some > > > > > >>>>>> tags like "[CODING STYLE]" in dev mailing list for these > type > > of > > > > > >>>>>> communications? This can be a separate discussion though if > we > > > > wish. > > > > > >>>>>> > > > > > >>>>>> All in all, big +1 for adopting it. > > > > > >>>>>> > > > > > >>>>>> Bowen > > > > > >>>>>> > > > > > >>>>>> > > > > > >>>>>> > > > > > >>>>>> > > > > > >>>>>> On Wed, Jun 12, 2019 at 12:32 PM Stephan Ewen < > > se...@apache.org > > > > > > > > > >>>> wrote: > > > > > >>>>>> > > > > > >>>>>>> Hi all! > > > > > >>>>>>> > > > > > >>>>>>> I want to propose that we try and adopt a code style and > > > quality > > > > > >>>> guide. > > > > > >>>>>> Its > > > > > >>>>>>> a big endeavor, but I think it's worth trying :-) > > > > > >>>>>>> > > > > > >>>>>>> The Apache Flink community and contributor base is growing > > > quite > > > > a > > > > > >>>> bit, > > > > > >>>>>> new > > > > > >>>>>>> committers and contributors are coming on board frequently. > > > > > >>> Everyone > > > > > >>>>>> comes > > > > > >>>>>>> from a different background and brings a different level of > > > > > >>>> experience. > > > > > >>>>>>> Different contributors apply different styles, and > > > contributions > > > > > >>> are > > > > > >>>>>>> naturally of varying code quality. > > > > > >>>>>>> > > > > > >>>>>>> We are struggling with finding a good balance between: > > > > > >>>>>>> > > > > > >>>>>>> (1) On the one hand maintaining a certain code standard > for a > > > big > > > > > >>>> and > > > > > >>>>>>> complex system like Flink, to reduce bugs and make future > > > > > >>>> contributions > > > > > >>>>>>> feasible (and not impossible due to code complexity). > > > > > >>>>>>> > > > > > >>>>>>> (2) On the other hand, make contributions possible for > > > > > >>>> contributors. > > > > > >>>>>> This > > > > > >>>>>>> means not guarding everything to the point that no > > > contributions > > > > > >>> can > > > > > >>>>> get > > > > > >>>>>> in > > > > > >>>>>>> any more. > > > > > >>>>>>> > > > > > >>>>>>> My suggestion to help with this is to define a standard and > > > > > >>> document > > > > > >>>> it > > > > > >>>>>>> explicitly. It will help to get everyone on the same page > > what > > > > the > > > > > >>>>>>> expectation is, and it helps contributors know what to pay > > > > > >>> attention > > > > > >>>>> to. > > > > > >>>>>>> Such a guide should also help make review more efficient, > > > because > > > > > >>>>>>> contributors can know up front what reviewers will look at. > > > > > >>>>>>> > > > > > >>>>>>> Over the past weeks, I took a look at the current Flink > code > > > base > > > > > >>> and > > > > > >>>>>>> talked to some committers and contributors and tried to > come > > up > > > > > >>> with > > > > > >>>> a > > > > > >>>>>>> proposal that reflects the approaches and standards that > many > > > > > >>>>> committers > > > > > >>>>>>> have adopted lately. > > > > > >>>>>>> > > > > > >>>>>>> > > > > > >>>>>>> > > > > > >>>>>> > > > > > >>>>> > > > > > >>>> > > > > > >>> > > > > > > > > > > > > > > > https://docs.google.com/document/d/1owKfK1DwXA-w6qnx3R7t2D_o0BsFkkukGlRhvl3XXjQ > > > > > >>>>>>> > > > > > >>>>>>> > > > > > >>>>>>> This guide is not fix and final, we should discuss it and > > > expand > > > > > >>> and > > > > > >>>>>> adjust > > > > > >>>>>>> it over time. The guide tries to strike a balance between > too > > > > much > > > > > >>>>>> contents > > > > > >>>>>>> (don't force someone to read a book before contributing) > and > > > > being > > > > > >>>>>>> comprehensive enough. The guide looks long, but much of it > > are > > > > > >>>>> component > > > > > >>>>>> or > > > > > >>>>>>> aspect specific parts, like how to deal with new > > dependencies, > > > > > >>>>>>> configuration changes, etc. > > > > > >>>>>>> > > > > > >>>>>>> I an curious to hear whether you think such a guide is in > > > > > >>> principle a > > > > > >>>>>> good > > > > > >>>>>>> idea. > > > > > >>>>>>> If yes, is the one here a good starting point? > > > > > >>>>>>> > > > > > >>>>>>> Best, > > > > > >>>>>>> Stephan > > > > > >>>>>>> > > > > > >>>>>> > > > > > >>>>> > > > > > >>>> > > > > > >>>> > > > > > >>>> -- > > > > > >>>> Best Regards > > > > > >>>> > > > > > >>>> Jeff Zhang > > > > > >>>> > > > > > > > > > > > > > > > > > > > > > >
