[FFmpeg-devel] Policy on ffmpeg-devel list and contributions [was: Re: [PATCH] Refactor Developer Docs, update dev list section (v2)]
from.ffmpeg-dev at jdlh.com
Wed Nov 29 23:06:06 EET 2017
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
> 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, 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
More information about the ffmpeg-devel