The wrong way for a framework to lay out projects
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 ....
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
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
the same repo as
mysite. This container repo has no sensible name
mysite did (or alternately the only sensible name is once
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
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.)