--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/content/Coding/025-upgrading-django1.5.rst	Thu Jan 30 21:45:03 2014 -0600
@@ -0,0 +1,120 @@
+Upgrading to Django 1.5
+#######################
+
+:date: 2013-08-29 19:30
+:tags: Django
+:slug: upgrading-to-django-1.5
+:author: Brian Neal
+
+Upgrading to Django 1.5
+=======================
+
+`Django`_ 1.5 came out a while ago, and I finally got around to upgrading two
+of my largest sites. I thought I would make a list of what I changed at a high
+level for my own reference. Perhaps someone else may find it useful as well.
+
+In any event, I highly recommend you read the excellent `release notes`_ and
+`deprecation timeline`_. I also recommend you run with warnings turned on::
+
+   $ python -Wall manage.py runserver
+
+This will help you flag down issues in your code. If you aren't sure where
+a warning is coming from, you can turn warnings into exceptions and get
+a traceback (see the Python docs on the warnings_ library). Another trick is to
+put a pdb_ breakpoint in the Django code before or after the warning, then you
+can examine the call stack with the ``w`` command.
+
+Upgrading Issues
+================
+
+Here are the issues that I ran into. Of course you may have a very different
+experience depending on what features of Django you used and the details of
+your site.
+
+#. **Replace occurrences of Django's simplejson with json**. The Django team
+   deprecated their version of the json library since they had dropped support
+   for older versions of Python.
+
+#. **select_related's depth argument is deprecated**. Instead of using
+   ``depth`` I had to explictly name which relationships to follow.
+
+#. **The cleanup management command is now called clearsessions**. I have
+   a Celery_ task I had to update because of this name change.
+
+#. **Remove my {% load url from future %} tags**. Long ago I had converted to
+   the newer ``url`` tag behavior by using this tag. Since this is now the
+   current behavior I could remove all of these tags.
+ 
+#. **The LOGIN_* settings now accept URL names**. These settings can now accept
+   URL names which allows me to be more DRY (Don't Repeat Yourself). I no
+   longer have to maintain URL patterns in two places.
+
+#. **Management commands should use self.stdout, etc. for output**. I'm not
+   sure if this is required, but it makes it easier to test your management
+   commands.
+
+#. **slugify is now available at django.utils.text**. I was doing something
+   kind of hacky by invoking the slugify template filter in Python code. Now
+   this slugify code is more naturally available as a free Python function
+   without the template filter baggage.
+
+#. **Remove all references to django.contrib.markup**. Django decided not to be
+   so tightly coupled to various third party markup languages. I can see their
+   reasoning, as it does add to their maintenance burden, but it is kind of
+   inconvenient if you already relied on it. Fortunately I had a while ago
+   stopped relying on the Markdown filter and had used a custom solution.
+   Seeing this issue in the release notes caused me to go looking through my
+   code and I found some unused templates and ``INSTALLED_APPS`` setting that
+   I could remove.  On my second site, I had one tiny usage of the Textile
+   filter that I decided to just get rid of since it was hardly worth carrying
+   the dependency for. I wrote a quick and dirty management command to convert
+   the database from storing Textile markup to HTML and I was done.
+
+#. **localflavor is deprecated in preferece to a third party app**. I was using
+   some US state fields in a few models. All I had to do was pip_ install
+   `django-localflavor`_, fix up some imports, update my requirements files,
+   and I was good.
+
+#. **Function-based generic views are now gone**. A third party application
+   I am using made use of the old function-based generic views. These have been
+   replaced with the newer class-based generic views. Luckily I wasn't actually
+   using the views in this application, I am only relying on it's models and
+   utilities. In this case I simply removed the inclusion of the application's
+   ``urls.py`` and all was well. The application is no longer maintained so
+   I would have had to port to the class-based views if I had needed them.
+
+#. **The adminmedia template tags library is now gone**. I wasn't actually
+   using this anymore, but I had a template that was still loading it. This
+   cruft was removed.
+
+What I didn't do
+================
+
+Django 1.5's largest new feature is probably its support for a `configurable
+User model`_. This impacts my largest site, and I wasn't quite sure how to
+proceed on this front. This is the only issue I feel like Django threw me under
+the bus on. Fortunately, the ``get_profile()`` and ``AUTH_PROFILE_MODULE``
+stuff will not be removed until Django 1.7. In addition, the author of the
+South_ library is developing model migration support which will also land in
+Django 1.7. Thus there is some time to sort this out, and I'm hoping Django
+will have some tutorials or docs on how to migrate away from the old
+``AUTH_PROFILE_MODULE`` scheme.
+
+Conclusion
+==========
+
+The upgrade process went smoother and quicker than I thought thanks to the
+excellent release notes and the Django team's use of Python warnings to flag
+deprecated features.
+
+
+.. _Django: https://www.djangoproject.com/
+.. _release notes: https://docs.djangoproject.com/en/1.5/releases/1.5/
+.. _deprecation timeline: https://docs.djangoproject.com/en/1.5/internals/deprecation/
+.. _warnings: http://docs.python.org/library/warnings.html
+.. _pdb: http://docs.python.org/library/pdb.html
+.. _Celery: http://www.celeryproject.org/
+.. _pip: http://www.pip-installer.org/en/latest/
+.. _django-localflavor: https://pypi.python.org/pypi/django-localflavor
+.. _configurable user model: https://docs.djangoproject.com/en/1.5/topics/auth/customizing/#auth-custom-user
+.. _South: http://south.aeracode.org/