257 lines
10 KiB
Plaintext
257 lines
10 KiB
Plaintext
.. _internals-svn:
|
|
|
|
=================================
|
|
The Django source code repository
|
|
=================================
|
|
|
|
|
|
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.
|
|
|
|
|
|
.. _an official packaged release of Django: http://www.djangoproject.com/download/
|
|
|
|
|
|
High-level overview
|
|
===================
|
|
|
|
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 <http://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 <http://www.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:
|
|
|
|
* ``branches`` contains branched copies of Django's code, which are
|
|
(or were) maintained for various purposes. Some branches exist to
|
|
provide a place to develop major or experimental new features
|
|
without affecting the rest of Django's code, while others serve to
|
|
provide bug fixes or support for older Django releases.
|
|
|
|
* ``tags`` contains snapshots of Django's code at various important
|
|
points in its history; mostly these are the exact revisions from
|
|
which packaged Django releases were produced.
|
|
|
|
* ``trunk`` contains the main in-development code which will become
|
|
the next packaged release of Django, and is where most development
|
|
activity is focused.
|
|
|
|
|
|
.. _Subversion: http://subversion.tigris.org/
|
|
.. _a free online book: http://svnbook.red-bean.com/
|
|
.. _A friendly web-based interface for browsing the code: http://code.djangoproject.com/browser/
|
|
|
|
|
|
Working with Django's trunk
|
|
===========================
|
|
|
|
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 :ref:`the documentation for contributing to Django
|
|
<internals-contributing>`, which covers things like the preferred
|
|
coding style and how to generate and submit a patch.
|
|
|
|
|
|
Branches
|
|
========
|
|
|
|
Django uses branches for two main purposes:
|
|
|
|
1. Development of major or experimental features, to keep them from
|
|
affecting progress on other work in trunk.
|
|
|
|
2. Security and bug-fix support for older releases of Django, during
|
|
their support lifetimes.
|
|
|
|
|
|
Feature-development branches
|
|
----------------------------
|
|
|
|
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:
|
|
|
|
* ``boulder-oracle-sprint``: Added support for Oracle databases to
|
|
Django's object-relational mapper. This has been part of Django
|
|
since the 1.0 release.
|
|
|
|
* ``gis``: Added support for geographic/spatial queries to Django's
|
|
object-relational mapper. This has been part of Django since the 1.0
|
|
release, as the bundled application ``django.contrib.gis``.
|
|
|
|
* ``i18n``: Added :ref:`internationalization support <topics-i18n>` to
|
|
Django. This has been part of Django since the 0.90 release.
|
|
|
|
* ``magic-removal``: A major refactoring of both the internals and
|
|
public APIs of Django's object-relational mapper. This has been part
|
|
of Django since the 0.95 release.
|
|
|
|
* ``multi-auth``: A refactoring of :ref:`Django's bundled
|
|
authentication framework <topics-auth>` which added support for
|
|
:ref:`authentication backends <authentication-backends>`. This has
|
|
been part of Django since the 0.95 release.
|
|
|
|
* ``new-admin``: A refactoring of :ref:`Django's bundled
|
|
administrative application <ref-contrib-admin>`. This became part of
|
|
Django as of the 0.91 release, but was superseded by another
|
|
refactoring (see next listing) prior to the Django 1.0 release.
|
|
|
|
* ``newforms-admin``: The second refactoring of Django's bundled
|
|
administrative application. This became part of Django as of the 1.0
|
|
release, and is the basis of the current incarnation of
|
|
``django.contrib.admin``.
|
|
|
|
* ``queryset-refactor``: A refactoring of the internals of Django's
|
|
object-relational mapper. This became part of Django as of the 1.0
|
|
release.
|
|
|
|
* ``unicode``: A refactoring of Django's internals to consistently use
|
|
Unicode-based strings in most places within Django and Django
|
|
applications. This became part of Django as of the 1.0 release.
|
|
|
|
Additionally, the following branches are closed, but their code was
|
|
never merged into Django and the features they aimed to implement
|
|
were never finished:
|
|
|
|
* ``full-history``
|
|
|
|
* ``generic-auth``
|
|
|
|
* ``multiple-db-support``
|
|
|
|
* ``per-object-permissions``
|
|
|
|
* ``schema-evolution``
|
|
|
|
* ``schema-evolution-ng``
|
|
|
|
* ``search-api``
|
|
|
|
* ``sqlalchemy``
|
|
|
|
All of the above-mentioned branches now reside in
|
|
``django/branches/attic``.
|
|
|
|
|
|
Support and bugfix branches
|
|
---------------------------
|
|
|
|
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:
|
|
|
|
* ``0.90-bugfixes``
|
|
|
|
* ``0.91-bugfixes``
|
|
|
|
* ``0.95-bugfixes``
|
|
|
|
* ``0.96-bugfixes``
|
|
|
|
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.
|
|
|
|
|
|
Tags
|
|
====
|
|
|
|
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:
|
|
|
|
* ``ipo``: Django's code as it existed at the moment Django was first
|
|
publicly announced in 2005.
|
|
|
|
* ``pre-magic-removal``: The state of Django's code just before the
|
|
merging of the ``magic-removal`` branch (described above), which
|
|
significantly updated Django's object-relational mapper.
|
|
|
|
* ``pre-newforms-admin``: The state of Django's code just before the
|
|
merging of the ``newforms-admin`` branch (see above), which
|
|
significantly updated Django's bundled administrative application.
|
|
|
|
* Tags corresponding to each of the alpha, beta and release-candidate
|
|
packages in the run up to the Django 1.0 release.
|