[FFmpeg-devel] Add doc on ffmpeg-devel, update on -cvslog list (v3)

Submitted by Jim DeLaHunt on Dec. 4, 2017, 7:09 a.m.

Details

Message ID 20171204070902.54949-1-from.ffmpeg-dev@jdlh.com
State Accepted
Headers show

Commit Message

Jim DeLaHunt Dec. 4, 2017, 7:09 a.m.
The Developer Documentation had instructions to
subscribe to the ffmpeg-cvslog email list. But that is
no longer accurate. For the purposes in this section --
review of patches, discussion of development issues --
ffmpeg_devel is the appropriate email list. Some developers
may want to monitor ffmpeg-cvslog, but it is not mandatory.

This is v3 of this doc, based on discussion in thread
<https://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/220528.html>
and in response to docs Maintainer comments in
<https://ffmpeg.org/pipermail/ffmpeg-devel/2017-December/221596.html>.

1. In doc/developer.texi, add a new section about
ffmpeg-devel, based on existing text from ffmpeg-cvslog
section regarding discussion of patches and of
development issues. Reflect wording from discussion at
<https://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221199.html>
but with copy-editing to make wording more concise.

2. In doc/developer.texi, rewrite the ffmpeg-cvslog section
to match the current usage of ffmpeg-cvslog. Some
developers choose to follow this list, but it is not
mandatory.

There are a lot of improvements possible to the
Developer Documentation page, beyond this refactoring.
However, making those improvements is a much bigger
and more difficult task.  This change is "low hanging
fruit".

Signed-off-by: Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>
---
 doc/developer.texi | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

Comments

Carl Eugen Hoyos Dec. 4, 2017, 12:42 p.m.
2017-12-04 8:09 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>:

>  @section Documentation/Other
> +@subheading Subscribe to the ffmpeg-devel mailing list.
> +It is important to be subscribed to the
> +@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel}
> +mailing list. Almost any non-trivial patch is to be sent there
> +for review. Other developers may have comments about your contribution.
> +We expect you see those comments, and to improve it if requested.

> +(N.B. Experienced committers have other channels,
> +and may sometimes skip review for trivial fixes.)

This is exactly why committers have to read ffmpeg-cvslog,
this has nothing to do with ffmpeg-devel.

The patch is not ok, Carl Eugen
Paul B Mahol Dec. 4, 2017, 1 p.m.
On 12/4/17, Carl Eugen Hoyos <ceffmpeg@gmail.com> wrote:
> 2017-12-04 8:09 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>:
>
>>  @section Documentation/Other
>> +@subheading Subscribe to the ffmpeg-devel mailing list.
>> +It is important to be subscribed to the
>> +@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel,
>> ffmpeg-devel}
>> +mailing list. Almost any non-trivial patch is to be sent there
>> +for review. Other developers may have comments about your contribution.
>> +We expect you see those comments, and to improve it if requested.
>
>> +(N.B. Experienced committers have other channels,
>> +and may sometimes skip review for trivial fixes.)
>
> This is exactly why committers have to read ffmpeg-cvslog,
> this has nothing to do with ffmpeg-devel.
>
> The patch is not ok, Carl Eugen
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel@ffmpeg.org
> http://ffmpeg.org/mailman/listinfo/ffmpeg-devel
>

Lets start vote on this.
Timothy Gu Dec. 5, 2017, 10:07 a.m.
Hi,

On Mon, Dec 4, 2017 at 4:43 AM Carl Eugen Hoyos <ceffmpeg@gmail.com> wrote:

> The patch is not ok, Carl Eugen


It is clear that you have no respect for community consensus.

9 for removal of mandatory status (10 counting myself):
TR: http://lists.ffmpeg.org/pipermail/ffmpeg-devel/2017-November/220272.html

PBM:
http://lists.ffmpeg.org/pipermail/ffmpeg-devel/2017-November/220441.html
RB: http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221152.html
RP: http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221155.html
CB: http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221204.html
DB: http://ffmpeg.org/pipermail/ffmpeg-devel/2017-December/221695.html
HL: http://ffmpeg.org/pipermail/ffmpeg-devel/2017-December/221697.html
wm4: http://ffmpeg.org/pipermail/ffmpeg-devel/2017-December/221727.html
LL: http://ffmpeg.org/pipermail/ffmpeg-devel/2017-December/221729.html

2 neutral:
MT: http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221174.html
(personally
uses -cvslog but "try to reply to -devel")
MN: http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221387.html
(encourage
subscription rather than require it)

1 against:
You.

As the Documentation maintainer, this patch LGTM. With community consensus,
this is thusly applied.

Thanks to you all.

Timothy
Jim DeLaHunt Dec. 5, 2017, 7:02 p.m.
On 2017-12-05 02:07, Timothy Gu wrote:

> Hi,
>
> [...]
>
> As the Documentation maintainer, this patch LGTM. With community consensus,
> this is thusly applied.
>
> Thanks to you all.
>
> Timothy
>
Thank you, Timothy, and everyone who participated in this discussion.

The end product is a small change to the documentation, but I think it 
is a high-impact fix for new contributors who are trying to figure out 
how the ffmpeg project works and how they can plug in to the process.

As a bonus, it was also, for this new contributor, a real education in 
how the project works.

Now if you'll excuse me, I'm going to take this wonderful tool and 
convert some audio and video content from one format to another.

Patch hide | download patch | download mbox

diff --git a/doc/developer.texi b/doc/developer.texi
index 89124a295c..65f2630e69 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -380,12 +380,30 @@  always check values read from some untrusted source before using them
 as array index or other risky things.
 
 @section Documentation/Other
+@subheading Subscribe to the ffmpeg-devel mailing list.
+It is important to be subscribed to the
+@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel}
+mailing list. Almost any non-trivial patch is to be sent there
+for review. Other developers may have comments about your contribution.
+We expect you see those comments, and to improve it if requested.
+(N.B. Experienced committers have other channels,
+and may sometimes skip review for trivial fixes.)
+Also, discussion here about bug fixes and ffmpeg improvements by
+other developers may be helpful information for you.
+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.
 
 @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
+@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.
 
 @subheading Keep the documentation up to date.
 Update the documentation if you change behavior or add features. If you are