Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
  • Loading branch information...
commit 5eda3a16dfa6b40907a9edfad4ed9e3d3fdaeb1c 1 parent eaf1f7d
James Bennett authored August 17, 2009
3  docs/index.txt
@@ -187,7 +187,8 @@ The Django open-source project
187 187
     * **Community:**
188 188
       :ref:`How to get involved <internals-contributing>` |
189 189
       :ref:`The release process <internals-release-process>` |
190  
-      :ref:`Team of committers <internals-committers>`
  190
+      :ref:`Team of committers <internals-committers>` |
  191
+      :ref:`The Django source code repository <internals-svn>`
191 192
 
192 193
     * **Design philosophies:**
193 194
       :ref:`Overview <misc-design-philosophies>`
258  docs/internals/svn.txt
... ...
@@ -0,0 +1,258 @@
  1
+.. _internals-svn:
  2
+
  3
+=================================
  4
+The Django source code repository
  5
+=================================
  6
+
  7
+
  8
+When deploying a Django application into a real production
  9
+environment, you will almost always want to use `an official packaged
  10
+release of Django`_. However, if you'd like to try out in-development
  11
+code from an upcoming release or contribute to the development of
  12
+Django, you'll need to obtain a checkout from Django's source code
  13
+repository. This document covers the way the code repository is laid
  14
+out and how to work with and find things in it.
  15
+
  16
+
  17
+.. _an official packaged release of Django: http://www.djangoproject.com/download/
  18
+
  19
+
  20
+High-level overview
  21
+===================
  22
+
  23
+The Django source code repository uses `Subversion`_ to track changes
  24
+to the code over time, so you'll need a copy of the Subversion client
  25
+(a program called ``svn``) on your computer, and you'll want to
  26
+familiarize yourself with the basics of how Subversion
  27
+works. Subversion's web site offers downloads for various operating
  28
+systems, and `a free online book`_ is available to help you get up to
  29
+speed with using Subversion.
  30
+
  31
+The Django Subversion repository is located online at
  32
+`code.djangoproject.com/svn <http://code.djangoproject.com/svn/>`_. `A
  33
+friendly Web-based interface for browsing the code`_ is also
  34
+available, though when using Subversion you'll always want to use the
  35
+repository address instead. At the top level of the repository are two
  36
+directories: ``django`` contains the full source code for all Django
  37
+releases, while ``djangoproject.com`` contains the source code and
  38
+templates for for the `djangoproject.com
  39
+<http://www.djangoproject.com/>` web site. For trying out
  40
+in-development Django code, or contributing to Django, you'll always
  41
+want to check out code from some location in the ``django`` directory.
  42
+
  43
+Inside the ``django`` directory, Django's source code is organized
  44
+into three areas:
  45
+
  46
+* ``branches`` contains branched copies of Django's code, which are
  47
+  (or were) maintained for various purposes. Some branches exist to
  48
+  provide a place to develop major or experimental new features
  49
+  without affecting the rest of Django's code, while others serve to
  50
+  provide bug fixes or support for older Django releases.
  51
+
  52
+* ``tags`` contains snapshots of Django's code at various important
  53
+  points in its history; mostly these are the exact revisions from
  54
+  which packaged Django releases were produced.
  55
+
  56
+* ``trunk`` contains the main in-development code which will become
  57
+  the next packaged release of Django, and is where most development
  58
+  activity is focused.
  59
+
  60
+
  61
+.. _Subversion: http://subversion.tigris.org/
  62
+.. _a free online book: http://svnbook.red-bean.com/
  63
+.. _A friendly web-based interface for browsing the code: http://code.djangoproject.com/browser/
  64
+
  65
+
  66
+Working with Django's trunk
  67
+===========================
  68
+
  69
+If you'd like to try out the in-development code for the next release
  70
+of Django, or if you'd like to contribute to Django by fixing bugs or
  71
+developing new features, you'll want to get the code from trunk. You
  72
+can get a complete copy of this code (a "Subversion checkout") by
  73
+typing::
  74
+
  75
