mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-04 02:48:35 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Fixed #16469 -- Improved documentation of Django internals, including the new backport policy. Many thanks to Aymeric Augustin.

Browse source 
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16548 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jannis Leidel 2011-07-19 13:16:09 +00:00
parent 8f7b5024b2
commit 127b7fdce8
13 changed files with 441 additions and 369 deletions
Download patch file Download diff file Expand all files Collapse all files

17
docs/internals/contributing/writing-code/branch-policy.txt
View file

@ -146,15 +146,14 @@ Alternatively, you can use a symlink called ``django`` that points to the
location of the branch's ``django`` package. If you want to switch back, just
change the symlink to point to the old code.
A third option is to use a `path file`_ (``<something>.pth``) which should
work on all systems (including Windows, which doesn't have symlinks
available). First, make sure there are no files, directories or symlinks named
``django`` in your ``site-packages`` directory. Then create a text file named
``django.pth`` and save it to your ``site-packages`` directory. That file
should contain a path to your copy of Django on a single line and optional
comments. Here is an example that points to multiple branches. Just uncomment
the line for the branch you want to use ('Trunk' in this example) and make
sure all other lines are commented::
A third option is to use a `path file`_ (``<something>.pth``). First, make sure
there are no files, directories or symlinks named ``django`` in your
``site-packages`` directory. Then create a text file named ``django.pth`` and
save it to your ``site-packages`` directory. That file should contain a path to
your copy of Django on a single line and optional comments. Here is an example
that points to multiple branches. Just uncomment the line for the branch you
want to use ('Trunk' in this example) and make sure all other lines are
commented::
# Trunk is a svn checkout of:
# http://code.djangoproject.com/svn/django/trunk/

15
docs/internals/contributing/writing-code/coding-style.txt
View file

@ -9,7 +9,7 @@ Python style
* Unless otherwise specified, follow :pep:`8`.
You could use a tool like `pep8.py`_ to check for some problems in this
You could use a tool like `pep8`_ to check for some problems in this
area, but remember that PEP 8 is only a guide, so respect the style of
the surrounding code as a primary goal.
@ -171,9 +171,9 @@ That means that the ability for third parties to import the module at the top
level is incompatible with the ability to configure the settings object
manually, or makes it very difficult in some circumstances.
Instead of the above code, a level of laziness or indirection must be used,
such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy``
or ``lambda``.
Instead of the above code, a level of laziness or indirection must be used, such
as :class:`django.utils.functional.LazyObject`,
:func:`django.utils.functional.lazy` or ``lambda``.
Miscellaneous
-------------
@ -181,10 +181,15 @@ Miscellaneous
* Mark all strings for internationalization; see the :doc:`i18n
documentation </topics/i18n/index>` for details.
* Remove ``import`` statements that are no longer used when you change code.
The most common tools for this task are `pyflakes`_ and `pylint`_.
* Please don't put your name in the code you contribute. Our policy is to
keep contributors' names in the ``AUTHORS`` file distributed with Django
-- not scattered throughout the codebase itself. Feel free to include a
change to the ``AUTHORS`` file in your patch if you make more than a
single trivial change.
.. _pep8.py: http://pypi.python.org/pypi/pep8/
.. _pep8: http://pypi.python.org/pypi/pep8
.. _pyflakes: http://pypi.python.org/pypi/pyflakes
.. _pylint: http://pypi.python.org/pypi/pylint

14
docs/internals/contributing/writing-code/submitting-patches.txt
View file

