| Message ID | 20171126083111.91454-1-from.ffmpeg-dev@jdlh.com |
|---|---|
| State | Superseded |
| Headers | show |
2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > -@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
On 11/26/17, Carl Eugen Hoyos <ceffmpeg@gmail.com> wrote: > 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > >> -@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.
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.
On 11/26/17, Nicolas George <george@nsup.org> 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.
On 2017-11-26 04:38, Paul B Mahol wrote: > On 11/26/17, Nicolas George <george@nsup.org> 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".
On 11/26/17, Jim DeLaHunt <from.ffmpeg-dev@jdlh.com> wrote: > On 2017-11-26 04:38, Paul B Mahol wrote: >> On 11/26/17, Nicolas George <george@nsup.org> 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...
On 2017-11-26 03:42, Carl Eugen Hoyos wrote: > 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: >> -@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.... > But if people are not interested in improving their contribution, > I would still prefer the patches to be sent. So, how realistic is this concern about non-subscribers sending patches to ffmpeg-devel? Does it actually happen? Can you point to, say, three patches in the last six months which were sent by non-subscribers to ffmpeg-devel and were applied to the code base? Given how so many of the patches submitted by subscribers who know the unwritten rules are subjected to veto and revision, I would be surprised if many non-subscribers who are ignorant of the unwritten rules would produce something satisfactory. 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. (I am tempted to add a phrase like, "If you want to send your patch to ffmpeg-devel without discussion, as if abandoning your baby on the steps of the orphanage, please do; one of the kind caregivers on the list may pick it up and find it a good home." But this is probably too snarky to be appropriate.) >> +@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. Tell me more about the procedure for trivial patches. I have not seen this documented, and I don't know about it. Does this apply to occasional contributors, or only to trusted experienced ffmpeg project members with commit privileges to the repository? The proposed text does not distinguish between occasional contributors and experienced project members. Maybe it should. I believe that the main audience of `doc/developer.html` is new and occasional contributors, because the experienced members will have internalised all the undocumented norms, and won't be referring to this page. What revised wording do you propose for the above phrase "any patch you contribute must be sent there"? >> +Also, this list is where bugs and possible improvements or > I believe this is misleading or even wrong. Oh? I took this wording from the existing <http://ffmpeg.org/developer.html#Documentation_002fOther> regarding the ffmpeg-cvslog list: "Bugs and possible improvements or general questions regarding commits are discussed there." What is misleading or wrong about this wording? What is your objection? What alternate wording would you propose for this sentence, which describes why contributors should pay attention to the content of ffmpeg-devel? >> +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. >> + [...] I think what is important about this new section is that it describes the policy and importance of the ffmpeg-devel list. It's interesting that the project had not put this into words in the current documentation. I'm trying to do that. Carl Eugen, you are quick to object to what you don't like about proposed wording. I think it's especially important that you suggest wording that does capture what you do support. You obviously care. Best regards, —Jim DeLaHunt
On 2017-11-26 03:42, Carl Eugen Hoyos wrote: > 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > [...] >> + >> @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. OK, what specifically are you against? More important, what are you in favour of? It's difficult for me to read your mind via email. Would you please read the existing section, "Subscribe to the ffmpeg-cvslog mailing list."[1], and give wording which to you describes accurately the current reality? I'll observe that we have already heard other opinions: * Paul[2]: "Not at all. To be a contributor, it is not needed to subscribe to [ffmpeg-cvslog] list." * Timo[3]: "Usually if a discussion comes up the mail from cvslog is replied to on [ffmpeg-devel] list, so no actual discussion happens on the automatic cvslog list." I don't have strong feelings on the policy for the -cvslog list, except that the current documentation is clearly inaccurate in describing the current reality. That is obvious even on a short exposure to the community. "Bugs and possible improvements or general questions regarding commits" are /not/ discussed "there", on ffmpeg-cvslog. The statement "We expect you to react if problems with your code are uncovered." is correct, but more accurately describes behaviour on ffmpeg-devel, not ffmpeg-cvslog. > Sorry, Carl Eugen It's great that you care. What wording do you support? Best regards, —Jim DeLaHunt [1] <http://ffmpeg.org/developer.html#Documentation_002fOther> [2] <http://lists.ffmpeg.org/pipermail/ffmpeg-devel/2017-November/220441.html> [3] <http://lists.ffmpeg.org/pipermail/ffmpeg-devel/2017-November/220272.html>
2017-11-26 22:44 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > On 2017-11-26 03:42, Carl Eugen Hoyos wrote: >> >> 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: >>> >>> -@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.... >> But if people are not interested in improving their contribution, >> I would still prefer the patches to be sent. > > > So, how realistic is this concern about non-subscribers sending patches to > ffmpeg-devel? Does it actually happen? This is very realistic afair. > Can you point to, say, three patches > in the last six months which were sent by non-subscribers to ffmpeg-devel No, the mail admins could (or explain that I am wrong.) > and were applied to the code base? I was under the impression the patches that were not applied would support my point. > Given how so many of the patches submitted by subscribers who know the > unwritten rules are subjected to veto and revision, I would be surprised if > many non-subscribers who are ignorant of the unwritten rules would produce > something satisfactory. > > 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. Sure but I was hoping that his is common sense unless explicitely denied. > > (I am tempted to add a phrase like, "If you want to send your patch to > ffmpeg-devel without discussion, as if abandoning your baby on the steps of > the orphanage, please do; one of the kind caregivers on the list may pick it > up and find it a good home." But this is probably too snarky to be > appropriate.) No objections;-) >>> +@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. > > Tell me more about the procedure for trivial patches. I have not seen this > documented, and I don't know about it. Does this apply to occasional > contributors, or only to trusted experienced ffmpeg project members with > commit privileges to the repository? There is a difference between contributors and committers and this may be the reason for our misunderstanding. > The proposed text does not distinguish between occasional contributors and > experienced project members. Maybe it should. I believe that the main > audience of `doc/developer.html` is new and occasional contributors, because > the experienced members will have internalised all the undocumented norms, > and won't be referring to this page. > > What revised wording do you propose for the above phrase "any patch you > contribute must be sent there"? > >>> +Also, this list is where bugs and possible improvements or >> >> I believe this is misleading or even wrong. > > Oh? I took this wording from the existing > <http://ffmpeg.org/developer.html#Documentation_002fOther> regarding the > ffmpeg-cvslog list: > "Bugs and possible improvements or general questions regarding commits are > discussed there." > What is misleading or wrong about this wording? What is your objection? 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. > What alternate wording would you propose for this sentence, which describes > why contributors should pay attention to the content of ffmpeg-devel? >>> >>> +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. >>> + > > > [...] > > I think what is important about this new section is that it describes the > policy and importance of the ffmpeg-devel list. It's interesting that the > project had not put this into words in the current documentation. I'm trying > to do that. Carl Eugen, you are quick to object to what you don't like > about proposed wording. I think it's especially important that you suggest > wording that does capture what you do support. You obviously care. I apparently failed so far to understand the goal of your patch. Carl Eugen
2017-11-26 22:57 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > On 2017-11-26 03:42, Carl Eugen Hoyos wrote: > >> 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: >> [...] >>> >>> + >>> @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. > > > OK, what specifically are you against? More important, what are you in > favour of? I have no issue with the current text. 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. Carl Eugen
Hi, On Mon, Nov 27, 2017 at 6:03 PM, Carl Eugen Hoyos <ceffmpeg@gmail.com> wrote: > 2017-11-26 22:57 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > > On 2017-11-26 03:42, Carl Eugen Hoyos wrote: > > > >> 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > >> [...] > >>> > >>> + > >>> @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. > > > > > > OK, what specifically are you against? More important, what are you in > > favour of? > > I have no issue with the current text. > > 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. FYI I'm a committer and I do not read -cvslog. Ronald
On 27 November 2017 at 23:05, Ronald S. Bultje <rsbultje@gmail.com> wrote: > Hi, > > On Mon, Nov 27, 2017 at 6:03 PM, Carl Eugen Hoyos <ceffmpeg@gmail.com> > wrote: > > > 2017-11-26 22:57 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > > > On 2017-11-26 03:42, Carl Eugen Hoyos wrote: > > > > > >> 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > > >> [...] > > >>> > > >>> + > > >>> @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. > > > > > > > > > OK, what specifically are you against? More important, what are you in > > > favour of? > > > > I have no issue with the current text. > > > > 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. > > > FYI I'm a committer and I do not read -cvslog. > > Ronald > _______________________________________________ > ffmpeg-devel mailing list > ffmpeg-devel@ffmpeg.org > http://ffmpeg.org/mailman/listinfo/ffmpeg-devel > Yeah, never touched cvslog either. If someone has comments to a commit which was pushed and doesn't use IRC then they should send an email to this ML. Or better yet use IRC.
On Mon, Nov 27, 2017, at 02:00 PM, Carl Eugen Hoyos wrote:
> No, the mail admins could (or explain that I am wrong.)
I would have to check each sender manually to see if they are in the
membership database. It would be possible to do this, but not very
practical. It would be easier for me to keep a running tally as I clear
the queue. 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).
Sometimes I'll set a frequent non-subscribed senders email address to be
automatically accepted (I purge this list occasionally).
On Mon, Nov 27, 2017, at 02:19 PM, 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). To clarify, in this case it was a reply, not a message.
On Mon, Nov 27, 2017, at 02:22 PM, Lou Logan wrote: > > To clarify, in this case it was a reply, not a message. Should have typed "patch" there, not message. Actually reading message before sending this time.
On Sun, Nov 26, 2017, at 12:57 PM, Jim DeLaHunt wrote: > I'll observe that we have already heard other opinions: > > * Paul[2]: "Not at all. To be a contributor, it is not needed to > subscribe to [ffmpeg-cvslog] list." > * Timo[3]: "Usually if a discussion comes up the mail from cvslog is > replied to on [ffmpeg-devel] list, so no actual discussion happens > on the automatic cvslog list." ffmpeg-cvslog should only be a log and not a place for discussion. ffmpeg-devel should be the only mailing list where development discussions occur. Discussing a commit that was not reviewed should also occur at ffmpeg-devel. Currently there is little discussion in ffmpeg-cvslog (excluding discussions also directed to ffmpeg-devel), and I'm not sure how many patch authors actually read or see ffmpeg-cvslog only replies. Having no conversation in ffmpeg-cvslog would mean fewer pending messages in the infiniqueue for me to regularly deal with. Developers, contributors, maintainers, and/or committers should not need to subscribe to ffmpeg-cvslog to participate.
On 28/11/17 00:12, Lou Logan wrote: > On Sun, Nov 26, 2017, at 12:57 PM, Jim DeLaHunt wrote: >> I'll observe that we have already heard other opinions: >> >> * Paul[2]: "Not at all. To be a contributor, it is not needed to >> subscribe to [ffmpeg-cvslog] list." >> * Timo[3]: "Usually if a discussion comes up the mail from cvslog is >> replied to on [ffmpeg-devel] list, so no actual discussion happens >> on the automatic cvslog list." > > ffmpeg-cvslog should only be a log and not a place for discussion. > ffmpeg-devel should be the only mailing list where development > discussions occur. > > Discussing a commit that was not reviewed should also occur at > ffmpeg-devel. Currently there is little discussion in ffmpeg-cvslog > (excluding discussions also directed to ffmpeg-devel), and I'm not sure > how many patch authors actually read or see ffmpeg-cvslog only replies. > > Having no conversation in ffmpeg-cvslog would mean fewer pending > messages in the infiniqueue for me to regularly deal with. > > Developers, contributors, maintainers, and/or committers should not need > to subscribe to ffmpeg-cvslog to participate. I do use -cvslog, though generally I try to reply to -devel unless the conversation is already on -cvslog. If the intent is that -devel should always be used for replies, can you set a reply-to header on -cvslog pointing to -devel? - Mark
On Mon, Nov 27, 2017, at 03:20 PM, Mark Thompson wrote: > > If the intent is that -devel should always be used for replies, can you > set a reply-to header on -cvslog pointing to -devel? Done, thanks. Should have done that years ago. Didn't really think about the cvslog situation much until this discussion.
On 2017-11-27 15:00, Carl Eugen Hoyos wrote: > 2017-11-26 22:44 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@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@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
On 2017-11-27 15:03, Carl Eugen Hoyos wrote: > 2017-11-26 22:57 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: >> On 2017-11-26 03:42, Carl Eugen Hoyos wrote: >> >>> 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: >>> [...] >>>> + >>>> @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. >> >> OK, what specifically are you against? More important, what are you in >> favour of? > I have no issue with the current text. With respect, this section of ffmpeg.org/develop.html is not intended for an experienced, knowledgeable, deeply involved senior committer like you. So it doesn't really matter that you have no issue with the current text. What matters is whether a new developer, trying to learn how to contribute to ffmpeg, has an issue with the text. I can tell you that, as a new contributor reading this section with fresh eyes, I most certainly do have an issue with this text. It says things about how ffmpeg-cvslog are used that are flat out incorrect. Incorrect instructions waste time and cause confusion. > 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 will point out that two more people, Ronald[1] and Rostislav[2], do not behave in accordance with your belief that committers are supposed to read -cvslog. How sure are you that your belief reflects what the project actually expects? I proposed my wording above. What wording describing -cvslog, which corrects the incorrect information and reflects what your colleagues tell you about how they use the list, would you accept? > I believe the difference could be considered common sense. As I said in the thread about ffmpeg-devel[3], Your sense of what is common might be biased by how much you know. I am here to tell you that the paragraphs in this patch are not at all "common sense". New contributors need to have them said out loud. [1] http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221152.html [2] http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221155.html [3] http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/221199.html My goal here is to fix the bug in ffmpeg.org/developer.html, in the section which describes the -cvslog mailing list. I'll make the patch. Just tell me what wording will pass review.
On Mon, Nov 27, 2017 at 11:19:01PM +0000, Rostislav Pehlivanov wrote: > On 27 November 2017 at 23:05, Ronald S. Bultje <rsbultje@gmail.com> wrote: > > > Hi, > > > > On Mon, Nov 27, 2017 at 6:03 PM, Carl Eugen Hoyos <ceffmpeg@gmail.com> > > wrote: > > > > > 2017-11-26 22:57 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > > > > On 2017-11-26 03:42, Carl Eugen Hoyos wrote: > > > > > > > >> 2017-11-26 9:31 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@jdlh.com>: > > > >> [...] > > > >>> > > > >>> + > > > >>> @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. > > > > > > > > > > > > OK, what specifically are you against? More important, what are you in > > > > favour of? > > > > > > I have no issue with the current text. > > > > > > 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. > > > > > > FYI I'm a committer and I do not read -cvslog. > > > > Ronald > > _______________________________________________ > > ffmpeg-devel mailing list > > ffmpeg-devel@ffmpeg.org > > http://ffmpeg.org/mailman/listinfo/ffmpeg-devel > > > > Yeah, never touched cvslog either. > If someone has comments to a commit which was pushed and doesn't use IRC > then they should send an email to this ML. Or better yet use IRC. I'm subscribed to cvslog, and sometimes use it to comment on a commit. But when I do, I CC ffmpeg-devel anyway. I don't think cvslog subscription should be mandatory at all, even for core developers. It's fine to acknowledge its existence in the developers documentation though.
On Mon, 27 Nov 2017 23:46:30 -0800, Jim DeLaHunt <from.ffmpeg-dev@jdlh.com> wrote: > On 2017-11-27 15:00, Carl Eugen Hoyos wrote: > > 2017-11-26 22:44 GMT+01:00 Jim DeLaHunt <from.ffmpeg-dev@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. Let me also echo Lou and Carl's concerns. I am one of the other ML admins/mods and just 2 days ago approved submission to -devel a patch that was stuck in the mod queue because the author was not subscribed. i also auto-approved all future mails from that author. Patches without subscription happens often, couple times per month? The list traffic is immense (thousands of patches and discussions per month) and most people just want to drop a patch and run. Most smaller quick clear error fixing patches are accepted i would say, so this situation works. of course we are always looking for better practices, so we also have patchwork installed: https://patchwork.ffmpeg.org/project/ffmpeg/list/ unfortunately , we have also seen many distros and projects maintain their own ffmpeg patches, sometimes for years. never submitting them back to us. we are trying to improve this situation in any way that we can. i'm not trying to dogpile on you, just explaining the situation. > Also, someone once observed that common sense is not very common. :-) sure, but please remember the DOCS are already quite verbose, and brevity is the soul of wit. so if you can say more with less verbiage that would be great. > ----- > 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. > ----- i think your additions are well meaning, but the above is repetitive and can be made smaller. e.g. you use the words contribution, comments etc multiple times. i could attempt a rephrasing if you want? i would have done so in this mail but i am in a rush atm. Also please note that most ffmpeg developers and patch authors are from around the world , and english may not be their native language. >I am trying to contribute patches to fix the most severe, easiest to fix bugs in the docs. no problem. thanks for contributing. > 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. haha! well let me please explain to you what situation you have gotten yourself stuck into! :) the development docs that you want to patch are actually the ffmpeg project's written rules and policy that governs the whole shebang. so these are the rules that all devs must agree to within the project. sure, we bicker about the rules and not everyone follows every rule, and we have many unwritten rules that we also abide by. which also causes great strife sometimes when someone thinks a rule is official or not... look i didnt say it was a good system, it is what we have evolved into over the years. the point is that changes to this specific part of the documentation affects all devs, not just new contributors. so we are more interested to changes of this document. especially large changes all in one patch. what your v1 patch has unintentionally done is to change our long standing ffmpeg policy about patch submission and review. i know this was not your intention, but you have picked one of the core parts of the project to modify on your first attempt. :) hope this clears things up. feel free to ask me questions off list, or we can be found on irc.freenode.net #ffmpeg-devel as well for real time chat. tl;dr my suggestions: 1. split docs patch 2. less words, rephrase for brevity 3. welcome to open source team collaboration :) -compn
On 2017-11-29 06:53, Compn wrote: > [...] >> Also, someone once observed that common sense is not very common. :-) > sure, but please remember the DOCS are already quite verbose, and > brevity is the soul of wit. so if you can say more with less verbiage > that would be great. > [...] > Also please note that most ffmpeg developers and patch authors are from > around the world , and english may not be their native language. I'd be happy to work on better wording. I think the obstacle is more fundamental: there isn't agreement on what to say, or a consensus that it should be said at all. > >> 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. > haha! well let me please explain to you what situation you have gotten > yourself stuck into! :) > > the development docs that you want to patch are actually the ffmpeg > project's written rules and policy that governs the whole shebang. > > so these are the rules that all devs must agree to within the project. > sure, we bicker about the rules and not everyone follows every rule, > and we have many unwritten rules that we also abide by. which also > causes great strife sometimes when someone thinks a rule is official or > not... look i didnt say it was a good system, it is what we have > evolved into over the years. > > the point is that changes to this specific part of the documentation > affects all devs, not just new contributors. so we are more interested > to changes of this document. especially large changes all in one patch. > > what your v1 patch has unintentionally done is to change our long > standing ffmpeg policy about patch submission and review. i know this > was not your intention, but you have picked one of the core parts of the > project to modify on your first attempt. :) What this says to me is that the problems I observe in ffmpeg.org/developer.html go deeper than wording. There are architectural problems: this one page is supposed to serve as both the reference for the project's rules and as a tutorial for new contributors. The requirements for these two purposes differ. There are governance problems: rules exist for important parts of the project, but they are not in writing. Exhibit 1 is that the ffmpeg-devel list is central to this project, but there is presently zero description of it in this web page. Exhibit 2 is that the actual practice of the ffmpeg-cvslog list by several senior developers clearly differs from the description of it in this page. Exhibit 3 is the absence in this whole discussion of any reference to any rule-making process and its decisions, when the patch appears to intrude on policy matters. There are process problems: while I see lots of activity and appropriate process for improving the code of the ffmpeg executables, there is not similar activity or appropriate process for improving the documentation. I think this thread shows that the patch/review/reject or accept model used for code doesn't work so well for words. And then there are the writing problems: broken links, all content under one @chapter, checklists but no instructions to use the checklists, missing content, unclear content, and so on. I came here to try to fix the most severe, easiest to fix bugs in the docs. I am learning that nothing about ffmpeg.org/developer.html is going to be easy to fix. I am skeptical that splitting the docs patch will help. > hope this clears things up. feel free to ask me questions off list, or > we can be found on irc.freenode.net #ffmpeg-devel as well for real > time chat. > > tl;dr my suggestions: > 1. split docs patch > 2. less words, rephrase for brevity > 3. welcome to open source team collaboration :) I appreciate that offer. I will hop on to IRC and off-list email for a bit, and see if I can find a way forward. Maybe I won't find it. In the meantime, I don't expect that I will get the cooperation needed to fix this patch. I think it has been defeated. But I do appreciate the helpful explanation, and I do appreciate the welcome to the project. Thank you. Best regards, —Jim DeLaHunt
On Wed, Nov 29, 2017 at 01:06:06PM -0800, Jim DeLaHunt wrote: > On 2017-11-29 06:53, Compn wrote: > > >[...] > >>Also, someone once observed that common sense is not very common. :-) > >sure, but please remember the DOCS are already quite verbose, and > >brevity is the soul of wit. so if you can say more with less verbiage > >that would be great. > >[...] > >Also please note that most ffmpeg developers and patch authors are from > >around the world , and english may not be their native language. > I'd be happy to work on better wording. I think the obstacle is more > fundamental: there isn't agreement on what to say, or a consensus > that it should be said at all. > > > > >>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. > >haha! well let me please explain to you what situation you have gotten > >yourself stuck into! :) > > > >the development docs that you want to patch are actually the ffmpeg > >project's written rules and policy that governs the whole shebang. > > > >so these are the rules that all devs must agree to within the project. > >sure, we bicker about the rules and not everyone follows every rule, > >and we have many unwritten rules that we also abide by. which also > >causes great strife sometimes when someone thinks a rule is official or > >not... look i didnt say it was a good system, it is what we have > >evolved into over the years. > > > >the point is that changes to this specific part of the documentation > >affects all devs, not just new contributors. so we are more interested > >to changes of this document. especially large changes all in one patch. > > > >what your v1 patch has unintentionally done is to change our long > >standing ffmpeg policy about patch submission and review. i know this > >was not your intention, but you have picked one of the core parts of the > >project to modify on your first attempt. :) > > What this says to me is that the problems I observe in > ffmpeg.org/developer.html go deeper than wording. > > There are architectural problems: this one page is supposed to serve > as both the reference for the project's rules and as a tutorial for > new contributors. The requirements for these two purposes differ. > > There are governance problems: rules exist for important parts of > the project, but they are not in writing. Exhibit 1 is that the > ffmpeg-devel list is central to this project, but there is presently > zero description of it in this web page. Exhibit 2 is that the > actual practice of the ffmpeg-cvslog list by several senior > developers clearly differs from the description of it in this page. the cvslog list was in the past used in a way thats more similar to the text, practice changed, probably primarly as the tools changed from cvs to svn to git. git has a local, efficient and fast log where one can see all changes. the prior version control systems lacked that, this may have been te reason cvslog was more used and important. The text maybe doesn fully reflect this but it is wrong towards a arguably benefitial side. That is when more people look & review changes which are pushed, that is a good thing. [...]
Hi all, On Sun, Nov 26, 2017 at 12:32 AM Jim DeLaHunt <from.ffmpeg-dev@jdlh.com> 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 <ceffmpeg@gmail.com> 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
2017-12-03 6:37 GMT+01:00 Timothy Gu <timothygu99@gmail.com>: > On Mon, Nov 27, 2017 at 3:03 PM Carl Eugen Hoyos <ceffmpeg@gmail.com> 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
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
On Mon, Dec 4, 2017 at 3:09 PM, Derek Buitenhuis <derek.buitenhuis@gmail.com> 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
On Mon, 4 Dec 2017 14:09:40 +0000 Derek Buitenhuis <derek.buitenhuis@gmail.com> 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.
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.
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
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 @@ -249,9 +247,9 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}: (setq c-default-style "ffmpeg") @end lisp -@section Development Policy +@chapter Development Policy -@subsection Patches/Committing +@section Patches/Committing @subheading Licenses for patches must be compatible with FFmpeg. Contributions should be licensed under the @uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1}, @@ -350,7 +348,7 @@ time-frame (12h for build failures and security fixes, 3 days small changes, 1 week for big patches) then commit your patch if you think it is OK. Also note, the maintainer can simply ask for more time to review! -@subsection Code +@section Code @subheading API/ABI changes should be discussed before they are made. Do not change behavior of the programs (renaming options etc) or public API or ABI without first discussing it on the ffmpeg-devel mailing list. @@ -381,12 +379,26 @@ Never write to unallocated memory, never write over the end of arrays, always check values read from some untrusted source before using them as array index or other risky things. -@subsection Documentation/Other +@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, because any patch you contribute must be sent there +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. +Also, this list is where bugs and possible improvements or +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. @subheading Keep the documentation up to date. Update the documentation if you change behavior or add features. If you are @@ -406,7 +418,7 @@ finding a new maintainer and also don't forget to update the @file{MAINTAINERS} We think our rules are not too hard. If you have comments, contact us. -@section Code of conduct +@chapter Code of conduct Be friendly and respectful towards others and third parties. Treat others the way you yourself want to be treated. @@ -436,7 +448,7 @@ Finally, keep in mind the immortal words of Bill and Ted, "Be excellent to each other." @anchor{Submitting patches} -@section Submitting patches +@chapter Submitting patches First, read the @ref{Coding Rules} above if you did not yet, in particular the rules regarding patch submission. @@ -485,7 +497,7 @@ Give us a few days to react. But if some time passes without reaction, send a reminder by email. Your patch should eventually be dealt with. -@section New codecs or formats checklist +@chapter New codecs or formats checklist @enumerate @item @@ -537,7 +549,7 @@ Did you make sure it compiles standalone, i.e. with @end enumerate -@section patch submission checklist +@chapter patch submission checklist @enumerate @item @@ -650,7 +662,7 @@ Test your code with valgrind and or Address Sanitizer to ensure it's free of leaks, out of array accesses, etc. @end enumerate -@section Patch review process +@chapter Patch review process All patches posted to ffmpeg-devel will be reviewed, unless they contain a clear note that the patch is not for the git master branch. @@ -681,7 +693,7 @@ to be reviewed, please consider helping to review other patches, that is a great way to get everyone's patches reviewed sooner. @anchor{Regression tests} -@section Regression tests +@chapter Regression tests Before submitting a patch (or committing to the repository), you should at least test that you did not break anything. @@ -692,7 +704,7 @@ Running 'make fate' accomplishes this, please see @url{fate.html} for details. this case, the reference results of the regression tests shall be modified accordingly]. -@subsection Adding files to the fate-suite dataset +@section Adding files to the fate-suite dataset When there is no muxer or encoder available to generate test media for a specific test then the media has to be included in the fate-suite. @@ -703,7 +715,7 @@ Once you have a working fate test and fate sample, provide in the commit message or introductory message for the patch series that you post to the ffmpeg-devel mailing list, a direct link to download the sample media. -@subsection Visualizing Test Coverage +@section Visualizing Test Coverage The FFmpeg build system allows visualizing the test coverage in an easy manner with the coverage tools @code{gcov}/@code{lcov}. This involves @@ -730,7 +742,7 @@ You can use the command @code{make lcov-reset} to reset the coverage measurements. You will need to rerun @code{make lcov} after running a new test. -@subsection Using Valgrind +@section Using Valgrind The configure script provides a shortcut for using valgrind to spot bugs related to memory handling. Just add the option @@ -744,7 +756,7 @@ In case you need finer control over how valgrind is invoked, use the your configure line instead. @anchor{Release process} -@section Release process +@chapter Release process FFmpeg maintains a set of @strong{release branches}, which are the recommended deliverable for system integrators and distributors (such as @@ -776,7 +788,7 @@ adjustments to the symbol versioning file. Please discuss such changes on the @strong{ffmpeg-devel} mailing list in time to allow forward planning. @anchor{Criteria for Point Releases} -@subsection Criteria for Point Releases +@section Criteria for Point Releases Changes that match the following criteria are valid candidates for inclusion into a point release: @@ -800,7 +812,7 @@ point releases of the same release branch. The order for checking the rules is (1 OR 2 OR 3) AND 4. -@subsection Release Checklist +@section Release Checklist The release process involves the following steps:
Previously, the Developer Documentation <ffmpeg.org/developer.html> 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 <http://ffmpeg.org/pipermail/ffmpeg-devel/2017-November/220528.html>. 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 <from.ffmpeg-dev@jdlh.com> --- doc/developer.texi | 74 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 43 insertions(+), 31 deletions(-)