Hi All, I think it would help if Django was better at *deprecations and backward compatibility*. I’ve brought this up [before <https://groups.google.com/d/msg/django-developers/ZWy2Esj46nE/jzSP3DRIEAAJ>], but didn’t get any feedback, so here’s another try at it, with some *specific ideas of how to improve things below*.
*Background*: The [API docs <https://docs.djangoproject.com/en/2.0/misc/api-stability/>] say “*If, for some reason, an API declared stable must be removed or replaced*, it will be declared deprecated but will remain in the API for at least two feature releases.” - I’ve always thought of the “must be removed” as “there’s really no alternative”. I think that if it's not broken, Django should avoid breaking it. I maintain lots of Django projects, and upgrading is not a small task. There are enough changes to undocumented APIs already happening that it would be great if the documented ones didn't change as much. I also think it’s a little disappointing that *3rd party libraries don’t get easy 1.8 and 2.0 support out of the box*. Both of those releases are currently supported, but if the library uses deprecated features to support 1.8, it won’t work on 2.0 by definition. Yes, backward compatibility means Django has more technical debt, and yes it comes at a cost (more code, more docs, tests run longer, more thank-less maintenance etc), but it means Django’s not forcing users to do the tedious work of changing their code. That’s a _huge_ benefit. Isn’t the whole point of a framework to have documented and tested code so the user doesn’t need to do tedious things? “it takes care of much of the hassle of Web development, so you can focus on writing your app.” Some deprecations I thought could have gone better: #17209 (auth views), #26013 (urls.urlresolvers), #22218 (url patterns()), #23276 (url() strings), #14675 (urls.defaults), #6735 (views.generic.simple), #18651 (assignment_tag). *Ideas of how to improve backward compatibility*: *1.* I think it would help if any breaking change, and any new deprecation/removal (any change that adds to those sections in the release notes) received 3-7 days *feedback from the mailing list*, with a clear subject, something like “deprecating X”, "changing x's defaults", “renaming X” or “removing X”. It's a little more bureaucracy, but I think there's a huge benefit to making sure everyone's on the same page about these things. (This already happens for some, but not all deprecations.) I don’t pay close attention to tickets and pull requests, so I often don’t notice that there’s a new deprecation/removal until _after_ it’s already been merged. The few people on the ticket may have agreed to removing something, but not necessarily the larger community. Or, if it was being discussed, a lot of discussion was on the new feature, and it wasn’t clear that a deprecation/removal would be included in the change. (Sometimes the deprecation is thrown in as an after-thought / "while we're at it, lets rename...") Having a *clear email in django-developers* would also give more people the initial heads-up to avoid using the old code. *2.* For some changes, Django has decided to delay/*hold off deprecating/removing a feature until after the next LTS or “eventually”* (some good examples: #23433 (django-admin.py), #27753 (utils.six, etc), #25236 (ifequal), #25978 (render_to_response), #28593 (url() -> re_path()). I think this delay is a really good thing, and I think it should be *more official/documented to encourage its use* (if not the default). As [Russ put it <https://groups.google.com/d/msg/django-developers/J7vpMKSHk7U/3vGPs71MCgAJ> ]: “The only other suggestion I've got is to add a new "pre-deprecation" step to our deprecation process - a flag that lets us indicate that at some point, we intend to deprecate something, but we haven't decided when that will be. This would essentially be a "*don't use this on new code, but there's no rush in replacing it*". It could also be accompanied with a Warning so that existing uses could be found and replaced if someone was so inclined.” Delaying the removal would *help libraries support both 1.8 and 2.0* (for example) at the same time. (Also, I think a longer removal timeline might make it a little less likely for something to be deprecated/removed in the first place. - A good thing, in my opinion.) Thanks, Collin [before] https://groups.google.com/d/msg/django-developers/ZWy2Esj46nE/jzSP3DRIEAAJ [API docs] https://docs.djangoproject.com/en/2.0/misc/api-stability/ [Russ put it] https://groups.google.com/d/msg/django-developers/J7vpMKSHk7U/3vGPs71MCgAJ -- You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@googlegroups.com. Visit this group at https://groups.google.com/group/django-developers. To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/6ebdc57e-32df-4815-860d-c76c6e3b4884%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
