doc/developer: revise mailing list section
authorJim DeLaHunt <from.ffmpeg-dev@jdlh.com>
Mon, 4 Dec 2017 07:09:02 +0000 (23:09 -0800)
committerTimothy Gu <timothygu99@gmail.com>
Tue, 5 Dec 2017 10:06:10 +0000 (02:06 -0800)
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>
Signed-off-by: Timothy Gu <timothygu99@gmail.com>
doc/developer.texi

index 89124a2..66b2463 100644 (file)
@@ -380,12 +380,28 @@ 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
+anyway.
 
 @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