[FFmpeg-devel] Policy on ffmpeg-devel list and contributions [was: Re: [PATCH] Refactor Developer Docs, update dev list section (v2)]

[Jim DeLaHunt]

On 2017-11-29 06:53, Compn wrote:

> [...]
>> Also, someone once observed that common sense is not very common. :-)
> sure, but please remember the DOCS are already quite verbose, and
> brevity is the soul of wit. so if you can say more with less verbiage
> that would be great.
> [...]
> Also please note that most ffmpeg developers and patch authors are from
> around the world , and english may not be their native language.
I'd be happy to work on better wording. I think the obstacle is more 
fundamental: there isn't agreement on what to say, or a consensus that 
it should be said at all.

>
>> I find it interesting that bug fixes and enhancements to the source code
>> of ffmpeg are approved so much more easily than this patch's bug fixes
>> and enhancements to the text of ffmpeg.org. This is not a smooth
>> documentation process.
> haha! well let me please explain to you what situation you have gotten
> yourself stuck into! :)
>
> the development docs that you want to patch are actually the ffmpeg
> project's written rules and policy that governs the whole shebang.
>
> so these are the rules that all devs must agree to within the project.
> sure, we bicker about the rules and not everyone follows every rule,
> and we have many unwritten rules that we also abide by. which also
> causes great strife sometimes when someone thinks a rule is official or
> not... look i didnt say it was a good system, it is what we have
> evolved into over the years.
>
> the point is that changes to this specific part of the documentation
> affects all devs, not just new contributors. so we are more interested
> to changes of this document. especially large changes all in one patch.
>
> what your v1 patch has unintentionally done is to change our long
> standing ffmpeg policy about patch submission and review. i know this
> was not your intention, but you have picked one of the core parts of the
> project to modify on your first attempt. :)

What this says to me is that the problems I observe in 
ffmpeg.org/developer.html go deeper than wording.

There are architectural problems: this one page is supposed to serve as 
both the reference for the project's rules and as a tutorial for new 
contributors. The requirements for these two purposes differ.

There are governance problems: rules exist for important parts of the 
project, but they are not in writing. Exhibit 1 is that the ffmpeg-devel 
list is central to this project, but there is presently zero description 
of it in this web page. Exhibit 2 is that the actual practice of the 
ffmpeg-cvslog list by several senior developers clearly differs from the 
description of it in this page. Exhibit 3 is the absence in this whole 
discussion of any reference to any rule-making process and its 
decisions, when the patch appears to intrude on policy matters.

There are process problems: while I see lots of activity and appropriate 
process for improving the code of the ffmpeg executables, there is not 
similar activity or appropriate process for improving the documentation. 
I think this thread shows that the patch/review/reject or accept model 
used for code doesn't work so well for words.

And then there are the writing problems: broken links, all content under 
one @chapter, checklists but no instructions to use the checklists, 
missing content, unclear content, and so on.

I came here to try to fix the most severe, easiest to fix bugs in the 
docs. I am learning that nothing about ffmpeg.org/developer.html is 
going to be easy to fix.  I am skeptical that splitting the docs patch 
will help.

> hope this clears things up. feel free to ask me questions off list, or
> we can be found on irc.freenode.net #ffmpeg-devel as well for real
> time chat.
>
> tl;dr my suggestions:
> 1. split docs patch
> 2. less words, rephrase for brevity
> 3. welcome to open source team collaboration :)

I appreciate that offer. I will hop on to IRC and off-list email for a 
bit, and see if I can find a way forward. Maybe I won't find it.

In the meantime, I don't expect that I will get the cooperation needed 
to fix this patch. I think it has been defeated.

But I do appreciate the helpful explanation, and I do appreciate the 
welcome to the project. Thank you. Best regards,
        —Jim DeLaHunt

-- 
     --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