Add new documentation covering the layout of the Django SVN repository.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@11466 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
parent
eaf1f7d6e3
commit
5eda3a16df
|
@ -187,7 +187,8 @@ The Django open-source project
|
||||||
* **Community:**
|
* **Community:**
|
||||||
:ref:`How to get involved <internals-contributing>` |
|
:ref:`How to get involved <internals-contributing>` |
|
||||||
:ref:`The release process <internals-release-process>` |
|
:ref:`The release process <internals-release-process>` |
|
||||||
:ref:`Team of committers <internals-committers>`
|
:ref:`Team of committers <internals-committers>` |
|
||||||
|
:ref:`The Django source code repository <internals-svn>`
|
||||||
|
|
||||||
* **Design philosophies:**
|
* **Design philosophies:**
|
||||||
:ref:`Overview <misc-design-philosophies>`
|
:ref:`Overview <misc-design-philosophies>`
|
||||||
|
|
|
@ -0,0 +1,258 @@
|
||||||
|
.. _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 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. Generally, you can recognize a dead branch by viewing it through
|
||||||
|
the web interface, which lists the date of the most recent change to
|
||||||
|
the branch. Branches which have gone more than a month or two with no
|
||||||
|
activity can usually be assumed to be closed. In the future, the
|
||||||
|
layout of branches in the repository may be rearranged to make it
|
||||||
|
easier to tell which branches are still active (e.g., by moving closed
|
||||||
|
or abandoned branches into the ``django/branches/attic`` directory).
|
||||||
|
|
||||||
|
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``
|
||||||
|
|
||||||
|
|
||||||
|
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`` will be 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.
|
Loading…
Reference in New Issue