Browse files

Add new documentation covering the layout of the Django SVN repository.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent eaf1f7d commit 5eda3a16dfa6b40907a9edfad4ed9e3d3fdaeb1c @ubernostrum ubernostrum committed Aug 17, 2009
Showing with 260 additions and 1 deletion.
  1. +2 −1 docs/index.txt
  2. +258 −0 docs/internals/svn.txt
@@ -187,7 +187,8 @@ The Django open-source project
* **Community:**
:ref:`How to get involved <internals-contributing>` |
: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:**
: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:
+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
+` <>`_. `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 ```` contains the source code and
+templates for for the `
+<>` 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:
+.. _a free online book:
+.. _A friendly web-based interface for browsing the code:
+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
+ svn co
+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.
+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
+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.

0 comments on commit 5eda3a1

Please sign in to comment.