The wrong way for a framework to lay out projects

March 18, 2013

I tweeted:

I admire Django's attempts to screw up my entire source repository structure, where by 'admire' I actually mean 'am madly hacking around'.

I'm sad to say that Django 1.4 is a great illustration of two bad things. First it is a great illustration of how not to lay out a project hierarchy and second it is a great illustration of how not to do a layout transition.

Up until Django 1.4, the more or less canonical source layout of a Django project looked something like this:


The file is basically the central hub for doing a lot of things with (and to) your project. In Django 1.4 they decided that should live at the top level, in a layout that now looks like this:

The problem with this layout is that it breaks the first rule of sane code layout: everything goes in a single directory hierarchy that is your VCS repo. Modern VCSes manage a directory hierarchy, so you really want to give them one. The Django 1.4 layout requires you to invent a container directory purely so that you can put in the same repo as mysite. This container repo has no sensible name the way mysite did (or alternately the only sensible name is once again 'mysite', so you have a mysite/mysite directory to confuse everyone). By contrast the old layout was perfect for VCSes (you made mysite the root of your VCS repo and everything was great).

The other problem is transitioning an existing project that has, of course, set itself up with the mysite directory being the VCS repo. In order to keep under VCS and to keep Django happy, you get to push absolutely everything else in your repo down a level in a massive (and completely artificial) rename changeset. Depending on how your VCS works this may well completely screw up VCS history and the ability to trace changes back over the discontinuity. Since I decline to do this to myself (and to our Django-based web app), I'm instead forced into very ugly hacks in to make it work where it is.

(Django people will say that Django is forced to do this because of Python module handling issues. My view is that it is a mistake to make things into modules in the first place when they are in fact not, and mysite is not a module in any meaningful sense.)

Written on 18 March 2013.
« The power of suggestion that documentation has
Don't use ab for your web server stress tests (I like siege instead) »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Mon Mar 18 21:07:40 2013
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.