3
=================================
4
The Django source code repository
5
=================================
8
When deploying a Django application into a real production
9
environment, you will almost always want to use `an official packaged
10
release of Django`_. However, if you'd like to try out in-development
11
code from an upcoming release or contribute to the development of
12
Django, you'll need to obtain a checkout from Django's source code
13
repository. This document covers the way the code repository is laid
14
out and how to work with and find things in it.
17
.. _an official packaged release of Django: http://www.djangoproject.com/download/
23
The Django source code repository uses `Subversion`_ to track changes
24
to the code over time, so you'll need a copy of the Subversion client
25
(a program called ``svn``) on your computer, and you'll want to
26
familiarize yourself with the basics of how Subversion
27
works. Subversion's web site offers downloads for various operating
28
systems, and `a free online book`_ is available to help you get up to
29
speed with using Subversion.
31
The Django Subversion repository is located online at
32
`code.djangoproject.com/svn <http://code.djangoproject.com/svn/>`_. `A
33
friendly Web-based interface for browsing the code`_ is also
34
available, though when using Subversion you'll always want to use the
35
repository address instead. At the top level of the repository are two
36
directories: ``django`` contains the full source code for all Django
37
releases, while ``djangoproject.com`` contains the source code and
38
templates for the `djangoproject.com <http://www.djangoproject.com/>`_
39
web site. For trying out in-development Django code, or contributing
40
to Django, you'll always want to check out code from some location in
41
the ``django`` directory.
43
Inside the ``django`` directory, Django's source code is organized
46
* ``branches`` contains branched copies of Django's code, which are
47
(or were) maintained for various purposes. Some branches exist to
48
provide a place to develop major or experimental new features
49
without affecting the rest of Django's code, while others serve to
50
provide bug fixes or support for older Django releases.
52
* ``tags`` contains snapshots of Django's code at various important
53
points in its history; mostly these are the exact revisions from
54
which packaged Django releases were produced.
56
* ``trunk`` contains the main in-development code which will become
57
the next packaged release of Django, and is where most development
61
.. _Subversion: http://subversion.tigris.org/
62
.. _a free online book: http://svnbook.red-bean.com/
63
.. _A friendly web-based interface for browsing the code: http://code.djangoproject.com/browser/
66
Working with Django's trunk
67
===========================
69
If you'd like to try out the in-development code for the next release
70
of Django, or if you'd like to contribute to Django by fixing bugs or
71
developing new features, you'll want to get the code from trunk. You
72
can get a complete copy of this code (a "Subversion checkout") by
75
svn co http://code.djangoproject.com/svn/django/trunk/
77
Note that this will get *all* of Django: in addition to the top-level
78
``django`` module containing Python code, you'll also get a copy of
79
Django's documentation, unit-test suite, packaging scripts and other
80
miscellaneous bits. Django's code will be present in your checkout as
81
a directory named ``django``.
83
To try out the in-development trunk code with your own applications,
84
simply place the directory containing your checkout on your Python
85
import path. Then ``import`` statements which look for Django will find
86
the ``django`` module within your checkout.
88
If you're going to be working on Django's code (say, to fix a bug or
89
develop a new feature), you can probably stop reading here and move
90
over to :ref:`the documentation for contributing to Django
91
<internals-contributing>`, which covers things like the preferred
92
coding style and how to generate and submit a patch.
98
Django uses branches for two main purposes:
100
1. Development of major or experimental features, to keep them from
101
affecting progress on other work in trunk.
103
2. Security and bug-fix support for older releases of Django, during
104
their support lifetimes.
107
Feature-development branches
108
----------------------------
110
Feature-development branches tend by their nature to be
111
temporary. Some produce successful features which are merged back into
112
Django's trunk to become part of an official release, but others do
113
not; in either case there comes a time when the branch is no longer
114
being actively worked on by any developer. At this point the branch is
117
Unfortunately, Subversion has no standard way of indicating this. As a
118
workaround, branches of Django which are closed and no longer
119
maintained are moved into the directory ``django/branches/attic``.
121
For reference, the following are branches whose code eventually became
122
part of Django itself, and so are no longer separately maintained:
124
* ``boulder-oracle-sprint``: Added support for Oracle databases to
125
Django's object-relational mapper. This has been part of Django
126
since the 1.0 release.
128
* ``gis``: Added support for geographic/spatial queries to Django's
129
object-relational mapper. This has been part of Django since the 1.0
130
release, as the bundled application ``django.contrib.gis``.
132
* ``i18n``: Added :ref:`internationalization support <topics-i18n>` to
133
Django. This has been part of Django since the 0.90 release.
135
* ``magic-removal``: A major refactoring of both the internals and
136
public APIs of Django's object-relational mapper. This has been part
137
of Django since the 0.95 release.
139
* ``multi-auth``: A refactoring of :ref:`Django's bundled
140
authentication framework <topics-auth>` which added support for
141
:ref:`authentication backends <authentication-backends>`. This has
142
been part of Django since the 0.95 release.
144
* ``new-admin``: A refactoring of :ref:`Django's bundled
145
administrative application <ref-contrib-admin>`. This became part of
146
Django as of the 0.91 release, but was superseded by another
147
refactoring (see next listing) prior to the Django 1.0 release.
149
* ``newforms-admin``: The second refactoring of Django's bundled
150
administrative application. This became part of Django as of the 1.0
151
release, and is the basis of the current incarnation of
152
``django.contrib.admin``.
154
* ``queryset-refactor``: A refactoring of the internals of Django's
155
object-relational mapper. This became part of Django as of the 1.0
158
* ``unicode``: A refactoring of Django's internals to consistently use
159
Unicode-based strings in most places within Django and Django
160
applications. This became part of Django as of the 1.0 release.
162
Additionally, the following branches are closed, but their code was
163
never merged into Django and the features they aimed to implement
170
* ``multiple-db-support``
172
* ``per-object-permissions``
174
* ``schema-evolution``
176
* ``schema-evolution-ng``
182
All of the above-mentioned branches now reside in
183
``django/branches/attic``.
186
Support and bugfix branches
187
---------------------------
189
In addition to fixing bugs in current trunk, the Django project
190
provides official bug-fix support for the most recent released version
191
of Django, and security support for the two most recently-released
192
versions of Django. This support is provided via branches in which the
193
necessary bug or security fixes are applied; the branches are then
194
used as the basis for issuing bugfix or security releases.
196
As of the Django 1.0 release, these branches can be found in the
197
repository in the directory ``django/branches/releases``, and new branches
198
will be created there approximately one month after each new Django
199
release. For example, shortly after the release of Django 1.0, the
200
branch ``django/branches/releases/1.0.X`` was created to receive bug
201
fixes, and shortly after the release of Django 1.1 the branch
202
``django/branches/releases/1.1.X`` was created.
204
Prior to the Django 1.0 release, these branches were maintaind within
205
the top-level ``django/branches`` directory, and so the following
206
branches exist there and provided support for older Django releases:
216
Official support for those releases has expired, and so they no longer
217
receive direct maintenance from the Django project. However, the
218
branches continue to exist and interested community members have
219
occasionally used them to provide unofficial support for old Django
226
The directory ``django/tags`` within the repository contains complete
227
copies of the Django source code as it existed at various points in
228
its history. These "tagged" copies of Django are *never* changed or
229
updated; new tags may be added as needed, but once added they are
230
considered read-only and serve as useful guides to Django's
233
Within ``django/tags/releases`` are copies of the code which formed each
234
packaged release of Django, and each tag is named with the version
235
number of the release to which it corresponds. So, for example,
236
``django/tags/releases/1.1`` is a complete copy of the code which was
237
packaged as the Django 1.1 release.
239
Within ``django/tags/notable_moments`` are copies of the Django code from
240
points which do not directly correspond to releases, but which are
241
nonetheless important historical milestones for Django
242
development. The current "notable moments" marked there are:
244
* ``ipo``: Django's code as it existed at the moment Django was first
245
publicly announced in 2005.
247
* ``pre-magic-removal``: The state of Django's code just before the
248
merging of the ``magic-removal`` branch (described above), which
249
significantly updated Django's object-relational mapper.
251
* ``pre-newforms-admin``: The state of Django's code just before the
252
merging of the ``newforms-admin`` branch (see above), which
253
significantly updated Django's bundled administrative application.
255
* Tags corresponding to each of the alpha, beta and release-candidate
256
packages in the run up to the Django 1.0 release.
added
removed
docs/internals/svn.txt
