Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-12-04 Thread Lou Logan 
On Mon, Dec 4, 2017, at 12:54 PM, Lou Logan wrote:
> Back in ye olde cvs days it made more sense, but not anymore with git.
> Legacy and tradition alone shouldn't be a factor.

...and just for comparison:

ffmpeg-devel: 1800 subscribers
ffmpeg-cvslog: 190 subscribers
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-12-04 Thread Lou Logan 
On Mon, Dec 4, 2017, at 03:45 AM, Carl Eugen Hoyos wrote:
>
> Committers have to be subscribed to -cvslog.

Back in ye olde cvs days it made more sense, but not anymore with git.
Legacy and tradition alone shouldn't be a factor.
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-12-04 Thread wm4 
On Mon, 4 Dec 2017 14:09:40 +
Derek Buitenhuis  wrote:

> On 12/4/2017 12:45 PM, Carl Eugen Hoyos wrote:
> > Committers have to be subscribed to -cvslog.  
> 
> "Have to"? I certainly am not, and neither are many. Are you going to
> kick all of them out and revoke their push access? I think not.

I've been subscribed to it once (when I heard that it was expected),
but it had absolutely no value. If anyone actually posted there, they
always cross posted to ffmpeg-devel too. So I unsubscribed.

The only use of that list is if someone lacks better git update
notifications.
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-12-04 Thread Hendrik Leppkes 
On Mon, Dec 4, 2017 at 3:09 PM, Derek Buitenhuis
 wrote:
> On 12/4/2017 12:45 PM, Carl Eugen Hoyos wrote:
>> Committers have to be subscribed to -cvslog.
>
> "Have to"? I certainly am not, and neither are many. Are you going to
> kick all of them out and revoke their push access? I think not.
>

I agree, I have never been subscribed to that list either, and I don't
see any reason why I should.
If I want to review changes to Git, I use gitweb, mail is a bad format for that.

- Hendrik
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-12-04 Thread Derek Buitenhuis 
On 12/4/2017 12:45 PM, Carl Eugen Hoyos wrote:
> Committers have to be subscribed to -cvslog.

"Have to"? I certainly am not, and neither are many. Are you going to
kick all of them out and revoke their push access? I think not.

It's clear that the majority here do not agree with you on this issue,
in my opinion. Either put it to a vote or stop the needless, and endless
bikshedding on this simple documentation patch.

- Derek
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-12-04 Thread Carl Eugen Hoyos 
2017-12-03 6:37 GMT+01:00 Timothy Gu :
> On Mon, Nov 27, 2017 at 3:03 PM Carl Eugen Hoyos  wrote:
>> If you believe that it is unclear that there is a difference between an
>> occasional contributor (who most likely would not read -devel nor
>> -cvslog) and a committer (who is supposed to read -cvslog), then
>> maybe a patch is useful.
>>
>> I believe the difference could be considered common sense.
>
> Thank you for expressing your opinion regarding this. However, I
> cannot say I agree with this evaluation. As I read this paragraph
> as it currently stands, the tone makes it sound like subscription
> is mandatory ("we expect you").

My suspicion is that at an earlier change of the documentation, this
paragraph was moved making understanding it more difficult.

But this does not justify making another bad / wrong change.

Committers have to be subscribed to -cvslog.

Carl Eugen
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-12-02 Thread Timothy Gu 
Hi all,

On Sun, Nov 26, 2017 at 12:32 AM Jim DeLaHunt 
wrote:
> 1. In doc/developer.texi, eliminate the single chapter,
> and promote each section underneath to chapter, and
> each subsection to section. Thus content and relative
> structure remains the same, but the overall structure is
> simpler.  Anchors within the page remain the same.

I have manually applied this part of the patch, which is noncontroversial
and a
strict improvement to what we have right now.

> 2. 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.

The wording in
https://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221199.html sounds
good
to me.

> 3. 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.

> +from all sources. Subscribing to this list is not mandatory, if
> +all you want to do is submit a patch here and there.

I would remove the "if" part, leaving only the "not mandatory" message.
Over my
tenure as FFmpeg developer I have never subscribed to -cvslog, since there
are
other ways of following FFmpeg development these days (subscribing to the
FFmpeg repo on GitHub, for example). I am glad to see this sentiment echoed
by
Ronald and Rostislav.

However, other than this technicality, I am in favor of the spirit of this
part
of the patch.



Carl,