@ -84,7 +84,7 @@ Patch style
Patches in ``git diff`` format are also acceptable.
* When creating patches, always run ``svn diff`` from the top-level
``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,
``trunk`` directory -- i.e. the one that contains ``django``, ``docs``,
``tests``, ``AUTHORS``, etc. This makes it easy for other people to
apply your patches.
@ -101,8 +101,8 @@ Patch style
* The code required to fix a problem or add a feature is an essential part
of a patch, but it is not the only part. A good patch should also
include a regression test to validate the behavior that has been fixed
(and prevent the problem from arising again).
include a regression test to validate the behavior that has been fixed,
to prevent the problem from arising again.
* If the code associated with a patch adds a new feature, or modifies
behavior of an existing feature, the patch should also contain
@ -130,13 +130,13 @@ Serving compressed or "minified" versions of javascript files is considered
best practice in this regard.
To that end, patches for javascript files should include both the original
code for future development (e.g. "foo.js"), and a compressed version for
production use (e.g. "foo.min.js"). Any links to the file in the codebase
code for future development (e.g. ``foo.js``), and a compressed version for
production use (e.g. ``foo.min.js``). Any links to the file in the codebase
should point to the compressed version.
To simplify the process of providing optimized javascript code, Django
includes a handy script which should be used to create a "minified" version.
This script is located at ``/contrib/admin/media/js/compress.py``.
This script is located at ``django/contrib/admin/static/js/compress.py``.
Behind the scenes, ``compress.py`` is a front-end for Google's
`Closure Compiler`_ which is written in Java. However, the Closure Compiler
@ -148,7 +148,7 @@ The Closure Compiler library requires Java version 6 or higher (Java 1.6 or
higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with
Java 1.6 by default, so it may be necessary to upgrade your Java installation
before the tool will be functional. Also note that even after upgrading Java,
the default `/usr/bin/java` command may remain linked to the previous Java
the default ``/usr/bin/java`` command may remain linked to the previous Java
binary, so relinking that command may be necessary as well.
Please don't forget to run ``compress.py`` and include the ``diff`` of the

25
docs/internals/contributing/writing-code/unit-tests.txt
View file

@ -3,13 +3,13 @@ Unit tests
==========
Django comes with a test suite of its own, in the ``tests`` directory of the
Django tarball. It's our policy to make sure all tests pass at all times.
code base. It's our policy to make sure all tests pass at all times.
The tests cover:
* Models and the database API (``tests/modeltests/``).
* Everything else in core Django code (``tests/regressiontests``)
* Contrib apps (``django/contrib/<contribapp>/tests``, see below)
* Models and the database API (``tests/modeltests``),
* Everything else in core Django code (``tests/regressiontests``),
* :ref:`contrib-apps` (``django/contrib/<app>/tests``).
We appreciate any and all contributions to the test suite!
@ -105,8 +105,8 @@ internationalization, type:
./runtests.py --settings=path.to.settings generic_relations i18n
How do you find out the names of individual tests? Look in
``tests/modeltests`` and ``tests/regressiontests`` -- each directory name
there is the name of a test.
``tests/modeltests`` and ``tests/regressiontests`` — each directory name
there is the name of a test. Contrib app names are also valid test names.
If you just want to run a particular class of tests, you can specify a list of
paths to individual test classes. For example, to run the ``TranslationTests``
@ -150,16 +150,17 @@ associated tests will be skipped.
.. _memcached: http://www.danga.com/memcached/
.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
.. _contrib-apps:
Contrib apps
------------
Tests for apps in ``django/contrib/`` go in their respective directories under
``django/contrib/``, in a ``tests.py`` file. (You can split the tests over
multiple modules by using a ``tests`` directory in the normal Python way.)
Tests for contrib apps go in their respective directories under
``django/contrib``, in a ``tests.py`` file. You can split the tests over
multiple modules by using a ``tests`` directory in the normal Python way.
For the tests to be found, a ``models.py`` file must exist (it doesn't
have to have anything in it). If you have URLs that need to be
mapped, put them in ``tests/urls.py``.
For the tests to be found, a ``models.py`` file must exist, even if it's empty.
If you have URLs that need to be mapped, put them in ``tests/urls.py``.
To run tests for just one contrib app (e.g. ``markup``), use the same
method as above::