PageRenderTime 380ms CodeModel.GetById 120ms app.highlight 8ms RepoModel.GetById 131ms app.codeStats 1ms

/docs/internals/svn.txt

https://code.google.com/p/mango-py/
Plain Text | 254 lines | 185 code | 69 blank | 0 comment | 0 complexity | 20ada7749943ec5564af0c9a9897f381 MD5 | raw file
  1=================================
  2The Django source code repository
  3=================================
  4
  5
  6When deploying a Django application into a real production
  7environment, you will almost always want to use `an official packaged
  8release of Django`_. However, if you'd like to try out in-development
  9code from an upcoming release or contribute to the development of
 10Django, you'll need to obtain a checkout from Django's source code
 11repository. This document covers the way the code repository is laid
 12out 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
 18High-level overview
 19===================
 20
 21The Django source code repository uses `Subversion`_ to track changes
 22to 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
 24familiarize yourself with the basics of how Subversion
 25works. Subversion's Web site offers downloads for various operating
 26systems, and `a free online book`_ is available to help you get up to
 27speed with using Subversion.
 28
 29The Django Subversion repository is located online at
 30`code.djangoproject.com/svn <http://code.djangoproject.com/svn/>`_. `A
 31friendly Web-based interface for browsing the code`_ is also
 32available, though when using Subversion you'll always want to use the
 33repository address instead. At the top level of the repository are two
 34directories: ``django`` contains the full source code for all Django
 35releases, while ``djangoproject.com`` contains the source code and
 36templates for the `djangoproject.com <http://www.djangoproject.com/>`_
 37Web site. For trying out in-development Django code, or contributing
 38to Django, you'll always want to check out code from some location in
 39the ``django`` directory.
 40
 41Inside the ``django`` directory, Django's source code is organized
 42into 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
 64Working with Django's trunk
 65===========================
 66
 67If you'd like to try out the in-development code for the next release
 68of Django, or if you'd like to contribute to Django by fixing bugs or
 69developing new features, you'll want to get the code from trunk. You
 70can get a complete copy of this code (a "Subversion checkout") by
 71typing::
 72
 73    svn co http://code.djangoproject.com/svn/django/trunk/
 74
 75Note 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
 77Django's documentation, unit-test suite, packaging scripts and other
 78miscellaneous bits. Django's code will be present in your checkout as
 79a directory named ``django``.
 80
 81To try out the in-development trunk code with your own applications,
 82simply place the directory containing your checkout on your Python
 83import path. Then ``import`` statements which look for Django will find
 84the ``django`` module within your checkout.
 85
 86If you're going to be working on Django's code (say, to fix a bug or
 87develop a new feature), you can probably stop reading here and move
 88over to :doc:`the documentation for contributing to Django
 89</internals/contributing>`, which covers things like the preferred
 90coding style and how to generate and submit a patch.
 91
 92
 93Branches
 94========
 95
 96Django uses branches for two main purposes:
 97
 981. Development of major or experimental features, to keep them from
 99   affecting progress on other work in trunk.
100
1012. Security and bug-fix support for older releases of Django, during
102   their support lifetimes.
103
104
105Feature-development branches
106----------------------------
107
108Feature-development branches tend by their nature to be
109temporary. Some produce successful features which are merged back into
110Django's trunk to become part of an official release, but others do
111not; in either case there comes a time when the branch is no longer
112being actively worked on by any developer. At this point the branch is
113considered closed.
114
115Unfortunately, Subversion has no standard way of indicating this. As a
116workaround, branches of Django which are closed and no longer
117maintained are moved into the directory ``django/branches/attic``.
118
119For reference, the following are branches whose code eventually became
120part 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
160Additionally, the following branches are closed, but their code was
161never merged into Django and the features they aimed to implement
162were 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
180All of the above-mentioned branches now reside in
181``django/branches/attic``.
182
183
184Support and bugfix branches
185---------------------------
186
187In addition to fixing bugs in current trunk, the Django project
188provides official bug-fix support for the most recent released version
189of Django, and security support for the two most recently-released
190versions of Django. This support is provided via branches in which the
191necessary bug or security fixes are applied; the branches are then
192used as the basis for issuing bugfix or security releases.
193
194As of the Django 1.0 release, these branches can be found in the
195repository in the directory ``django/branches/releases``, and new branches
196will be created there approximately one month after each new Django
197release. For example, shortly after the release of Django 1.0, the
198branch ``django/branches/releases/1.0.X`` was created to receive bug
199fixes, and shortly after the release of Django 1.1 the branch
200``django/branches/releases/1.1.X`` was created.
201
202Prior to the Django 1.0 release, these branches were maintained within
203the top-level ``django/branches`` directory, and so the following
204branches 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
214Official support for those releases has expired, and so they no longer
215receive direct maintenance from the Django project. However, the
216branches continue to exist and interested community members have
217occasionally used them to provide unofficial support for old Django
218releases.
219
220
221Tags
222====
223
224The directory ``django/tags`` within the repository contains complete
225copies of the Django source code as it existed at various points in
226its history. These "tagged" copies of Django are *never* changed or
227updated; new tags may be added as needed, but once added they are
228considered read-only and serve as useful guides to Django's
229development history.
230
231Within ``django/tags/releases`` are copies of the code which formed each
232packaged release of Django, and each tag is named with the version
233number 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
235packaged as the Django 1.1 release.
236
237Within ``django/tags/notable_moments`` are copies of the Django code from
238points which do not directly correspond to releases, but which are
239nonetheless important historical milestones for Django
240development. 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.