On 2020-08-21 03:28, Nicolas George wrote:
Jim DeLaHunt (12020-08-20):
Nicolas, do you remember this?
On 2020-05-01 03:01, Nicolas George wrote [1]:
Carl Eugen Hoyos (12020-05-01):
-The desired output frame rate. The default is @code{25}.
+The output frame rate, in frames per second. May be an integer, real, or
+rational number, or an abbreviation. The default is @code{25}.
I seriously wonder who really profits from this change but it may be ok.
I would argue: lazy beginners.
…
Now that you mention, it, I remember. The fact that I did not find it
while searching my archives is caused by a misconfiguration of Git in
your end:
From: list+ffmpeg-...@jdlh.com
From: Jim DeLaHunt <list+ffmpeg-...@jdlh.com>
I will observe that you didn't actually review the documentation patch which
led to that thread. You just latched on to Carl Eugen's "who really profits"
comment, and complained. That patch was not my only experience submitting a
documentation improvement and having the FFmpeg project's antibodies reject
it. But it did vividly clarify for me what the project values and what it
does not.
I stand by my assessment, and reading a little more of your proposal and
your attitude in this discussion confirms that you have the wrong
attitude to both submitting patches and writing documentation.
…[snip]…
Nicholas, I do not intend to relitigate a review of my patch rewriting
the "fps" filter documentation[1] on the ffmpeg-user list. But also, I
think your message gives a false impression of what blocked that patch,
and I don't want to leave that false impression unchallenged.
There are many components, filters and others, that take a frame rate
option.…The proper way to document this option is to explain the syntax of a
frame rate at a central place, along with the syntax of a video size,
the syntax of a duration, etc., and to have a link to there in the
documentation of each option using that syntax.…
I actually agree 80% with you about how to document common options like
frame rate or PTS, in an ideal situation. They should be well documented
in a central location. Individual filter docs should link to the common
documentation. We might have minor differences of opinion about whether
to briefly spell out acronyms in the filter doc as part of the link. We
could come to some compromise on that. I will observe that present
FFmpeg documentation is not an idea situation. There is nothing to link
to for most of the terms in the "fps" filter doc (e.g. PTS). You
suggested adding all those other pieces: glossary, completing frame
rate, etc. That grows the scope of the patch, and is against the
development policy, "Do not commit unrelated changes together" [2]. But
we could come to a compromise about that also.
What blocked the "fps" filter doc patch boiled down to two substantive
objections[3]: 1. objection to a 6-times difference in completeness and
length. 2. objection to places where new doc claimed different
functionality than old doc. My claim that old doc was wrong about what
the code did, and new doc was correct. A few developers raised objection
#1. One developer reviewed the doc patch and raised objection #2. As far
as I know, neither that developer nor anyone else read the `vf_fps.c`
code[4] to determine whether the old doc or the new doc was correct.
And, no other developer cared to give the patch a substantive review, or
offer a different ruling on objections #1 and #2.
And this is where we come to your approach to submitting patches: you
were told, in a very succinct way, that you were wrong. You were
expected to understand how, but you were welcome to ask clarification. I
would have explained what I just explained, and pointed that the
documentation for the syntax of a frame rate already exists:
http://ffmpeg.org/ffmpeg-all.html#Video-rate
I believe this summary misrepresents the objections that blocked the
patch. The obstacle was not linking to #Video-rate. It was the patch's
completeness, and correction of mistaken descriptions[3] (or excessive
length, and misreading the vf_fps.c, for those who disagree with me).
The lack of other developers giving a review, and lack of feedback
saying "it would be OK with these corrections", gave me no confidence of
clearing the objections.
Now, the ffmpeg-user list is not the place to discuss patches. If there
is a developer who has become interested in that patch, let me know, and
I'll take this back to ffmpeg-devel.
… But instead, you attacked.…
I disagree with your word "attack". I would say I respectfully pushed
back. And I did not push back against feedback on the merits of the
patch. I pushed back[5] against your condescending label of the
documentation audience as "lazy beginners"[6].
I still think the documentation should serve the needs of FFmpeg users
who are not digital video experts, and who haven't read the FFmpeg
documentation from end to end. And you used the word "lazy" again just
now. I guess we still disagree about who the FFmpeg documentation is
for. That disagreement is indeed a reasonable subject for the
ffmpeg-user list.
And by the way,
…The fact that I did not find it while searching my archives is
caused by a misconfiguration of Git in your end:
… From: Jim DeLaHunt<list+ffmpeg-...@jdlh.com>
I take "misconfiguration" as a casual insult, which is unnecessary,
unhelpful for collaboration, and does not live up to the "Be friendly
and respectful" rule of the Code of Conduct. It is also mistaken: I
intentionally subscribe a different email address to ffmpeg-devel than
to ffmpeg-user, and intentionally use the ffmpeg-devel address on my
patches. So could you please avoid such casual insults? We have so many
more substantive things to disagree on.
—Jim DeLaHunt, software engineer, Vancouver, Canada
[1] http://ffmpeg.org/pipermail/ffmpeg-devel/2020-May/261811.html
[2] http://ffmpeg.org/developer.html#Patches_002fCommitting
[3] http://ffmpeg.org/pipermail/ffmpeg-devel/2020-May/261983.html
[4]
https://github.com/FFmpeg/FFmpeg/blob/1128aa875367f66ac11adc30364d5652919a2591/libavfilter/vf_fps.c
[5] http://ffmpeg.org/pipermail/ffmpeg-devel/2020-May/261986.html
[6] http://ffmpeg.org/pipermail/ffmpeg-devel/2020-May/261821.html
_______________________________________________
ffmpeg-user mailing list
ffmpeg-user@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-user
To unsubscribe, visit link above, or email
ffmpeg-user-requ...@ffmpeg.org with subject "unsubscribe".
