"Fossies" - the Fresh Open Source Software Archive

Member "Django-1.11.25/docs/internals/git.txt" (1 Oct 2019, 11219 Bytes) of package /linux/www/Django-1.11.25.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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 * ``master`` 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 * ``soc20XX/<project>`` branches were used by students who worked on Django
   43   during the 2009 and 2010 Google Summer of Code programs.
   44 
   45 * ``attic/<project>`` branches were used to develop major or experimental new
   46   features without affecting the rest of Django's code.
   47 
   48 The Git repository also contains `tags`_. These are the exact revisions from
   49 which packaged Django releases were produced, since version 1.0.
   50 
   51 The source code for the `Djangoproject.com <https://www.djangoproject.com/>`_
   52 website can be found at `github.com/django/djangoproject.com
   53 <https://github.com/django/djangoproject.com>`_.
   54 
   55 .. _Git: https://git-scm.com/
   56 .. _documentation: https://git-scm.com/documentation
   57 .. _branches: https://github.com/django/django/branches
   58 .. _tags: https://github.com/django/django/tags
   59 
   60 The master branch
   61 =================
   62 
   63 If you'd like to try out the in-development code for the next release of
   64 Django, or if you'd like to contribute to Django by fixing bugs or developing
   65 new features, you'll want to get the code from the master branch.
   66 
   67 Note that this will get *all* of Django: in addition to the top-level
   68 ``django`` module containing Python code, you'll also get a copy of Django's
   69 documentation, test suite, packaging scripts and other miscellaneous bits.
   70 Django's code will be present in your clone as a directory named
   71 ``django``.
   72 
   73 To try out the in-development code with your own applications, simply place
   74 the directory containing your clone on your Python import path. Then
   75 ``import`` statements which look for Django will find the ``django`` module
   76 within your clone.
   77 
   78 If you're going to be working on Django's code (say, to fix a bug or
   79 develop a new feature), you can probably stop reading here and move
   80 over to :doc:`the documentation for contributing to Django
   81 </internals/contributing/index>`, which covers things like the preferred
   82 coding style and how to generate and submit a patch.
   83 
   84 Other branches
   85 ==============
   86 
   87 Django uses branches to prepare for releases of Django.
   88 
   89 In the past when Django was hosted on Subversion, branches were also used for
   90 feature development. Now Django is hosted on Git and feature development is
   91 done on contributor's forks, but the Subversion feature branches remain in Git
   92 for historical reference.
   93 
   94 Stable branches
   95 ---------------
   96 
   97 These branches can be found in the repository as ``stable/A.B.x``
   98 branches and will be created right after the first alpha is tagged.
   99 
  100 For example, immediately after *Django 1.5 alpha 1* was tagged, the branch
  101 ``stable/1.5.x`` was created and all further work on preparing the code for the
  102 final 1.5 release was done there.
  103 
  104 These branches also provide limited bugfix support for the most recent released
  105 version of Django and security support for the two most recently-released
  106 versions of Django.
  107 
  108 For example, after the release of Django 1.5, the branch ``stable/1.5.x``
  109 receives only fixes for security and critical stability bugs, which are
  110 eventually released as Django 1.5.1 and so on, ``stable/1.4.x`` receives only
  111 security fixes, and ``stable/1.3.x`` no longer receives any updates.
  112 
  113 .. admonition:: Historical information
  114 
  115     This policy for handling ``stable/A.B.x`` branches was adopted starting
  116     with the Django 1.5 release cycle.
  117 
  118     Previously, these branches weren't created until right after the releases
  119     and the stabilization work occurred on the main repository branch. Thus,
  120     no new features development work for the next release of Django could be
  121     committed until the final release happened.
  122 
  123     For example, shortly after the release of Django 1.3 the branch
  124     ``stable/1.3.x`` was created. Official support for that release has expired,
  125     and so it no longer receives direct maintenance from the Django project.
  126     However, that and all other similarly named branches continue to exist and
  127     interested community members have occasionally used them to provide
  128     unofficial support for old Django releases.
  129 
  130 Feature-development branches
  131 ----------------------------
  132 
  133 .. admonition:: Historical information
  134 
  135     Since Django moved to Git in 2012, anyone can clone the repository and
  136     create their own branches, alleviating the need for official branches in
  137     the source code repository.
  138 
  139     The following section is mostly useful if you're exploring the repository's
  140     history, for example if you're trying to understand how some features were
  141     designed.
  142 
  143 Feature-development branches tend by their nature to be temporary. Some
  144 produce successful features which are merged back into Django's master to
  145 become part of an official release, but others do not; in either case there
  146 comes a time when the branch is no longer being actively worked on by any
  147 developer. At this point the branch is considered closed.
  148 
  149 Unfortunately, Django used to be maintained with the Subversion revision
  150 control system, that has no standard way of indicating this. As a workaround,
  151 branches of Django which are closed and no longer maintained were moved into
  152 ``attic``.
  153 
  154 For reference, the following are branches whose code eventually became
  155 part of Django itself, and so are no longer separately maintained:
  156 
  157 * ``boulder-oracle-sprint``: Added support for Oracle databases to
  158   Django's object-relational mapper. This has been part of Django
  159   since the 1.0 release.
  160 
  161 * ``gis``: Added support for geographic/spatial queries to Django's
  162   object-relational mapper. This has been part of Django since the 1.0
  163   release, as the bundled application ``django.contrib.gis``.
  164 
  165 * ``i18n``: Added :doc:`internationalization support </topics/i18n/index>` to
  166   Django. This has been part of Django since the 0.90 release.
  167 
  168 * ``magic-removal``: A major refactoring of both the internals and
  169   public APIs of Django's object-relational mapper. This has been part
  170   of Django since the 0.95 release.
  171 
  172 * ``multi-auth``: A refactoring of :doc:`Django's bundled
  173   authentication framework </topics/auth/index>` which added support for
  174   :ref:`authentication backends <authentication-backends>`. This has
  175   been part of Django since the 0.95 release.
  176 
  177 * ``new-admin``: A refactoring of :doc:`Django's bundled
  178   administrative application </ref/contrib/admin/index>`. This became part of
  179   Django as of the 0.91 release, but was superseded by another
  180   refactoring (see next listing) prior to the Django 1.0 release.
  181 
  182 * ``newforms-admin``: The second refactoring of Django's bundled
  183   administrative application. This became part of Django as of the 1.0
  184   release, and is the basis of the current incarnation of
  185   ``django.contrib.admin``.
  186 
  187 * ``queryset-refactor``: A refactoring of the internals of Django's
  188   object-relational mapper. This became part of Django as of the 1.0
  189   release.
  190 
  191 * ``unicode``: A refactoring of Django's internals to consistently use
  192   Unicode-based strings in most places within Django and Django
  193   applications. This became part of Django as of the 1.0 release.
  194 
  195 When Django moved from SVN to Git, the information about branch merges wasn't
  196 preserved in the source code repository. This means that the ``master`` branch
  197 of Django doesn't contain merge commits for the above branches.
  198 
  199 However, this information is `available as a grafts file`_. You can restore it
  200 by putting the following lines in ``.git/info/grafts`` in your local clone::
  201 
  202   ac64e91a0cadc57f4bc5cd5d66955832320ca7a1 553a20075e6991e7a60baee51ea68c8adc520d9a 0cb8e31823b2e9f05c4ae868c19f5f38e78a5f2e
  203   79e68c225b926302ebb29c808dda8afa49856f5c d0f57e7c7385a112cb9e19d314352fc5ed5b0747 aa239e3e5405933af6a29dac3cf587b59a099927
  204   5cf8f684237ab5addaf3549b2347c3adf107c0a7 cb45fd0ae20597306cd1f877efc99d9bd7cbee98 e27211a0deae2f1d402537f0ebb64ad4ccf6a4da
  205   f69cf70ed813a8cd7e1f963a14ae39103e8d5265 d5dbeaa9be359a4c794885c2e9f1b5a7e5e51fb8 d2fcbcf9d76d5bb8a661ee73dae976c74183098b
  206   aab3a418ac9293bb4abd7670f65d930cb0426d58 4ea7a11659b8a0ab07b0d2e847975f7324664f10 adf4b9311d5d64a2bdd58da50271c121ea22e397
  207   ff60c5f9de3e8690d1e86f3e9e3f7248a15397c8 7ef212af149540aa2da577a960d0d87029fd1514 45b4288bb66a3cda401b45901e85b645674c3988
  208   9dda4abee1225db7a7b195b84c915fdd141a7260 4fe5c9b7ee09dc25921918a6dbb7605edb374bc9 3a7c14b583621272d4ef53061287b619ce3c290d
  209   a19ed8aea395e8e07164ff7d85bd7dff2f24edca dc375fb0f3b7fbae740e8cfcd791b8bccb8a4e66 42ea7a5ce8aece67d16c6610a49560c1493d4653
  210   9c52d56f6f8a9cdafb231adf9f4110473099c9b5 c91a30f00fd182faf8ca5c03cd7dbcf8b735b458 4a5c5c78f2ecd4ed8859cd5ac773ff3a01bccf96
  211   953badbea5a04159adbfa970f5805c0232b6a401 4c958b15b250866b70ded7d82aa532f1e57f96ae 5664a678b29ab04cad425c15b2792f4519f43928
  212   471596fc1afcb9c6258d317c619eaf5fd394e797 4e89105d64bb9e04c409139a41e9c7aac263df4c 3e9035a9625c8a8a5e88361133e87ce455c4fc13
  213   9233d0426537615e06b78d28010d17d5a66adf44 6632739e94c6c38b4c5a86cf5c80c48ae50ac49f 18e151bc3f8a85f2766d64262902a9fcad44d937
  214 
  215 .. _available as a grafts file: https://github.com/ramiro/django-git-grafts
  216 
  217 Additionally, the following branches are closed, but their code was
  218 never merged into Django and the features they aimed to implement
  219 were never finished:
  220 
  221 * ``full-history``
  222 
  223 * ``generic-auth``
  224 
  225 * ``multiple-db-support``
  226 
  227 * ``per-object-permissions``
  228 
  229 * ``schema-evolution``
  230 
  231 * ``schema-evolution-ng``
  232 
  233 * ``search-api``
  234 
  235 * ``sqlalchemy``
  236 
  237 All of the above-mentioned branches now reside in ``attic``.
  238 
  239 Finally, the repository contains ``soc2009/xxx`` and ``soc2010/xxx`` feature
  240 branches, used for Google Summer of Code projects.
  241 
  242 Tags
  243 ====
  244 
  245 Each Django release is tagged and signed by the releaser.
  246 
  247 The tags can be found on GitHub's `tags`_ page.
  248 
  249 .. _tags: https://github.com/django/django/tags