From mboxrd@z Thu Jan 1 00:00:00 1970 From: Takashi Iwai Subject: Re: [PATCH 06/10] ctl: deprecate APIs to add an element set with a single element Date: Tue, 14 Jun 2016 13:46:35 +0200 Message-ID: References: <1465719371-27721-1-git-send-email-o-takashi@sakamocchi.jp> <1465719371-27721-7-git-send-email-o-takashi@sakamocchi.jp> <575FE99C.2090103@sakamocchi.jp> Mime-Version: 1.0 (generated by SEMI 1.14.6 - "Maruoka") Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: Received: from mx2.suse.de (mx2.suse.de [195.135.220.15]) by alsa0.perex.cz (Postfix) with ESMTP id 24A51261691 for ; Tue, 14 Jun 2016 13:46:38 +0200 (CEST) In-Reply-To: <575FE99C.2090103@sakamocchi.jp> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: alsa-devel-bounces@alsa-project.org Sender: alsa-devel-bounces@alsa-project.org To: Takashi Sakamoto Cc: alsa-devel@alsa-project.org, clemens@ladisch.de, ffado-devel@lists.sf.net List-Id: alsa-devel@alsa-project.org On Tue, 14 Jun 2016 13:25:16 +0200, Takashi Sakamoto wrote: > > Hi, > > On Jun 13 2016 21:51, Takashi Iwai wrote: > > On Sun, 12 Jun 2016 10:16:07 +0200, > > Takashi Sakamoto wrote: > >> > >> When comparing old APIs (to add a single element) with new APIs (to add > >> an element set), the latter has an benefit to get full identical > >> information for a first element in the element set. Furthermore, in > >> previous commit, the old APIs become simple wrappers to the new APIs. > >> Therefore, there's few intentions to use the old APIs. > >> > >> This commit deprecates the old APIs to encourage the usage of new APIs. > > > > In general, it's a bad idea to deprecate an API that has been actually > > used, and even a worse idea to give a link warning. We've done > > deprecation for some API functions in the past, and it wasn't a really > > smart move. But it was still justified that they were really unused > > API functions. In this case, however, it's commonly used API. That's > > a big difference. > > > > I know several system libraries like Gtk+ often deprecating API > > functions. But it's more annoying than useful for developers and > > users. Unless you are masochistic, the likely first reaction after > > seeing such a warning is: "upstream sucks again". > > I just added the link_warning() by immitating these old APIs such as > snd_pcm_hwsync(). In short, I assumed that it's a fashion of this > userspace library to use compiler/linker functionalities even if it's > against usual ways to maintain APIs in userspace libraries. Yes, we have had such things, and as mentioned, it was a bad idea, after all. The deprecation doesn't help maintaining the stuff. You don't need to follow our own bad attitude again. > (I'm not so strange developer, just foreigner to this project without > enough documentations.) > > For the deprecation, I basically agree with you. But there might be > exaggeration about usage of these APIs. They're rarely used, I > think. If you know actual application programs to use them, please > inform them to me. But I know discussions about the population of > these APIs are not a good direction in this case. Right, it's not the only indication. > My main intention of this patchset is to add the new APIs. These APIs > are completely upper compatible to the old APIs, and have benefits I > described. In fact, deleting public APIs is not preferable, but > deprecating them and still maintaining sometimes has advantages to > motivate users to start using the new ones. For this purpose, I think > it better to add 'deprecated' comment into documentations of old APIs. It depends. The deprecation and the recommendation are different behavior. The former is needed only when the old API is really harmful or doesn't work any longer. In such a case, giving a link warning is helpful so that user can know of it. Meanwhile, the latter is done everywhere. It's a programming practice, and let users choose a better one. That being said, it'd be good to add recommendation for a better API in the documentation. But it's never meant to deprecate some old API function. Again, deprecation doesn't help much from maintenance POV. I can judge it from my long experiences in both upstream maintainer and downstream packager sides. It may help hardening some serious errors if the old API were really bad. But that's all. thanks, Takashi