From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 7708 invoked by alias); 9 Oct 2014 18:07:35 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 7696 invoked by uid 89); 9 Oct 2014 18:07:34 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.9 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_LOW,SPF_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: mail-vc0-f172.google.com Received: from mail-vc0-f172.google.com (HELO mail-vc0-f172.google.com) (209.85.220.172) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES128-SHA encrypted) ESMTPS; Thu, 09 Oct 2014 18:07:33 +0000 Received: by mail-vc0-f172.google.com with SMTP id lf12so1451945vcb.17 for ; Thu, 09 Oct 2014 11:07:31 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:date:message-id:subject:from:to:cc :content-type; bh=9QDds3XHGssrUlzR/gigWf/5QiHBSF4eKj3d4gOcUnk=; b=UO22iOs9xj5JIP+rgRs9nG8Wy8K5q+QbUW/FF/9faYorSfezp1JtLYGZAvr1DI+UY3 0iDNQFxGJSmEUW5g7xJK9321auhPg2j9X18DJGy3lHQyIcNmHDXyT7fn/AwiwkZ9HNvM mUiPX+mwdP3t+xuGCZmHyyjAeYTBD9ngEKNR/fRfmefPBEz1gOhP2T5JkHQCxGa+XlTE xrZv7MgiwiRlS1pkSDnQDTncQj/tn4ssmOAta3zu7M9D1mr9072rKTvNk3q3QnjtgEGh yiMqJsPoIyz7lgQ63YVh06iN4fbCUMoAPIe/pGNLPrrXdZ6ZE4nsaZHXMl6VcCSssKp5 G8Jw== X-Gm-Message-State: ALoCoQk5Xxh/cj5ETcAAKnGdafc2X1vTdk+C3rMofjWq6vvAf33gBPyMTiY9pMf/Vlgh8YzpShgL MIME-Version: 1.0 X-Received: by 10.52.101.227 with SMTP id fj3mr17958044vdb.67.1412878050976; Thu, 09 Oct 2014 11:07:30 -0700 (PDT) Received: by 10.52.181.65 with HTTP; Thu, 9 Oct 2014 11:07:30 -0700 (PDT) Date: Thu, 09 Oct 2014 18:07:00 -0000 Message-ID: Subject: Deprecating (and deleting) user-facing APIs [was Re: Why do functions objfpy_new and pspy_new exist?] From: Doug Evans To: Stan Shebs Cc: gdb-patches Content-Type: text/plain; charset=UTF-8 X-IsSubscribed: yes X-SW-Source: 2014-10/txt/msg00219.txt.bz2 [I've changed the subject line to make the topic stand out more ...] On Thu, Oct 2, 2014 at 3:11 PM, Stan Shebs wrote: > On 9/25/14, 3:07 PM, Doug Evans wrote: > [...] >> >> I know I've mentioned this before, but since the topic has come up again, >> I think GDB could have a formal deprecation process that would allow >> us to remove things we'd like to remove (this is for API-like things >> which are harder to remove than, e.g., outdated ports). > > Nominally, the existing process is as described at > > https://sourceware.org/gdb/wiki/Internals%20Obsoleting-code > > We've also done "deprecate in one release, remove in the next", and > added "deprecated_" onto function names and such. Empirically, it > hasn't created the desired urgency - people have been content to keep > calling deprecated_foo for many years after its deprecation. :-) Yeah, though this situation is different in the sense that the subject here is externally facing APIs. At least different from adding "deprecated_" to function names; if we rename a function we've already broken user code. [One can imagine a multistep process where we add deprecated_foo as a synonym for foo, then later delete foo, and then still later delete deprecated_foo. That might be overkill in general.] I'm glad I haven't seen any real pushback (at least not yet :-)), so to advance the discussion ... One thing I think we need is to publish somewhere the state of the things being deprecated (and by "things" here I mean only user-facing API elements). [I'd still document the process for developers to follow in the above link. What I'm talking about here is for users to see the details of what's currently in the process of being deprecated/deleted.] And by "deprecated" here I also mean that we intend to eventually delete it. Anything deprecated here is also given a deletion date (where the date is probably expressed in terms of number of releases from now). We want to give users time to migrate away from things that will eventually be deleted, and I can imagine the length of time being more than one release. Thus we need to publish the current state in a place where users can find it and track it. I don't have a strong opinion on where this documentation lives. Anyone have a strong opinion on where this should live? I can see an argument made for keeping it with the sources. As a strawman we could have a "Deprecated APIs" section in gdb.texinfo. I would also add an easy to find link to the currently generated form from the website. I'd also add appropriate entries to NEWS of course. Comments?