+    svn co http://code.djangoproject.com/svn/django/trunk/
  76
+
  77
+Note that this will get *all* of Django: in addition to the top-level
  78
+``django`` module containing Python code, you'll also get a copy of
  79
+Django's documentation, unit-test suite, packaging scripts and other
  80
+miscellaneous bits. Django's code will be present in your checkout as
  81
+a directory named ``django``.
  82
+
  83
+To try out the in-development trunk code with your own applications,
  84
+simply place the directory containing your checkout on your Python
  85
+import path. Then ``import`` statements which look for Django will find
  86
+the ``django`` module within your checkout.
  87
+
  88
+If you're going to be working on Django's code (say, to fix a bug or
  89
+develop a new feature), you can probably stop reading here and move
  90
+over to :ref:`the documentation for contributing to Django
  91
+<internals-contributing>`, which covers things like the preferred
  92
+coding style and how to generate and submit a patch.
  93
+
  94
+
  95
+Branches
  96
+========
  97
+
  98
+Django uses branches for two main purposes:
  99
+
  100
+1. Development of major or experimental features, to keep them from
  101
+   affecting progress on other work in trunk.
  102
+
  103
+2. Security and bug-fix support for older releases of Django, during
  104
+   their support lifetimes.
  105
+
  106
+
  107
+Feature-development branches
  108
+----------------------------
  109
+
  110
+Feature-development branches tend by their nature to be
  111
+temporary. Some produce successful features which are merged back into
  112
+Django's trunk to become part of an official release, but others do
  113
+not; in either case there comes a time when the branch is no longer
  114
+being actively worked on by any developer. At this point the branch is
  115
+considered closed.
  116
+
  117
+Unfortunately, Subversion has no standard way of indicating
  118
+this. Generally, you can recognize a dead branch by viewing it through
  119
+the web interface, which lists the date of the most recent change to
  120
+the branch. Branches which have gone more than a month or two with no
  121
+activity can usually be assumed to be closed. In the future, the
  122
+layout of branches in the repository may be rearranged to make it
  123
+easier to tell which branches are still active (e.g., by moving closed
  124
+or abandoned branches into the ``django/branches/attic`` directory).
  125
+
  126
+For reference, the following are branches whose code eventually became
  127
+part of Django itself, and so are no longer separately maintained:
  128
+
  129
+* ``boulder-oracle-sprint``: Added support for Oracle databases to
  130
+  Django's object-relational mapper. This has been part of Django
  131
+  since the 1.0 release.
  132
+
  133
+* ``gis``: Added support for geographic/spatial queries to Django's
  134
+  object-relational mapper. This has been part of Django since the 1.0
  135
+  release, as the bundled application ``django.contrib.gis``.
  136
+
  137
+* ``i18n``: Added :ref:`internationalization support <topics-i18n>` to
  138
+  Django. This has been part of Django since the 0.90 release.
  139
+
  140
+* ``magic-removal``: A major refactoring of both the internals and
  141
+  public APIs of Django's object-relational mapper. This has been part
  142
+  of Django since the 0.95 release.
  143
+
  144
+* ``multi-auth``: A refactoring of :ref:`Django's bundled
  145
+  authentication framework <topics-auth>` which added support for
  146
+  :ref:`authentication backends <authentication-backends>`. This has
  147
+  been part of Django since the 0.95 release.
  148
+
  149
+* ``new-admin``: A refactoring of :ref:`Django's bundled
  150
+  administrative application <ref-contrib-admin>`. This became part of
  151
+  Django as of the 0.91 release, but was superseded by another
  152
+  refactoring (see next listing) prior to the Django 1.0 release.
  153
+
  154
+* ``newforms-admin``: The second refactoring of Django's bundled
  155
+  administrative application. This became part of Django as of the 1.0
  156
+  release, and is the basis of the current incarnation of
  157
+  ``django.contrib.admin``.
  158
+
  159
+* ``queryset-refactor``: A refactoring of the internals of Django's
  160
+  object-relational mapper. This became part of Django as of the 1.0
  161
+  release.
  162
