Just found the deprecation process document
<https://www.mediawiki.org/wiki/Requests_for_comment/API_roadmap>,
specifically:
1. If not already present, a request parameter will
be added to
specifically request the old behavior.
2. The change will be announced:
- A message will be sent to the mediawiki-api-announce
<http://lists.wikimedia.org/pipermail/mediawiki-api-announce/> mailing
list.
- Deprecation warnings will be output when neither the
select-new-version nor the select-old-version flags are used. Logs will
also be made.
3. *After a suitable timeframe, the new version will become the
default.*
4. *Any flag to select the new version explicitly may at some point be
removed, leading to "unrecognized parameter" warnings.*
My argument is that step #3 is unnecessary and #4 needs clarification in
that IMO APIs should only be removed when they are no longer supported,
otherwise you're just creating busy work for yourself and the clients.
On Thu, Jun 4, 2015 at 1:59 PM, Brian Gerstle <bgerstle(a)wikimedia.org>
wrote:
I know about the phab ticket, but I'm glad you
referenced it because I
found this:
(Anomie): I think feature flags to *select new behavior* and *a good
deprecation process* will take care of most
things that actually need
improvement, to the point where we can do per-module versioning on an ad
hoc basis rather than trying to force it everywhere.
IOW, why don't we continue w/ this feature flagging approach, which seems
like a decent way to version APIs and prevent breaking backwards
compatibility?
On Thu, Jun 4, 2015 at 1:05 PM, Legoktm <legoktm.wikipedia(a)gmail.com>
wrote:
On 06/04/2015 09:45 AM, Brian Gerstle wrote:
While it is (a little bit) nicer for new
developers, they'll just burned
(along with all the other current API users) when you change the
defaults.
What I'm trying to say is, changing the
default seems like more work for
more people with very little benefit. This is why
<https://developer.github.com/v3/> people <
https://www.reddit.com/dev/api>
version
<https://stripe.com/docs/api#charge_object> APIs
<https://developer.linkedin.com/docs/rest-api>.
I'd recommend reading <https://phabricator.wikimedia.org/T41592>, which
contains a pretty good rationale of why we currently don't version the
API.
-- Legoktm
_______________________________________________
Wikitech-l mailing list
Wikitech-l(a)lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
--
EN Wikipedia user page:
https://en.wikipedia.org/wiki/User:Brian.gerstle
IRC: bgerstle
--
EN Wikipedia user page:
https://en.wikipedia.org/wiki/User:Brian.gerstle
IRC: bgerstle