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