From 127b7fdce8e89e5a8e349a7de817050ac5a64719 Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Tue, 19 Jul 2011 13:16:09 +0000 Subject: Fixed #16469 -- Improved documentation of Django internals, including the new backport policy. Many thanks to Aymeric Augustin. git-svn-id: http://code.djangoproject.com/svn/django/trunk@16548 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- .../contributing/writing-code/branch-policy.txt | 17 +++++++-------- .../contributing/writing-code/coding-style.txt | 15 ++++++++----- .../writing-code/submitting-patches.txt | 14 ++++++------ .../contributing/writing-code/unit-tests.txt | 25 +++++++++++----------- 4 files changed, 38 insertions(+), 33 deletions(-) (limited to 'docs/internals/contributing/writing-code') diff --git a/docs/internals/contributing/writing-code/branch-policy.txt b/docs/internals/contributing/writing-code/branch-policy.txt index 940b96f7ac..8bda15a3d4 100644 --- a/docs/internals/contributing/writing-code/branch-policy.txt +++ b/docs/internals/contributing/writing-code/branch-policy.txt @@ -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`_ (``.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`_ (``.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/ diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 616550dcef..7a07735616 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -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 ` 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 diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index 4eb74e1b1e..8190206106 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -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 diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 3789172f99..cffcbd9371 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -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//tests``, see below) + * Models and the database API (``tests/modeltests``), + * Everything else in core Django code (``tests/regressiontests``), + * :ref:`contrib-apps` (``django/contrib//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:: -- cgit v1.3