On Oct 25, 2015, at 11:34 PM, Glyph Lefkowitz wrote:
For another, we have no way to hide deprecated APIs in the API documentation. If a new user is trying to figure out how to do something, if they're doing it during the deprecation period, they should not start out by using a deprecated API; yet, sometimes, if you look at the docs, that's what you'll find first.
I've been bitten by this before. I've also had issue with developers implementing a django-style upgrade/deprecation system **improperly** and creating a lot of nightmares for developers. By "Improperly" I mean that some developers will arbitrarily pin dependencies to certain versions or narrow ranges, which ends up creating version conflicts or preventing installs. From a "non-core user" of twisted point of view, and someone likely to run into issues from this change... things that I have liked from other projects are: 1. Narrative & API docs that note when something is going to be deprecated **in the first line**. 2. API docs that allow a reader to flip between versions. (a la ReadTheDocs style) If I end up on a link to /current docs and something is missing, I'd like to be able to flip back a few versions and read the deprecation info. 3. Logged deprecation warnings. IIRC, by default SqlAlchemy will log a deprecation warning the first 3 or 4x you call a function that is on it's way out. Twisted can be very "fast" in logging, so these messages might be lost. It might be nice to be able to pipe deprecation warnings into their own logger / output.