On Mon, Nov 27, 2017 at 3:03 PM Carl Eugen Hoyos  wrote:
> If you believe that it is unclear that there is a difference between an
> occasional contributor (who most likely would not read -devel nor
> -cvslog) and a committer (who is supposed to read -cvslog), then
> maybe a patch is useful.
>
> I believe the difference could be considered common sense.

Thank you for expressing your opinion regarding this. However, I cannot say
I
agree with this evaluation. As I read this paragraph as it currently stands,
the tone makes it sound like subscription is mandatory ("we expect you"). I
believe the proposed modification is a significant improvement over the
existing text.

Additionally, from what I'm reading, it seems as if you believe subscribing
to
-cvslog is even more important than subscribing to -devel, which is false,
plain and simple.

Without further opinions from you, I will be applying this part of the
patch in
due time, by virtue of being the maintainer of Documentation.

Thanks to you all,

Timothy
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-11-26 Thread Paul B Mahol 
On 11/26/17, Jim DeLaHunt  wrote:
> On 2017-11-26 04:38, Paul B Mahol wrote:
>> On 11/26/17, Nicolas George  wrote:
>>> Paul B Mahol (2017-11-26):
 Your opinions are irrelevant.
>>> # Be friendly and respectful towards others and third parties.
>>> # Treat others the way you yourself want to be treated.
>>>
>>> Please stop trampling the code of conduct.
>> Please stop being extremly rude and ignorant of other people's work.
> Paul, I am new on this list, but it seems to me that the only one being
> rude in this thread is you. I certainly hope this behaviour is not how
> you interpret "Be friendly and respectful towards others and third parties".

 I'm not first who started it, and since you are new to list you missed
 lots of flame wars...
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-11-26 Thread Jim DeLaHunt 

On 2017-11-26 04:38, Paul B Mahol wrote:

On 11/26/17, Nicolas George  wrote:

Paul B Mahol (2017-11-26):

Your opinions are irrelevant.

# Be friendly and respectful towards others and third parties.
# Treat others the way you yourself want to be treated.

Please stop trampling the code of conduct.

Please stop being extremly rude and ignorant of other people's work.
Paul, I am new on this list, but it seems to me that the only one being 
rude in this thread is you. I certainly hope this behaviour is not how 
you interpret "Be friendly and respectful towards others and third parties".


--
--Jim DeLaHunt, j...@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

___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-11-26 Thread Paul B Mahol 
On 11/26/17, Nicolas George  wrote:
> Paul B Mahol (2017-11-26):
>> Your opinions are irrelevant.
>
> # Be friendly and respectful towards others and third parties.
> # Treat others the way you yourself want to be treated.
>
> Please stop trampling the code of conduct.

Please stop being extremly rude and ignorant of other people's work.
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-11-26 Thread Nicolas George 
Paul B Mahol (2017-11-26):
> Your opinions are irrelevant.

# Be friendly and respectful towards others and third parties.
# Treat others the way you yourself want to be treated.

Please stop trampling the code of conduct.

-- 
  Nicolas George


signature.asc
Description: Digital signature
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-11-26 Thread Paul B Mahol 
On 11/26/17, Carl Eugen Hoyos  wrote:
> 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt :
>
>> -@subsection Documentation/Other
>> +@section Documentation/Other
>> +@subheading Subscribe to the ffmpeg-devel mailing list.
>> +It is important to be subscribed to the
>
> Of course it is important but I would much, much prefer
> if people send their patches without being subscribed
> than not sending their patches because it is implied
> that they cannot send patches if they don't want to
> subscribe.
>
>> +@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel,
>> ffmpeg-devel}
>> +mailing list, because any patch you contribute must be sent there
>
> 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.
>
>> +and reviewed by the other developers. They may have comments about your
>> +contribution. We expect you see those comments, and to improve your
>> contribution
>> +if requested.
>
> Yes.
>
> But if people are not interested in improving their contribution,
> I would still prefer the patches to be sent.
>
>> +Also, this list is where bugs and possible improvements or
>
> I believe this is misleading or even wrong.
>
>> +general questions regarding commits 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.
>> +
>>  @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, if
>> +all you want to do is submit a patch here and there.
>
> I am (still) against this change.
>
> Sorry, Carl Eugen

Your opinions are irrelevant.
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Re: [FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-11-26 Thread Carl Eugen Hoyos 
2017-11-26 9:31 GMT+01:00 Jim DeLaHunt :

> -@subsection Documentation/Other
> +@section Documentation/Other
> +@subheading Subscribe to the ffmpeg-devel mailing list.
> +It is important to be subscribed to the

Of course it is important but I would much, much prefer
if people send their patches without being subscribed
than not sending their patches because it is implied
that they cannot send patches if they don't want to
subscribe.

> +@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel}
> +mailing list, because any patch you contribute must be sent there

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.

