Thanks for the feedback everybody. I updated the PR and would like to merge it later today if there are no more comments.
Cheers, Fabian 2015-10-05 14:09 GMT+02:00 Fabian Hueske <fhue...@gmail.com>: > Hi, > > I opened a PR with the discussed changes [1]. > Please review, give feedback, and suggest changes. > > Cheers, Fabian > > [1] https://github.com/apache/flink-web/pull/11 > > > 2015-09-28 18:02 GMT+02:00 Fabian Hueske <fhue...@gmail.com>: > >> @Chiwan, sure. Will do that. Thanks for pointing it out :-) >> >> 2015-09-28 18:00 GMT+02:00 Chiwan Park <chiwanp...@apache.org>: >> >>> @Fabian, Could you cover FLINK-2712 in your pull request? I think that >>> it would be better than split pull request. >>> >>> Regards, >>> Chiwan Park >>> >>> > On Sep 28, 2015, at 4:51 PM, Fabian Hueske <fhue...@gmail.com> wrote: >>> > >>> > Thanks everybody for the discussion. >>> > I'll prepare a pull request to update the "How to contribute" and >>> "Coding >>> > Guidelines". >>> > >>> > Thanks, >>> > Fabian >>> > >>> > 2015-09-26 9:06 GMT+02:00 Maximilian Michels <m...@apache.org>: >>> > >>> >> Hi Fabian, >>> >> >>> >> This is a very important topic. Thanks for starting the discussion. >>> >> >>> >> 1) JIRA discussion >>> >> >>> >> Absolutely. No new feature should be introduced without a discussion. >>> >> Frankly, I see the problem that sometimes discussions only come up >>> >> when the pull request has been opened. However, this can be overcome >>> >> by the design document. >>> >> >>> >> 2) Design document >>> >> >>> >> +1 for the document. It increases transparency but also helps the >>> >> contributor to think his idea through before starting to code. The >>> >> document could also be written directly in JIRA. That way, it is more >>> >> accessible. JIRA offers mark up; even images can be attached and >>> >> displayed in the JIRA description. >>> >> >>> >> I'd like to propose another section "Limitations" for the design >>> >> document. Breaking API changes should also be listed on a special Wiki >>> >> page. >>> >> >>> >> 3) Coding style >>> >> >>> >> In addition to updating the document, do we want to enforce coding >>> >> styles also by adding new Maven Checkstyle rules? IMHO strict rules >>> >> could cause more annoyances than they actually contribute to the >>> >> readability of the code. Perhaps this should be discussed in a >>> >> separate thread. >>> >> >>> >> +1 for collecting common problems and design patterns to include them >>> >> in the document. I was thinking, that we should also cover some of the >>> >> features of tools and dependencies we heavily use, e.g. Travis, >>> >> Mockito, Guava, Log4j, FlinkMiniCluster, Unit testing vs IT cases, >>> >> etc. >>> >> >>> >> 4 ) Restructuring the how to contribute guide >>> >> >>> >> Good idea to have a meta document that explains how contributing works >>> >> in general, and another document for technical things. >>> >> >>> >> >>> >> Cheers, >>> >> Max >>> >> >>> >> >>> >> On Thu, Sep 24, 2015 at 2:53 PM, Fabian Hueske <fhue...@gmail.com> >>> wrote: >>> >>> >>> >>> Thanks everybody for feedback and comments. >>> >>> >>> >>> Regarding 1) and 2): >>> >>> >>> >>> I like the idea of keeping the discussion of new features and >>> >> improvements >>> >>> in JIRA as Kostas proposed. >>> >>> Our coding guidelines [1] already request a JIRA issue for each pull >>> >>> request. >>> >>> >>> >>> How about we highlight this requirement more prominently and follow >>> this >>> >>> rule more strict from now on. >>> >>> JIRA issues for new features and improvements should clearly specify >>> the >>> >>> scope and requirements for the new feature / improvement. >>> >>> The level of detail is up to the reporter of the issue, but the >>> community >>> >>> can request more detail or change the scope and requirements by >>> >> discussion. >>> >>> When a JIRA issue for a new feature or improvement is opened, the >>> >> community >>> >>> can start a discussion whether the feature is desirable for Flink or >>> not. >>> >>> Any contributor (including the reporter) can also attach a >>> >>> "design-doc-requested" label to the issue. A design document can be >>> >>> proposed by anybody, including the reporter or assignee of the JIRA >>> >> issue. >>> >>> However, the issue cannot be resolved and a corresponding PR not be >>> >> merged >>> >>> before a design document has been accepted by lazy consensus. Hence, >>> an >>> >>> assignee should propose a design doc before starting to code to avoid >>> >> major >>> >>> redesigns of the implementation. >>> >>> >>> >>> This way it is up to the community when to start a discussion about >>> >> whether >>> >>> a feature request is accepted or to request a design document. We can >>> >> make >>> >>> design documents mandatory for changes that touch the public API. >>> >>> >>> >>> Regarding 3): >>> >>> >>> >>> I agree with Vasia, that we should collect suggestions for common >>> >> patterns >>> >>> and also continuously update the coding guidelines. >>> >>> @Henry, I had best practices (exception handling, tests, etc.) in >>> mind. >>> >>> Syntactic code style is important as well, but we should have a >>> separate >>> >>> discussion about that, IMO. >>> >>> >>> >>> Proposal for a design document template: >>> >>> >>> >>> - Overview of general approach >>> >>> - API changes (changed interfaces, new / deprecated configuration >>> >>> parameters, changed behavior) >>> >>> - Main components and classes to touch >>> >>> >>> >>> Cheers, >>> >>> Fabian >>> >>> >>> >>> [1] http://flink.apache.org/coding-guidelines.html >>> >>> <http://flink.apache.org/coding-guidelines.html> >>> >>> >>> >>> 2015-09-24 10:52 GMT+02:00 Chiwan Park <chiwanp...@apache.org>: >>> >>> >>> >>>> Thanks Fabian for starting the discussion. >>> >>>> >>> >>>> +1 for overall approach. >>> >>>> >>> >>>> About (1), expressing that consensus must be required for new >>> feature >>> >> in >>> >>>> “How to contribute” page is very nice. Some pull requests were sent >>> >> without >>> >>>> consensus. The contributors had to rewrote their pull requests. >>> >>>> >>> >>>> Agree with (2), (3) and (4). >>> >>>> >>> >>>> Regards, >>> >>>> Chiwan Park >>> >>>> >>> >>>>> On Sep 24, 2015, at 2:23 AM, Henry Saputra < >>> henry.sapu...@gmail.com> >>> >>>> wrote: >>> >>>>> >>> >>>>> Thanks again, Fabian for starting the discussions. >>> >>>>> >>> >>>>> For (1) and (2) I think it is good idea and will help people to >>> >>>>> understand and follow the author thought process. >>> >>>>> Following up with Stephan's reply, some new features solutions >>> could >>> >>>>> be explained thoroughly in the PR descriptions but some requires >>> >>>>> additional reviews of the proposed design. >>> >>>>> I like the idea of using tag in JIRA whether new features should or >>> >>>>> should not being accompanied by design document. >>> >>>>> >>> >>>>> Agree with (3) and (4). >>> >>>>> As for (3) are you thinking about more of style of code syntax via >>> >>>>> checkstyle updates, or best practices in term of no mutable state >>> if >>> >>>>> possible, throw precise Exception if possible for interfaces, etc. >>> ? >>> >>>>> >>> >>>>> - Henry >>> >>>>> >>> >>>>> >>> >>>>> >>> >>>>> >>> >>>>> On Wed, Sep 23, 2015 at 9:31 AM, Stephan Ewen <se...@apache.org> >>> >> wrote: >>> >>>>>> Thanks, Fabian for driving this! >>> >>>>>> >>> >>>>>> I agree with your points. >>> >>>>>> >>> >>>>>> Concerning Vasia's comment to not raise the bar too high: >>> >>>>>> That is true, the requirements should be reasonable. We can >>> >> definitely >>> >>>> tag >>> >>>>>> issues as "simple" which means they do not require a design >>> >> document. >>> >>>> That >>> >>>>>> should be more for new features and needs not be very detailed. >>> >>>>>> >>> >>>>>> We could also make the inverse, meaning we explicitly tag certain >>> >>>> issues as >>> >>>>>> "requires design document". >>> >>>>>> >>> >>>>>> Greetings, >>> >>>>>> Stephan >>> >>>>>> >>> >>>>>> >>> >>>>>> >>> >>>>>> >>> >>>>>> On Wed, Sep 23, 2015 at 5:05 PM, Vasiliki Kalavri < >>> >>>> vasilikikala...@gmail.com >>> >>>>>>> wrote: >>> >>>>>> >>> >>>>>>> Hi, >>> >>>>>>> >>> >>>>>>> I agree with you Fabian. Clarifying these issues in the "How to >>> >>>> Contribute" >>> >>>>>>> guide will save lots of time both to reviewers and contributors. >>> >> It is >>> >>>> a >>> >>>>>>> really disappointing situation when someone spends time >>> >> implementing >>> >>>>>>> something and their PR ends up being rejected because either the >>> >>>> feature >>> >>>>>>> was not needed or the implementation details were never agreed >>> on. >>> >>>>>>> >>> >>>>>>> That said, I think we should also make sure that we don't raise >>> the >>> >>>> bar too >>> >>>>>>> high for simple contributions. >>> >>>>>>> >>> >>>>>>> Regarding (1) and (2), I think we should clarify what kind of >>> >>>>>>> additions/changes require this process to be followed. e.g. do we >>> >> need >>> >>>> to >>> >>>>>>> discuss additions for which JIRAs already exist? Ideas described >>> >> in the >>> >>>>>>> roadmaps? Adding a new algorithm to Gelly/Flink-ML? >>> >>>>>>> >>> >>>>>>> Regarding (3), maybe we can all suggest some examples/patterns >>> that >>> >>>> we've >>> >>>>>>> seen when reviewing PRs and then choose the most common (or all). >>> >>>>>>> >>> >>>>>>> (4) sounds good to me. >>> >>>>>>> >>> >>>>>>> Cheers, >>> >>>>>>> Vasia. >>> >>>>>>> >>> >>>>>>> On 23 September 2015 at 15:08, Kostas Tzoumas < >>> ktzou...@apache.org >>> >>> >>> >>>> wrote: >>> >>>>>>> >>> >>>>>>>> Big +1. >>> >>>>>>>> >>> >>>>>>>> For (1), a discussion in JIRA would also be an option IMO >>> >>>>>>>> >>> >>>>>>>> For (2), let us come up with few examples on what constitutes a >>> >>>> feature >>> >>>>>>>> that needs a design doc, and what should be in the doc (IMO >>> >>>>>>>> architecture/general approach, components touched, interfaces >>> >> changed) >>> >>>>>>>> >>> >>>>>>>> >>> >>>>>>>> >>> >>>>>>>> On Wed, Sep 23, 2015 at 2:24 PM, Fabian Hueske < >>> fhue...@gmail.com >>> >>> >>> >>>>>>> wrote: >>> >>>>>>>> >>> >>>>>>>>> Hi everybody, >>> >>>>>>>>> >>> >>>>>>>>> I guess we all have noticed that the Flink community is quickly >>> >>>> growing >>> >>>>>>>> and >>> >>>>>>>>> more and more contributions are coming in. Recently, a few >>> >>>>>>> contributions >>> >>>>>>>>> proposed new features without being discussed on the mailing >>> >> list. >>> >>>> Some >>> >>>>>>>> of >>> >>>>>>>>> these contributions were not accepted in the end. In other >>> cases, >>> >>>> pull >>> >>>>>>>>> requests had to be heavily reworked because the approach taken >>> >> was >>> >>>> not >>> >>>>>>>> the >>> >>>>>>>>> best one. These are situations which should be avoided because >>> >> both >>> >>>> the >>> >>>>>>>>> contributor as well as the person who reviewed the contribution >>> >>>>>>> invested >>> >>>>>>>> a >>> >>>>>>>>> lot of time for nothing. >>> >>>>>>>>> >>> >>>>>>>>> I had a look at our “How to contribute” and “Coding guideline” >>> >> pages >>> >>>>>>> and >>> >>>>>>>>> think, we can improve them. I see basically two issues: >>> >>>>>>>>> >>> >>>>>>>>> 1. The documents do not explain how to propose and discuss new >>> >>>>>>> features >>> >>>>>>>>> and improvements. >>> >>>>>>>>> 2. The documents are quite technical and the structure could be >>> >>>>>>>> improved, >>> >>>>>>>>> IMO. >>> >>>>>>>>> >>> >>>>>>>>> I would like to improve these pages and propose the following >>> >>>>>>> additions: >>> >>>>>>>>> >>> >>>>>>>>> 1. Request contributors and committers to start discussions on >>> >> the >>> >>>>>>>>> mailing list for new features. This discussion should help to >>> >> figure >>> >>>>>>> out >>> >>>>>>>>> whether such a new feature is a good fit for Flink and give >>> first >>> >>>>>>>> pointers >>> >>>>>>>>> for a design to implement it. >>> >>>>>>>>> 2. Require contributors and committers to write design >>> >> documents for >>> >>>>>>>> all >>> >>>>>>>>> new features and major improvements. These documents should be >>> >>>> attached >>> >>>>>>>> to >>> >>>>>>>>> a JIRA issue and follow a template which needs to be defined. >>> >>>>>>>>> 3. Extend the “Coding Style Guides” and add patterns that are >>> >>>>>>> commonly >>> >>>>>>>>> remarked in pull requests. >>> >>>>>>>>> 4. Restructure the current pages into three pages: a general >>> >> guide >>> >>>>>>> for >>> >>>>>>>>> contributions and two guides for how to contribute to code and >>> >>>> website >>> >>>>>>>> with >>> >>>>>>>>> all technical issues (repository, IDE setup, build system, >>> etc.) >>> >>>>>>>>> >>> >>>>>>>>> Looking forward for your comments, >>> >>>>>>>>> Fabian >>> >>>>>>>>> >>> >>>>>>>> >>> >>>>>>> >>> >>>> >>> >>>> >>> >>>> >>> >>>> >>> >>>> >>> >>>> >>> >> >>> >>> >>> >>> >>> >>> >> >