+
  163
+* ``unicode``: A refactoring of Django's internals to consistently use
  164
+  Unicode-based strings in most places within Django and Django
  165
+  applications. This became part of Django as of the 1.0 release.
  166
+
  167
+Additionally, the following branches are closed, but their code was
  168
+never merged into Django and the features they aimed to implement
  169
+were never finished:
  170
+
  171
+* ``full-history``
  172
+
  173
+* ``generic-auth``
  174
+
  175
+* ``multiple-db-support``
  176
+
  177
+* ``per-object-permissions``
  178
+
  179
+* ``schema-evolution``
  180
+
  181
+* ``schema-evolution-ng``
  182
+
  183
+* ``search-api``
  184
+
  185
+* ``sqlalchemy``
  186
+
  187
+
  188
+Support and bugfix branches
  189
+---------------------------
  190
+
  191
+In addition to fixing bugs in current trunk, the Django project
  192
+provides official bug-fix support for the most recent released version
  193
+of Django, and security support for the two most recently-released
  194
+versions of Django. This support is provided via branches in which the
  195
+necessary bug or security fixes are applied; the branches are then
  196
+used as the basis for issuing bugfix or security releases.
  197
+
  198
+As of the Django 1.0 release, these branches can be found in the
  199
+repository in the directory ``django/branches/releases``, and new branches
  200
+will be created there approximately one month after each new Django
  201
+release. For example, shortly after the release of Django 1.0, the
  202
+branch ``django/branches/releases/1.0.X`` was created to receive bug
  203
+fixes, and shortly after the release of Django 1.1 the branch
  204
+``django/branches/releases/1.1.X`` will be created.
  205
+
  206
+Prior to the Django 1.0 release, these branches were maintaind within
  207
+the top-level ``django/branches`` directory, and so the following
  208
+branches exist there and provided support for older Django releases:
  209
+
  210
+* ``0.90-bugfixes``
  211
+
  212
+* ``0.91-bugfixes``
  213
+
  214
+* ``0.95-bugfixes``
  215
+
  216
+* ``0.96-bugfixes``
  217
+
  218
+Official support for those releases has expired, and so they no longer
  219
+receive direct maintenance from the Django project. However, the
  220
+branches continue to exist and interested community members have
  221
+occasionally used them to provide unofficial support for old Django
  222
+releases.
  223
+
  224
+
  225
+Tags
  226
+====
  227
+
  228
+The directory ``django/tags`` within the repository contains complete
  229
+copies of the Django source code as it existed at various points in
  230
+its history. These "tagged" copies of Django are *never* changed or
  231
+updated; new tags may be added as needed, but once added they are
  232
+considered read-only and serve as useful guides to Django's
  233
+development history.
  234
+
  235
+Within ``django/tags/releases`` are copies of the code which formed each
  236
+packaged release of Django, and each tag is named with the version
  237
+number of the release to which it corresponds. So, for example,
  238
+``django/tags/releases/1.1`` is a complete copy of the code which was
  239
+packaged as the Django 1.1 release.
  240
+
  241
+Within ``django/tags/notable_moments`` are copies of the Django code from
  242
+points which do not directly correspond to releases, but which are
  243
+nonetheless important historical milestones for Django
  244
+development. The current "notable moments" marked there are:
  245
+
  246
+* ``ipo``: Django's code as it existed at the moment Django was first
  247
+  publicly announced in 2005.
  248
+
  249
+* ``pre-magic-removal``: The state of Django's code just before the
  250
+  merging of the ``magic-removal`` branch (described above), which
  251
+  significantly updated Django's object-relational mapper.
  252
+
  253
+* ``pre-newforms-admin``: The state of Django's code just before the
  254
+  merging of the ``newforms-admin`` branch (see above), which
  255
+  significantly updated Django's bundled administrative application.
  256
+
  257
+* Tags corresponding to each of the alpha, beta and release-candidate
  258
+  packages in the run up to the Django 1.0 release.

0 notes on commit 5eda3a1

Please sign in to comment.
Something went wrong with that request. Please try again.