Debian Codegraph @

docs/internals/git.txt

raw
1 =================================
2 The Django source code repository
3 =================================
4
5 When deploying a Django application into a real production environment, you
6 will almost always want to use `an official packaged release of Django`_.
7
8 However, if you'd like to try out in-development code from an upcoming release
9 or contribute to the development of Django, you'll need to obtain a clone of
10 Django's source code repository.
11
12 This document covers the way the code repository is laid out and how to work
13 with and find things in it.
14
15 .. _an official packaged release of Django: https://www.djangoproject.com/download/
16
17 High-level overview
18 ===================
19
20 The Django source code repository uses `Git`_ to track changes to the code
21 over time, so you'll need a copy of the Git client (a program called ``git``)
22 on your computer, and you'll want to familiarize yourself with the basics of
23 how Git works.
24
25 Git's website offers downloads for various operating systems. The site also
26 contains vast amounts of `documentation`_.
27
28 The Django Git repository is located online at `github.com/django/django
29 <https://github.com/django/django>`_. It contains the full source code for all
30 Django releases, which you can browse online.
31
32 The Git repository includes several `branches`_:
33
34 * ``main`` contains the main in-development code which will become
35 the next packaged release of Django. This is where most development
36 activity is focused.
37
38 * ``stable/A.B.x`` are the branches where release preparation work happens.
39 They are also used for bugfix and security releases which occur as necessary
40 after the initial release of a feature version.
41
42 The Git repository also contains `tags`_. These are the exact revisions from
43 which packaged Django releases were produced, since version 1.0.
44
45 A number of tags also exist under the ``archive/`` prefix for :ref:`archived
46 work<archived-feature-development-work>`.
47
48 The source code for the `Djangoproject.com <https://www.djangoproject.com/>`_
49 website can be found at `github.com/django/djangoproject.com
50 <https://github.com/django/djangoproject.com>`_.
51
52 .. _Git: https://git-scm.com/
53 .. _documentation: https://git-scm.com/doc
54 .. _branches: https://github.com/django/django/branches
55 .. _tags: https://github.com/django/django/tags
56
57 The main branch
58 ===============
59
60 If you'd like to try out the in-development code for the next release of
61 Django, or if you'd like to contribute to Django by fixing bugs or developing
62 new features, you'll want to get the code from the main branch.
63
64 .. note::
65
66 Prior to March 2021, the main branch was called ``master``.
67
68 Note that this will get *all* of Django: in addition to the top-level
69 ``django`` module containing Python code, you'll also get a copy of Django's
70 documentation, test suite, packaging scripts and other miscellaneous bits.
71 Django's code will be present in your clone as a directory named
72 ``django``.
73
74 To try out the in-development code with your own applications, place the
75 directory containing your clone on your Python import path. Then ``import``
76 statements which look for Django will find the ``django`` module within your
77 clone.
78
79 If you're going to be working on Django's code (say, to fix a bug or
80 develop a new feature), you can probably stop reading here and move
81 over to :doc:`the documentation for contributing to Django
82 </internals/contributing/index>`, which covers things like the preferred
83 coding style and how to generate and submit a patch.
84
85 Stable branches
86 ===============
87
88 Django uses branches to prepare for releases of Django. Each major release
89 series has its own stable branch.
90
91 These branches can be found in the repository as ``stable/A.B.x``
92 branches and will be created right after the first alpha is tagged.
93
94 For example, immediately after *Django 1.5 alpha 1* was tagged, the branch
95 ``stable/1.5.x`` was created and all further work on preparing the code for the
96 final 1.5 release was done there.
97
98 These branches also provide bugfix and security support as described in
99 :ref:`supported-versions-policy`.
100
101 For example, after the release of Django 1.5, the branch ``stable/1.5.x``
102 receives only fixes for security and critical stability bugs, which are
103 eventually released as Django 1.5.1 and so on, ``stable/1.4.x`` receives only
104 security and data loss fixes, and ``stable/1.3.x`` no longer receives any
105 updates.
106
107 .. admonition:: Historical information
108
109 This policy for handling ``stable/A.B.x`` branches was adopted starting
110 with the Django 1.5 release cycle.
111
112 Previously, these branches weren't created until right after the releases
113 and the stabilization work occurred on the main repository branch. Thus,
114 no new feature development work for the next release of Django could be
115 committed until the final release happened.
116
117 For example, shortly after the release of Django 1.3 the branch
118 ``stable/1.3.x`` was created. Official support for that release has expired,
119 and so it no longer receives direct maintenance from the Django project.
120 However, that and all other similarly named branches continue to exist, and
121 interested community members have occasionally used them to provide
122 unofficial support for old Django releases.
123
124 Tags
125 ====
126
127 Each Django release is tagged and signed by the releaser.
128
129 The tags can be found on GitHub's `tags`_ page.
130
131 .. _tags: https://github.com/django/django/tags
132
133 .. _archived-feature-development-work:
134
135 Archived feature-development work
136 ---------------------------------
137
138 .. admonition:: Historical information
139
140 Since Django moved to Git in 2012, anyone can clone the repository and
141 create their own branches, alleviating the need for official branches in
142 the source code repository.
143
144 The following section is mostly useful if you're exploring the repository's
145 history, for example if you're trying to understand how some features were
146 designed.
147
148 Feature-development branches tend by their nature to be temporary. Some
149 produce successful features which are merged back into Django's main branch to
150 become part of an official release, but others do not; in either case, there
151 comes a time when the branch is no longer being actively worked on by any
152 developer. At this point the branch is considered closed.
153
154 Django used to be maintained with the Subversion revision control system, that
155 has no standard way of indicating this. As a workaround, branches of Django
156 which are closed and no longer maintained were moved into ``attic``.
157
158 A number of tags exist under the ``archive/`` prefix to maintain a reference to
159 this and other work of historical interest.
160
161 The following tags under the ``archive/attic/`` prefix reference the tip of
162 branches whose code eventually became part of Django itself:
163
164 * ``boulder-oracle-sprint``: Added support for Oracle databases to
165 Django's object-relational mapper. This has been part of Django
166 since the 1.0 release.
167
168 * ``gis``: Added support for geographic/spatial queries to Django's
169 object-relational mapper. This has been part of Django since the 1.0
170 release, as the bundled application ``django.contrib.gis``.
171
172 * ``i18n``: Added :doc:`internationalization support </topics/i18n/index>` to
173 Django. This has been part of Django since the 0.90 release.
174
175 * ``magic-removal``: A major refactoring of both the internals and
176 public APIs of Django's object-relational mapper. This has been part
177 of Django since the 0.95 release.
178
179 * ``multi-auth``: A refactoring of :doc:`Django's bundled
180 authentication framework </topics/auth/index>` which added support for
181 :ref:`authentication backends <authentication-backends>`. This has
182 been part of Django since the 0.95 release.
183
184 * ``new-admin``: A refactoring of :doc:`Django's bundled
185 administrative application </ref/contrib/admin/index>`. This became part of
186 Django as of the 0.91 release, but was superseded by another
187 refactoring (see next listing) prior to the Django 1.0 release.
188
189 * ``newforms-admin``: The second refactoring of Django's bundled
190 administrative application. This became part of Django as of the 1.0
191 release, and is the basis of the current incarnation of
192 ``django.contrib.admin``.
193
194 * ``queryset-refactor``: A refactoring of the internals of Django's
195 object-relational mapper. This became part of Django as of the 1.0
196 release.
197
198 * ``unicode``: A refactoring of Django's internals to consistently use
199 Unicode-based strings in most places within Django and Django
200 applications. This became part of Django as of the 1.0 release.
201
202 Additionally, the following tags under the ``archive/attic/`` prefix reference
203 the tips of branches that were closed, but whose code was never merged into
204 Django, and the features they aimed to implement were never finished:
205
206 * ``full-history``
207
208 * ``generic-auth``
209
210 * ``multiple-db-support``
211
212 * ``per-object-permissions``
213
214 * ``schema-evolution``
215
216 * ``schema-evolution-ng``
217
218 * ``search-api``
219
220 * ``sqlalchemy``
221
222 Finally, under the ``archive/`` prefix, the repository contains
223 ``soc20XX/<project>`` tags referencing the tip of branches that were used by
224 students who worked on Django during the 2009 and 2010 Google Summer of Code
225 programs.