flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Matthias J. Sax" <mj...@informatik.hu-berlin.de>
Subject Re: How do we want to maintain our documentation?
Date Thu, 04 Jun 2015 12:19:02 GMT
Big +1 :)

On 06/04/2015 01:33 PM, Robert Metzger wrote:
> I would also say that in particular big changes should include an update to
> the documentation as well!
> 
> I'll add a rule to the guidelines and I'll start annoying you to write
> documentation in pull requests.
> 
> On Thu, Jun 4, 2015 at 1:06 PM, Maximilian Michels <mxm@apache.org> wrote:
> 
>> +1 for your proposed changes, Robert. I would argue that is even more
>> crucial that big pull requests contain documentation because a lot of times
>> only the contributor can create this documentation. Additionally,
>> documentation makes reviewing a pull request much easier.
>>
>> Fragmented documentation is a separate issue. We have to make sure that we
>> check the quality of the documentation in addition to the quality of the
>> submitted code.
>>
>> On Wed, Jun 3, 2015 at 11:57 PM, Fabian Hueske <fhueske@gmail.com> wrote:
>>
>>> +1 for Robert's suggestion.
>>>
>>> In fact, I thought this was already our practice. Also I would not allow
>>> exceptions from that rule in the "stable" codebase. Writing documentation
>>> and describing how stuff should be used lets you think about it in a
>>> different way and can help to make the feature better. Also features
>> which
>>> are not documented do not exist. We might be less strict with changes to
>>> flink-staging but as soon as it moves out, documentation must be
>>> "complete".
>>>
>>> However, such a rule will only help to have (more) complete
>> documentation,
>>> but not necessarily good documentation. I observed that documentation
>> tends
>>> to cluttered and more fragmented if more people add and change stuff. I
>>> guess from time to time, documentation just needs to be restructured and
>>> partially rewritten.
>>>
>>> 2015-06-03 18:19 GMT+02:00 Vasiliki Kalavri <vasilikikalavri@gmail.com>:
>>>
>>>> Hi,
>>>>
>>>> in principle I agree with Robert's suggestion.
>>>>
>>>> I can only see two cases where this might not work well:
>>>>
>>>> - if the change is something big / totally new and the documentation to
>>> be
>>>> written is large. In this case, I would prefer to have a separate issue
>>> for
>>>> docs to ensure better quality and review, otherwise we might end up
>> with
>>>> following "improve docs" issues
>>>>
>>>> - if the code change is blocking some other issue. Then, it might make
>>>> sense to merge the code fast and update the docs fast.
>>>>
>>>> In any case though, I agree that it's not a good idea to have someone
>>>> adding the missing docs just before the release.
>>>>
>>>> Cheers,
>>>> -Vasia.
>>>>
>>>> On 3 June 2015 at 17:27, Till Rohrmann <trohrmann@apache.org> wrote:
>>>>
>>>>> For me it also makes sense that the contributor who has implemented
>> the
>>>>> changes and thus knows them best should update the documentation
>>>>> accordingly.
>>>>>
>>>>> +1
>>>>>
>>>>> On Wed, Jun 3, 2015 at 5:25 PM, Chiwan Park <chiwanpark@icloud.com>
>>>> wrote:
>>>>>
>>>>>> +1 Good. PR should contain documentation.
>>>>>>
>>>>>> Regards,
>>>>>> Chiwan Park
>>>>>>
>>>>>>> On Jun 4, 2015, at 12:24 AM, Lokesh Rajaram <
>>>> rajaram.lokesh@gmail.com>
>>>>>> wrote:
>>>>>>>
>>>>>>> +1. I like this idea, not sure if my vote counts :)
>>>>>>>
>>>>>>> On Wed, Jun 3, 2015 at 8:21 AM, Robert Metzger <
>>> rmetzger@apache.org>
>>>>>> wrote:
>>>>>>>
>>>>>>>> Hi,
>>>>>>>>
>>>>>>>> as part of making our codebase ready for the upcoming 0.9
>> release,
>>>>> I've
>>>>>>>> started to go over the documentation of Flink.
>>>>>>>>
>>>>>>>> It seems that our current approach for documenting stuff:
>>>>>>>> - We implement and merge a feature
>>>>>>>> - We open a JIRA for documenting it.
>>>>>>>>
>>>>>>>> Before the release, we realize that we have many open
>>> documentation
>>>>>> issues
>>>>>>>> (currently 26) and hope that somebody (in this case me) is
>> fixing
>>>>> them.
>>>>>>>>
>>>>>>>> Some of the pull requests also contain documentation, but
>>> certainly
>>>>> not
>>>>>> all
>>>>>>>> of them.
>>>>>>>>
>>>>>>>>
>>>>>>>> I am proposing to:
>>>>>>>> - add a rule to our coding guidelines [1] which states that
>> every
>>>>> change
>>>>>>>> that affects the documentation needs to update the documentation
>>>>>>>> accordingly.
>>>>>>>> - Committers have to make sure that pull request are following
>> the
>>>>> rule
>>>>>>>> before accepting the change. Otherwise, we reject the pull
>>> request.
>>>>>>>>
>>>>>>>>
>>>>>>>> [1] http://flink.apache.org/coding-guidelines.html
>>>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
> 


Mime
View raw message