diff options
| author | Luke Plant <L.Plant.98@cantab.net> | 2011-10-14 00:12:01 +0000 |
|---|---|---|
| committer | Luke Plant <L.Plant.98@cantab.net> | 2011-10-14 00:12:01 +0000 |
| commit | d1e5c55258d624058a93c8cacdb1f25ae7857554 (patch) | |
| tree | dca859edc2229f68b7511687aa8b333378786633 /docs/internals/contributing/writing-code | |
| parent | 5109ac370928a5924887424b6d6c803038fcb691 (diff) | |
Fixed many more ReST indentation errors, somehow accidentally missed from [16955]
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16983 bcc190cf-cafb-0310-a4f2-bffc1f526a37
Diffstat (limited to 'docs/internals/contributing/writing-code')
4 files changed, 209 insertions, 209 deletions
diff --git a/docs/internals/contributing/writing-code/branch-policy.txt b/docs/internals/contributing/writing-code/branch-policy.txt index ec4db3e532..3e6e179a2e 100644 --- a/docs/internals/contributing/writing-code/branch-policy.txt +++ b/docs/internals/contributing/writing-code/branch-policy.txt @@ -14,31 +14,31 @@ take more than a single patch, or requires large-scale refactoring -- you need to do it on a feature branch. Our development process recognizes two options for feature branches: - 1. Feature branches using a distributed revision control system like - Git_, Mercurial_, Bazaar_, etc. +1. Feature branches using a distributed revision control system like + Git_, Mercurial_, Bazaar_, etc. - If you're familiar with one of these tools, this is probably your best - option since it doesn't require any support or buy-in from the Django - core developers. + If you're familiar with one of these tools, this is probably your best + option since it doesn't require any support or buy-in from the Django + core developers. - However, do keep in mind that Django will continue to use Subversion - for the foreseeable future, and this will naturally limit the - recognition of your branch. Further, if your branch becomes eligible - for merging to trunk you'll need to find a core developer familiar - with your DVCS of choice who'll actually perform the merge. + However, do keep in mind that Django will continue to use Subversion + for the foreseeable future, and this will naturally limit the + recognition of your branch. Further, if your branch becomes eligible + for merging to trunk you'll need to find a core developer familiar + with your DVCS of choice who'll actually perform the merge. - If you do decided to start a distributed branch of Django and choose to - make it public, please add the branch to the `Django branches`_ wiki - page. + If you do decided to start a distributed branch of Django and choose to + make it public, please add the branch to the `Django branches`_ wiki + page. - 2. Feature branches using SVN have a higher bar. If you want a branch - in SVN itself, you'll need a "mentor" among the :doc:`core committers - </internals/committers>`. This person is responsible for actually - creating the branch, monitoring your process (see below), and - ultimately merging the branch into trunk. +2. Feature branches using SVN have a higher bar. If you want a branch + in SVN itself, you'll need a "mentor" among the :doc:`core committers + </internals/committers>`. This person is responsible for actually + creating the branch, monitoring your process (see below), and + ultimately merging the branch into trunk. - If you want a feature branch in SVN, you'll need to ask in - `django-developers`_ for a mentor. + If you want a feature branch in SVN, you'll need to ask in + `django-developers`_ for a mentor. .. _git: http://git-scm.com/ .. _mercurial: http://mercurial.selenic.com/ @@ -60,21 +60,21 @@ Developers with branches in SVN, however, **must** follow these rules. The branch mentor will keep on eye on the branch and **will delete it** if these rules are broken. - * Only branch entire copies of the Django tree, even if work is only - happening on part of that tree. This makes it painless to switch to a - branch. +* Only branch entire copies of the Django tree, even if work is only + happening on part of that tree. This makes it painless to switch to a + branch. - * Merge changes from trunk no less than once a week, and preferably every - couple-three days. +* Merge changes from trunk no less than once a week, and preferably every + couple-three days. - In our experience, doing regular trunk merges is often the difference - between a successful branch and one that fizzles and dies. + In our experience, doing regular trunk merges is often the difference + between a successful branch and one that fizzles and dies. - If you're working on an SVN branch, you should be using `svnmerge.py`_ - to track merges from trunk. + If you're working on an SVN branch, you should be using `svnmerge.py`_ + to track merges from trunk. - * Keep tests passing and documentation up-to-date. As with patches, - we'll only merge a branch that comes with tests and documentation. +* Keep tests passing and documentation up-to-date. As with patches, + we'll only merge a branch that comes with tests and documentation. .. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py @@ -91,11 +91,11 @@ Using branches To use a branch, you'll need to do two things: - * Get the branch's code through Subversion. +* Get the branch's code through Subversion. - * Point your Python ``site-packages`` directory at the branch's version of - the ``django`` package rather than the version you already have - installed. +* Point your Python ``site-packages`` directory at the branch's version of + the ``django`` package rather than the version you already have + installed. Getting the code from Subversion ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 6c3c1b3a25..915cc7724b 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -7,137 +7,137 @@ Please follow these coding standards when writing code for inclusion in Django. Python style ------------ - * Unless otherwise specified, follow :pep:`8`. +* Unless otherwise specified, follow :pep:`8`. - 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. + 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. - * Use four spaces for indentation. +* Use four spaces for indentation. - * Use underscores, not camelCase, for variable, function and method names - (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``). +* Use underscores, not camelCase, for variable, function and method names + (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``). - * Use ``InitialCaps`` for class names (or for factory functions that - return classes). +* Use ``InitialCaps`` for class names (or for factory functions that + return classes). - * In docstrings, use "action words" such as:: +* In docstrings, use "action words" such as:: - def foo(): - """ - Calculates something and returns the result. - """ - pass + def foo(): + """ + Calculates something and returns the result. + """ + pass - Here's an example of what not to do:: + Here's an example of what not to do:: - def foo(): - """ - Calculate something and return the result. - """ - pass + def foo(): + """ + Calculate something and return the result. + """ + pass Template style -------------- - * In Django template code, put one (and only one) space between the curly - brackets and the tag contents. +* In Django template code, put one (and only one) space between the curly + brackets and the tag contents. - Do this: + Do this: - .. code-block:: html+django + .. code-block:: html+django - {{ foo }} + {{ foo }} - Don't do this: + Don't do this: - .. code-block:: html+django + .. code-block:: html+django - {{foo}} + {{foo}} View style ---------- - * In Django views, the first parameter in a view function should be called - ``request``. +* In Django views, the first parameter in a view function should be called + ``request``. - Do this:: + Do this:: - def my_view(request, foo): - # ... + def my_view(request, foo): + # ... - Don't do this:: + Don't do this:: - def my_view(req, foo): - # ... + def my_view(req, foo): + # ... Model style ----------- - * Field names should be all lowercase, using underscores instead of - camelCase. +* Field names should be all lowercase, using underscores instead of + camelCase. - Do this:: + Do this:: - class Person(models.Model): - first_name = models.CharField(max_length=20) - last_name = models.CharField(max_length=40) + class Person(models.Model): + first_name = models.CharField(max_length=20) + last_name = models.CharField(max_length=40) - Don't do this:: + Don't do this:: - class Person(models.Model): - FirstName = models.CharField(max_length=20) - Last_Name = models.CharField(max_length=40) + class Person(models.Model): + FirstName = models.CharField(max_length=20) + Last_Name = models.CharField(max_length=40) - * The ``class Meta`` should appear *after* the fields are defined, with - a single blank line separating the fields and the class definition. +* The ``class Meta`` should appear *after* the fields are defined, with + a single blank line separating the fields and the class definition. - Do this:: + Do this:: - class Person(models.Model): - first_name = models.CharField(max_length=20) - last_name = models.CharField(max_length=40) + class Person(models.Model): + first_name = models.CharField(max_length=20) + last_name = models.CharField(max_length=40) - class Meta: - verbose_name_plural = 'people' + class Meta: + verbose_name_plural = 'people' - Don't do this:: + Don't do this:: - class Person(models.Model): - first_name = models.CharField(max_length=20) - last_name = models.CharField(max_length=40) - class Meta: - verbose_name_plural = 'people' + class Person(models.Model): + first_name = models.CharField(max_length=20) + last_name = models.CharField(max_length=40) + class Meta: + verbose_name_plural = 'people' - Don't do this, either:: + Don't do this, either:: - class Person(models.Model): - class Meta: - verbose_name_plural = 'people' + class Person(models.Model): + class Meta: + verbose_name_plural = 'people' - first_name = models.CharField(max_length=20) - last_name = models.CharField(max_length=40) + first_name = models.CharField(max_length=20) + last_name = models.CharField(max_length=40) - * The order of model inner classes and standard methods should be as - follows (noting that these are not all required): +* The order of model inner classes and standard methods should be as + follows (noting that these are not all required): - * All database fields - * Custom manager attributes - * ``class Meta`` - * ``def __unicode__()`` - * ``def __str__()`` - * ``def save()`` - * ``def get_absolute_url()`` - * Any custom methods + * All database fields + * Custom manager attributes + * ``class Meta`` + * ``def __unicode__()`` + * ``def __str__()`` + * ``def save()`` + * ``def get_absolute_url()`` + * Any custom methods - * If ``choices`` is defined for a given model field, define the choices as - a tuple of tuples, with an all-uppercase name, either near the top of - the model module or just above the model class. Example:: +* If ``choices`` is defined for a given model field, define the choices as + a tuple of tuples, with an all-uppercase name, either near the top of + the model module or just above the model class. Example:: - GENDER_CHOICES = ( - ('M', 'Male'), - ('F', 'Female'), - ) + GENDER_CHOICES = ( + ('M', 'Male'), + ('F', 'Female'), + ) Use of ``django.conf.settings`` ------------------------------- @@ -178,26 +178,26 @@ as :class:`django.utils.functional.LazyObject`, Miscellaneous ------------- - * Mark all strings for internationalization; see the :doc:`i18n - documentation </topics/i18n/index>` for details. +* 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`_. +* Remove ``import`` statements that are no longer used when you change code. + The most common tools for this task are `pyflakes`_ and `pylint`_. - * Systematically remove all trailing whitespaces from your code as those - add unnecessary bytes, add visual clutter to the patches and can also - occasionally cause unnecessary merge conflicts. Some IDE's can be - configured to automatically remove them and most VCS tools can be set to - highlight them in diff outputs. Note, however, that patches which only - remove whitespace (or only make changes for nominal PEP 8 conformance) - are likely to be rejected, since they only introduce noise rather than - code improvement. Tidy up when you're next changing code in the area. +* Systematically remove all trailing whitespaces from your code as those + add unnecessary bytes, add visual clutter to the patches and can also + occasionally cause unnecessary merge conflicts. Some IDE's can be + configured to automatically remove them and most VCS tools can be set to + highlight them in diff outputs. Note, however, that patches which only + remove whitespace (or only make changes for nominal PEP 8 conformance) + are likely to be rejected, since they only introduce noise rather than + code improvement. Tidy up when you're next changing code in the area. - * 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. +* 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: http://pypi.python.org/pypi/pep8 .. _pyflakes: http://pypi.python.org/pypi/pyflakes diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index d839641467..f443908285 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -19,28 +19,28 @@ If you have identified a contribution you want to make and you're capable of fixing it (as measured by your coding ability, knowledge of Django internals and time availability), claim it by following these steps: - * `Create an account`_ to use in our ticket system. If you have an account - but have forgotten your password, you can reset it using the - `password reset page`_. +* `Create an account`_ to use in our ticket system. If you have an account + but have forgotten your password, you can reset it using the + `password reset page`_. - * If a ticket for this issue doesn't exist yet, create one in our - `ticket tracker`_. +* If a ticket for this issue doesn't exist yet, create one in our + `ticket tracker`_. - * If a ticket for this issue already exists, make sure nobody else has - claimed it. To do this, look at the "Assigned to" section of the ticket. - If it's assigned to "nobody," then it's available to be claimed. - Otherwise, somebody else is working on this ticket, and you either find - another bug/feature to work on, or contact the developer working on the - ticket to offer your help. +* If a ticket for this issue already exists, make sure nobody else has + claimed it. To do this, look at the "Assigned to" section of the ticket. + If it's assigned to "nobody," then it's available to be claimed. + Otherwise, somebody else is working on this ticket, and you either find + another bug/feature to work on, or contact the developer working on the + ticket to offer your help. - * Log into your account, if you haven't already, by clicking "Login" in - the upper right of the ticket page. +* Log into your account, if you haven't already, by clicking "Login" in + the upper right of the ticket page. - * Claim the ticket: +* Claim the ticket: - 1. click the "accept" radio button under "Action" near the bottom of the - page, - 2. then click "Submit changes." + 1. click the "accept" radio button under "Action" near the bottom of the + page, + 2. then click "Submit changes." .. _Create an account: https://www.djangoproject.com/accounts/register/ .. _password reset page: https://www.djangoproject.com/accounts/password/reset/ @@ -76,43 +76,43 @@ it. Patch style ----------- - * Make sure your code matches our :doc:`coding-style`. +* Make sure your code matches our :doc:`coding-style`. - * Submit patches in the format returned by the ``svn diff`` command. - An exception is for code changes that are described more clearly in - plain English than in code. Indentation is the most common example; it's - hard to read patches when the only difference in code is that it's - indented. +* Submit patches in the format returned by the ``svn diff`` command. + An exception is for code changes that are described more clearly in + plain English than in code. Indentation is the most common example; it's + hard to read patches when the only difference in code is that it's + indented. - Patches in ``git diff`` format are also acceptable. + 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``, - ``tests``, ``AUTHORS``, etc. This makes it easy for other people to - apply your patches. +* When creating patches, always run ``svn diff`` from the top-level + ``trunk`` directory -- i.e. the one that contains ``django``, ``docs``, + ``tests``, ``AUTHORS``, etc. This makes it easy for other people to + apply your patches. - * Attach patches to a ticket in the `ticket tracker`_, using the "attach - file" button. Please *don't* put the patch in the ticket description - or comment unless it's a single line patch. +* Attach patches to a ticket in the `ticket tracker`_, using the "attach + file" button. Please *don't* put the patch in the ticket description + or comment unless it's a single line patch. - * Name the patch file with a ``.diff`` extension; this will let the ticket - tracker apply correct syntax highlighting, which is quite helpful. +* Name the patch file with a ``.diff`` extension; this will let the ticket + tracker apply correct syntax highlighting, which is quite helpful. - * Check the "Has patch" box on the ticket details. This will make it - obvious that the ticket includes a patch, and it will add the ticket to - the `list of tickets with patches`_. +* Check the "Has patch" box on the ticket details. This will make it + obvious that the ticket includes a patch, and it will add the ticket to + the `list of tickets with patches`_. - * 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 to prevent the problem from arising again. Also, if some tickets are - relevant to the code that you've written, mention the ticket numbers in - some comments in the test so that one can easily trace back the relevant - discussions after your patch gets committed and the tickets get closed. +* 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 to prevent the problem from arising again. Also, if some tickets are + relevant to the code that you've written, mention the ticket numbers in + some comments in the test so that one can easily trace back the relevant + discussions after your patch gets committed and the tickets get closed. - * If the code associated with a patch adds a new feature, or modifies - behavior of an existing feature, the patch should also contain - documentation. +* If the code associated with a patch adds a new feature, or modifies + behavior of an existing feature, the patch should also contain + documentation. Non-trivial patches ------------------- diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index cffcbd9371..5ec09fe84c 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -7,9 +7,9 @@ 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``), - * :ref:`contrib-apps` (``django/contrib/<app>/tests``). +* 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! @@ -58,30 +58,30 @@ and type: The :setting:`DATABASES` setting in this test settings module needs to define two databases: - * A ``default`` database. This database should use the backend that - you want to use for primary testing +* A ``default`` database. This database should use the backend that + you want to use for primary testing - * A database with the alias ``other``. The ``other`` database is - used to establish that queries can be directed to different - databases. As a result, this database can use any backend you - want. It doesn't need to use the same backend as the ``default`` - database (although it can use the same backend if you want to). +* A database with the alias ``other``. The ``other`` database is + used to establish that queries can be directed to different + databases. As a result, this database can use any backend you + want. It doesn't need to use the same backend as the ``default`` + database (although it can use the same backend if you want to). If you're using a backend that isn't SQLite, you will need to provide other details for each database: - * The :setting:`USER` option for each of your databases needs to - specify an existing user account for the database. +* The :setting:`USER` option for each of your databases needs to + specify an existing user account for the database. - * The :setting:`PASSWORD` option needs to provide the password for - the :setting:`USER` that has been specified. +* The :setting:`PASSWORD` option needs to provide the password for + the :setting:`USER` that has been specified. - * The :setting:`NAME` option must be the name of an existing database to - which the given user has permission to connect. The unit tests will not - touch this database; the test runner creates a new database whose name - is :setting:`NAME` prefixed with ``test_``, and this test database is - deleted when the tests are finished. This means your user account needs - permission to execute ``CREATE DATABASE``. +* The :setting:`NAME` option must be the name of an existing database to + which the given user has permission to connect. The unit tests will not + touch this database; the test runner creates a new database whose name + is :setting:`NAME` prefixed with ``test_``, and this test database is + deleted when the tests are finished. This means your user account needs + permission to execute ``CREATE DATABASE``. You will also need to ensure that your database uses UTF-8 as the default character set. If your database server doesn't use UTF-8 as a default charset, @@ -128,13 +128,13 @@ Running all the tests If you want to run the full suite of tests, you'll need to install a number of dependencies: - * PyYAML_ - * Markdown_ - * Textile_ - * Docutils_ - * setuptools_ - * memcached_, plus a :ref:`supported Python binding <memcached>` - * gettext_ (:ref:`gettext_on_windows`) +* PyYAML_ +* Markdown_ +* Textile_ +* Docutils_ +* setuptools_ +* memcached_, plus a :ref:`supported Python binding <memcached>` +* gettext_ (:ref:`gettext_on_windows`) If you want to test the memcached cache backend, you'll also need to define a :setting:`CACHES` setting that points at your memcached instance. |
