[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-27 15:00, Carl Eugen Hoyos wrote:
> 2017-11-26 22:44 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev at jdlh.com>:
>> So, how realistic is this concern about non-subscribers sending 
>> patches to
>> ffmpeg-devel?  Does it actually happen?
> This is very realistic afair.
OK, and Lou Logan corroborates Carl Eugen:
On 2017-11-27 15:19, Lou Logan wrote:
> A very rough guess is that there are usually at least several
> patches from unsubscribed users a week (in fact there was one in the
> queue minutes ago).

So I accept that welcoming non-subscribers sending patches to 
ffmpeg-devel is a real concern. I was skeptical, but I was wrong.

So I will revise the patch to add this paragraph (indented below):

>> That said, would your concern be addressed if I were to add this sentence:
>>
>>     However, it is more important to the project that we receive your
>>     patch than that you be subscribed to the ffmpeg-devel list. If you
>>     have a patch, and don't want to subscribe and discuss the patch,
>>     then please do send it to the list.
On 2017-11-27 15:00, Carl Eugen Hoyos wrote:
> Sure but I was hoping that his is common sense unless explicitely denied.

Carl Eugen, you have a tremendous dedication to the FFmpeg project and 
are deeply familiar with patch handling and the code base. I would argue 
that this makes you a weaker judge of "common sense". Your sense of what 
is common might be biased by how much you know.

Someone who knows much less might be a better judge of what is "common 
sense" to the new contributor to FFmpeg. And I am here to tell you that 
the paragraphs in this patch are not at all "common sense". New 
contributors need to them said out loud.

Also, someone once observed that common sense is not very common. :-)


On 2017-11-27 15:00, Carl Eugen Hoyos wrote:
> 2017-11-26 22:44 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev at jdlh.com>:
>> On 2017-11-26 03:42, Carl Eugen Hoyos wrote:
>>> No:
>>> I believe it is very important that trivial patches are not sent
>>> to the development mailing list - its volume is already so big
>>> that some patches are sadly (!) forgotten.

[...]

> Bug fixes and patches that implement improvements are discussed on
> ffmpeg-devel and therefore, in this specific cases, bugs and possible
> improvement are discussed. Bugs without fixes and improvements
> without patches should not be discussed on ffmpeg-devel.
OK, would you accept this wording for a subheading on ffmpeg-devel?

-----
It is important to be subscribed to the
@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel}
mailing list, because any non-trivial patch you contribute must be sent 
there
and reviewed by other developers. They may have comments about your
contribution. We expect you see those comments, and to improve your 
contribution
if requested. (N.B. Experienced committers may sometimes skip review for 
trivial fixes.)
Also, this list is where bug fixes and ffmpeg improvements from other 
developers
are discussed. That may be helpful information as you write your 
contribution. Finally, by being a list
subscriber your contribution will be posted immediately to the list,
without the moderation hold which messages from non-subscribers experience.

However, it is more important to the project that we receive your
patch than that you be subscribed to the ffmpeg-devel list. If you
have a patch, and don't want to subscribe and discuss the patch,
then please do send it to the list.
-----

Carl Eugen, do you accept this wording for a description of ffmpeg-devel 
on ffmpeg.org/developer.html?

> I apparently failed so far to understand the goal of your patch. 

I answered this in a private email, but the list saw your comment, and 
I'd like it to see my response. Forgive the repetition.

I made this patch because I want to fix bugs in 
ffmpeg.org/developer.html . The website directs new contributors to this 
page, where they are supposed to find out how the project wants them to 
contribute. I am a new contributor, I have just gone through this 
process. I had basic questions which the web page did not answer, or 
answered unhelpfully.

There are shallow, easy-to-fix bugs in the content of this web page. It 
does describe the ffmpeg-cvslog list, using words which are inaccurate 
when compared to the discussion now on the -devel list about how 
committers and contributers use or ignore -cvslog. The page does not 
describe the ffmpeg-devel list, but it should. References to -devel are 
not the same as a description of -devel.

Also, there are editorial problems with the web page. The structure 
consists of one @chapter and multiple @sections and @subsections. The 
structure should be multiple @chapters, so the stub @chapter should be 
eliminated and every @section and @subsection should be promoted one level.

There is a saying in free software, "scratch your own itch". My "itch" 
is that I attempted to make a minor patch to the FFmpeg documentation (2 
new FAQs), and I found it way more difficult than it should have been, 
due to poor documentation on ffmpeg.org/developer.html and elsewhere. I 
am trying to contribute patches to fix the most severe, easiest to fix 
bugs in the docs.

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.

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