[FFmpeg-devel] Accurately describing ffmpeg-cvslog list [was: Re: [PATCH] Refactor Developer Docs, update dev list section (v2)]

[Jim DeLaHunt]

On 2017-11-27 15:03, Carl Eugen Hoyos wrote:

> 2017-11-26 22:57 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev at jdlh.com>:
>> On 2017-11-26 03:42, Carl Eugen Hoyos wrote:
>>
>>> 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev at jdlh.com>:
>>> [...]
>>>> +
>>>>    @subheading Subscribe to the ffmpeg-cvslog mailing list.
>>>> -It is important to do this as the diffs of all commits are sent there
>>>> and
>>>> -reviewed by all the other developers. Bugs and possible improvements or
>>>> -general questions regarding commits are discussed there. We expect you
>>>> to
>>>> -react if problems with your code are uncovered.
>>>> +Diffs of all commits are sent to the
>>>> + at uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-cvslog,
>>>> ffmpeg-cvslog}
>>>> +mailing list. Some developers read this list to review all code base
>>>> changes
>>>> +from all sources. Subscribing to this list is not mandatory, if
>>>> +all you want to do is submit a patch here and there.
>>> I am (still) against this change.
>>
>> OK, what specifically are you against?  More important, what are you in
>> favour of?
> I have no issue with the current text.

With respect, this section of ffmpeg.org/develop.html is not intended 
for an experienced, knowledgeable, deeply involved senior committer like 
you.  So it doesn't really matter that you have no issue with the 
current text. What matters is whether a new developer, trying to learn 
how to contribute to ffmpeg, has an issue with the text.

I can tell you that, as a new contributor reading this section with 
fresh eyes, I most certainly do have an issue with this text. It says 
things about how ffmpeg-cvslog are used that are flat out incorrect. 
Incorrect instructions waste time and cause confusion.

> If you believe that it is unclear that there is a difference between an
> occasional contributor (who most likely would not read -devel nor
> -cvslog) and a committer (who is supposed to read -cvslog), then
> maybe a patch is useful.

I will point out that two more people, Ronald[1] and Rostislav[2], do 
not behave in accordance with your belief that committers are supposed 
to read -cvslog. How sure are you that your belief reflects what the 
project actually expects?

I proposed my wording above.  What wording describing -cvslog, which 
corrects the incorrect information and reflects what your colleagues 
tell you about how they use the list, would you accept?

> I believe the difference could be considered common sense.
As I said in the thread about ffmpeg-devel[3], Your sense of what is 
common might be biased by how much you know. I am here to tell you that 
the paragraphs in this patch are not at all "common sense". New 
contributors need to have them said out loud.
[1] http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221152.html
[2] http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221155.html
[3] http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221199.html

My goal here is to fix the bug in ffmpeg.org/developer.html, in the 
section which describes the -cvslog mailing list. I'll make the patch. 
Just tell me what wording will pass review.

-- 
     --Jim DeLaHunt, jdlh at jdlh.com     http://blog.jdlh.com/ (http://jdlh.com/)
       multilingual websites consultant

       355-1027 Davie St, Vancouver BC V6E 4L2, Canada
          Canada mobile +1-604-376-8953