> +and reviewed by the other developers. They may have comments about your
> +contribution. We expect you see those comments, and to improve your 
> contribution
> +if requested.

Yes.

But if people are not interested in improving their contribution,
I would still prefer the patches to be sent.

> +Also, this list is where bugs and possible improvements or

I believe this is misleading or even wrong.

> +general questions regarding commits 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.
> +
>  @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, if
> +all you want to do is submit a patch here and there.

I am (still) against this change.

Sorry, Carl Eugen
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

[FFmpeg-devel] [PATCH] Refactor Developer Docs, update dev list section (v2)

2017-11-26 Thread Jim DeLaHunt 
Previously, the Developer Documentation
 contained a single chapter,
1. Developer Guide, with all content under that single
chapter. Thus the document structure was one level deeper
and more complicated than it needed to be.  It differed
from similar documents such as /faq.html, which have
multiple chapters.

Also, 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
for all contributors.

1. In doc/developer.texi, eliminate the single chapter,
and promote each section underneath to chapter, and
each subsection to section. Thus content and relative
structure remains the same, but the overall structure is
simpler.  Anchors within the page remain the same.

2. 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.

3. 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.

See ffmpeg-devel thread about the first version of this patch, at
.
I believe all comments to date in that thread are addressed
with this patch.

I believe there were no links to the eliminated "Developer
Documentation" chapter, based on a search of the source
code.

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 
---
 doc/developer.texi | 74 +++---
 1 file changed, 43 insertions(+), 31 deletions(-)

diff --git a/doc/developer.texi b/doc/developer.texi
index a7b4f1d737..bdcce015d3 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -10,9 +10,7 @@
 
 @contents
 
-@chapter Developers Guide
-
-@section Notes for external developers
+@chapter Notes for external developers
 
 This document is mostly useful for internal FFmpeg developers.
 External developers who need to use the API in their application should
@@ -30,7 +28,7 @@ For more detailed legal information about the use of FFmpeg in
 external programs read the @file{LICENSE} file in the source tree and
 consult @url{https://ffmpeg.org/legal.html}.
 
-@section Contributing
+@chapter Contributing
 
 There are 3 ways by which code gets into FFmpeg.
 @itemize @bullet
@@ -47,9 +45,9 @@ The developer making the commit and the author are 
responsible for their changes
 and should try to fix issues their commit causes.
 
 @anchor{Coding Rules}
-@section Coding Rules
+@chapter Coding Rules
 
-@subsection Code formatting conventions
+@section Code formatting conventions
 
 There are the following guidelines regarding the indentation in files:
 
@@ -74,7 +72,7 @@ The presentation is one inspired by 'indent -i4 -kr -nut'.
 The main priority in FFmpeg is simplicity and small code size in order to
 minimize the bug count.
 
-@subsection Comments
+@section Comments
 Use the JavaDoc/Doxygen  format (see examples below) so that code documentation
 can be generated automatically. All nontrivial functions should have a comment
 above them explaining what the function does, even if it is just one sentence.
@@ -114,7 +112,7 @@ int myfunc(int my_parameter)
 ...
 @end example
 
-@subsection C language features
+@section C language features
 
 FFmpeg is programmed in the ISO C90 language with a few additional
 features from ISO C99, namely:
@@ -160,7 +158,7 @@ mixing statements and declarations;
 GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
 @end itemize
 
-@subsection Naming conventions
+@section Naming conventions
 All names should be composed with underscores (_), not CamelCase. For example,
 @samp{avfilter_get_video_buffer} is an acceptable function name and
 @samp{AVFilterGetVideo} is not. The exception from this are type names, like
@@ -204,7 +202,7 @@ letter as they are reserved by the C standard. Names 
starting with @code{_}
 are reserved at the file level and may not be used for externally visible
 symbols. If in doubt, just avoid names starting with @code{_} altogether.
 
-@subsection Miscellaneous conventions
+@section Miscellaneous conventions
 
 @itemize @bullet
 @item
@@ -216,7 +214,7 @@ Casts should be used only when necessary. Unneeded 
parentheses
 should also be avoided if they don't make the code easier to understand.
 @end itemize
 
-@subsection Editor configuration
+@section Editor configuration
 In order to configure Vim to follow FFmpeg formatting conventions, paste
 the following snippet into your @file{.vimrc}:
 @example
@@