PageRenderTime 1129ms CodeModel.GetById 1111ms RepoModel.GetById 1ms app.codeStats 0ms

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