Plain Text | 254 lines | 185 code | 69 blank | 0 comment | 0 complexity | 20ada7749943ec5564af0c9a9897f381 MD5 | raw file
1================================= 2The Django source code repository 3================================= 4 5 6When deploying a Django application into a real production 7environment, you will almost always want to use `an official packaged 8release of Django`_. However, if you'd like to try out in-development 9code from an upcoming release or contribute to the development of 10Django, you'll need to obtain a checkout from Django's source code 11repository. This document covers the way the code repository is laid 12out 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 18High-level overview 19=================== 20 21The Django source code repository uses `Subversion`_ to track changes 22to 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 24familiarize yourself with the basics of how Subversion 25works. Subversion's Web site offers downloads for various operating 26systems, and `a free online book`_ is available to help you get up to 27speed with using Subversion. 28 29The Django Subversion repository is located online at 30`code.djangoproject.com/svn <http://code.djangoproject.com/svn/>`_. `A 31friendly Web-based interface for browsing the code`_ is also 32available, though when using Subversion you'll always want to use the 33repository address instead. At the top level of the repository are two 34directories: ``django`` contains the full source code for all Django 35releases, while ``djangoproject.com`` contains the source code and 36templates for the `djangoproject.com <http://www.djangoproject.com/>`_ 37Web site. For trying out in-development Django code, or contributing 38to Django, you'll always want to check out code from some location in 39the ``django`` directory. 40 41Inside the ``django`` directory, Django's source code is organized 42into 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 64Working with Django's trunk 65=========================== 66 67If you'd like to try out the in-development code for the next release 68of Django, or if you'd like to contribute to Django by fixing bugs or 69developing new features, you'll want to get the code from trunk. You 70can get a complete copy of this code (a "Subversion checkout") by 71typing:: 72 73 svn co http://code.djangoproject.com/svn/django/trunk/ 74 75Note 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 77Django's documentation, unit-test suite, packaging scripts and other 78miscellaneous bits. Django's code will be present in your checkout as 79a directory named ``django``. 80 81To try out the in-development trunk code with your own applications, 82simply place the directory containing your checkout on your Python 83import path. Then ``import`` statements which look for Django will find 84the ``django`` module within your checkout. 85 86If you're going to be working on Django's code (say, to fix a bug or 87develop a new feature), you can probably stop reading here and move 88over to :doc:`the documentation for contributing to Django 89</internals/contributing>`, which covers things like the preferred 90coding style and how to generate and submit a patch. 91 92 93Branches 94======== 95 96Django uses branches for two main purposes: 97 981. Development of major or experimental features, to keep them from 99 affecting progress on other work in trunk. 100 1012. Security and bug-fix support for older releases of Django, during 102 their support lifetimes. 103 104 105Feature-development branches 106---------------------------- 107 108Feature-development branches tend by their nature to be 109temporary. Some produce successful features which are merged back into 110Django's trunk to become part of an official release, but others do 111not; in either case there comes a time when the branch is no longer 112being actively worked on by any developer. At this point the branch is 113considered closed. 114 115Unfortunately, Subversion has no standard way of indicating this. As a 116workaround, branches of Django which are closed and no longer 117maintained are moved into the directory ``django/branches/attic``. 118 119For reference, the following are branches whose code eventually became 120part 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 160Additionally, the following branches are closed, but their code was 161never merged into Django and the features they aimed to implement 162were 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 180All of the above-mentioned branches now reside in 181``django/branches/attic``. 182 183 184Support and bugfix branches 185--------------------------- 186 187In addition to fixing bugs in current trunk, the Django project 188provides official bug-fix support for the most recent released version 189of Django, and security support for the two most recently-released 190versions of Django. This support is provided via branches in which the 191necessary bug or security fixes are applied; the branches are then 192used as the basis for issuing bugfix or security releases. 193 194As of the Django 1.0 release, these branches can be found in the 195repository in the directory ``django/branches/releases``, and new branches 196will be created there approximately one month after each new Django 197release. For example, shortly after the release of Django 1.0, the 198branch ``django/branches/releases/1.0.X`` was created to receive bug 199fixes, and shortly after the release of Django 1.1 the branch 200``django/branches/releases/1.1.X`` was created. 201 202Prior to the Django 1.0 release, these branches were maintained within 203the top-level ``django/branches`` directory, and so the following 204branches 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 214Official support for those releases has expired, and so they no longer 215receive direct maintenance from the Django project. However, the 216branches continue to exist and interested community members have 217occasionally used them to provide unofficial support for old Django 218releases. 219 220 221Tags 222==== 223 224The directory ``django/tags`` within the repository contains complete 225copies of the Django source code as it existed at various points in 226its history. These "tagged" copies of Django are *never* changed or 227updated; new tags may be added as needed, but once added they are 228considered read-only and serve as useful guides to Django's 229development history. 230 231Within ``django/tags/releases`` are copies of the code which formed each 232packaged release of Django, and each tag is named with the version 233number 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 235packaged as the Django 1.1 release. 236 237Within ``django/tags/notable_moments`` are copies of the Django code from 238points which do not directly correspond to releases, but which are 239nonetheless important historical milestones for Django 240development. 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.