summaryrefslogtreecommitdiff
path: root/docs/internals/contributing/writing-code
diff options
context:
space:
mode:
authorLuke Plant <L.Plant.98@cantab.net>2011-10-14 00:12:01 +0000
committerLuke Plant <L.Plant.98@cantab.net>2011-10-14 00:12:01 +0000
commitd1e5c55258d624058a93c8cacdb1f25ae7857554 (patch)
treedca859edc2229f68b7511687aa8b333378786633 /docs/internals/contributing/writing-code
parent5109ac370928a5924887424b6d6c803038fcb691 (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')
-rw-r--r--docs/internals/contributing/writing-code/branch-policy.txt70
-rw-r--r--docs/internals/contributing/writing-code/coding-style.txt202
-rw-r--r--docs/internals/contributing/writing-code/submitting-patches.txt92
-rw-r--r--docs/internals/contributing/writing-code/unit-tests.txt54
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.