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.