When deploying a Django application into a real production environment, you will almost always want to use an official packaged release of Django. However, if you’d like to try out in-development code from an upcoming release or contribute to the development of Django, you’ll need to obtain a checkout from Django’s source code repository. This document covers the way the code repository is laid out and how to work with and find things in it.
The Django source code repository uses Subversion to track changes to the code over time, so you’ll need a copy of the Subversion client (a program called svn) on your computer, and you’ll want to familiarize yourself with the basics of how Subversion works. Subversion’s web site offers downloads for various operating systems, and a free online book is available to help you get up to speed with using Subversion.
The Django Subversion repository is located online at code.djangoproject.com/svn. A friendly Web-based interface for browsing the code is also available, though when using Subversion you’ll always want to use the repository address instead. At the top level of the repository are two directories: django contains the full source code for all Django releases, while djangoproject.com contains the source code and templates for the djangoproject.com web site. For trying out in-development Django code, or contributing to Django, you’ll always want to check out code from some location in the django directory.
Inside the django directory, Django’s source code is organized into three areas:
If you’d like to try out the in-development code for the next release of Django, or if you’d like to contribute to Django by fixing bugs or developing new features, you’ll want to get the code from trunk. You can get a complete copy of this code (a “Subversion checkout”) by typing:
svn co http://code.djangoproject.com/svn/django/trunk/
Note that this will get all of Django: in addition to the top-level django module containing Python code, you'll also get a copy of Django's documentation, unit-test suite, packaging scripts and other miscellaneous bits. Django's code will be present in your checkout as a directory named django.
To try out the in-development trunk code with your own applications, simply place the directory containing your checkout on your Python import path. Then import statements which look for Django will find the django module within your checkout.
If you're going to be working on Django's code (say, to fix a bug or develop a new feature), you can probably stop reading here and move over to the documentation for contributing to Django, which covers things like the preferred coding style and how to generate and submit a patch.
Django uses branches for two main purposes:
Feature-development branches tend by their nature to be temporary. Some produce successful features which are merged back into Django's trunk to become part of an official release, but others do not; in either case there comes a time when the branch is no longer being actively worked on by any developer. At this point the branch is considered closed.
Unfortunately, Subversion has no standard way of indicating this. As a workaround, branches of Django which are closed and no longer maintained are moved into the directory django/branches/attic.
For reference, the following are branches whose code eventually became part of Django itself, and so are no longer separately maintained:
Additionally, the following branches are closed, but their code was never merged into Django and the features they aimed to implement were never finished:
All of the above-mentioned branches now reside in django/branches/attic.
In addition to fixing bugs in current trunk, the Django project provides official bug-fix support for the most recent released version of Django, and security support for the two most recently-released versions of Django. This support is provided via branches in which the necessary bug or security fixes are applied; the branches are then used as the basis for issuing bugfix or security releases.
As of the Django 1.0 release, these branches can be found in the repository in the directory django/branches/releases, and new branches will be created there approximately one month after each new Django release. For example, shortly after the release of Django 1.0, the branch django/branches/releases/1.0.X was created to receive bug fixes, and shortly after the release of Django 1.1 the branch django/branches/releases/1.1.X was created.
Prior to the Django 1.0 release, these branches were maintaind within the top-level django/branches directory, and so the following branches exist there and provided support for older Django releases:
Official support for those releases has expired, and so they no longer receive direct maintenance from the Django project. However, the branches continue to exist and interested community members have occasionally used them to provide unofficial support for old Django releases.
The directory django/tags within the repository contains complete copies of the Django source code as it existed at various points in its history. These "tagged" copies of Django are never changed or updated; new tags may be added as needed, but once added they are considered read-only and serve as useful guides to Django's development history.
Within django/tags/releases are copies of the code which formed each packaged release of Django, and each tag is named with the version number of the release to which it corresponds. So, for example, django/tags/releases/1.1 is a complete copy of the code which was packaged as the Django 1.1 release.
Within django/tags/notable_moments are copies of the Django code from points which do not directly correspond to releases, but which are nonetheless important historical milestones for Django development. The current "notable moments" marked there are:
Jul 05, 2010