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:

mysite/
    manage.py
    settings.py
    ...
    myapp/
        models.py
        ....

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

manage.py
mysite/
    settings.py
    ....

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 manage.py 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 manage.py 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 manage.py 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.)