mirror of
https://github.com/django/django.git
synced 2025-10-24 06:06:09 +00:00
Fixed #26020 -- Normalized header stylings in docs.
This commit is contained in:
Elif T. Kus
Tim Graham
@@ -5,7 +5,7 @@ Coding style
|
||||
Please follow these coding standards when writing code for inclusion in Django.
|
||||
|
||||
Python style
|
||||
------------
|
||||
============
|
||||
|
||||
* Please conform to the indentation style dictated in the ``.editorconfig``
|
||||
file. We recommend using a text editor with `EditorConfig`_ support to avoid
|
||||
@@ -52,7 +52,7 @@ Python style
|
||||
to use regular expression matching.
|
||||
|
||||
Imports
|
||||
-------
|
||||
=======
|
||||
|
||||
* Use `isort <https://github.com/timothycrosley/isort#readme>`_ to automate
|
||||
import sorting using the guidelines below.
|
||||
@@ -132,7 +132,7 @@ Imports
|
||||
from django.views.generic.base import View
|
||||
|
||||
Template style
|
||||
--------------
|
||||
==============
|
||||
|
||||
* In Django template code, put one (and only one) space between the curly
|
||||
brackets and the tag contents.
|
||||
@@ -150,7 +150,7 @@ Template style
|
||||
{{foo}}
|
||||
|
||||
View style
|
||||
----------
|
||||
==========
|
||||
|
||||
* In Django views, the first parameter in a view function should be called
|
||||
``request``.
|
||||
@@ -166,7 +166,7 @@ View style
|
||||
# ...
|
||||
|
||||
Model style
|
||||
-----------
|
||||
===========
|
||||
|
||||
* Field names should be all lowercase, using underscores instead of
|
||||
camelCase.
|
||||
@@ -240,7 +240,7 @@ Model style
|
||||
)
|
||||
|
||||
Use of ``django.conf.settings``
|
||||
-------------------------------
|
||||
===============================
|
||||
|
||||
Modules should not in general use settings stored in ``django.conf.settings``
|
||||
at the top level (i.e. evaluated when the module is imported). The explanation
|
||||
@@ -276,7 +276,7 @@ such as ``django.utils.functional.LazyObject``,
|
||||
``django.utils.functional.lazy()`` or ``lambda``.
|
||||
|
||||
Miscellaneous
|
||||
-------------
|
||||
=============
|
||||
|
||||
* Mark all strings for internationalization; see the :doc:`i18n
|
||||
documentation </topics/i18n/index>` for details.
|
||||
@@ -299,7 +299,7 @@ Miscellaneous
|
||||
single trivial change.
|
||||
|
||||
JavaScript style
|
||||
----------------
|
||||
================
|
||||
|
||||
For details about the JavaScript code style used by Django, see
|
||||
:doc:`javascript`.
|
||||
|
||||
@@ -9,7 +9,7 @@ Please follow these coding standards when writing JavaScript code for inclusion
|
||||
in Django.
|
||||
|
||||
Code style
|
||||
----------
|
||||
==========
|
||||
|
||||
* Please conform to the indentation style dictated in the ``.editorconfig``
|
||||
file. We recommend using a text editor with `EditorConfig`_ support to avoid
|
||||
@@ -27,7 +27,7 @@ Code style
|
||||
.. _javascript-patches:
|
||||
|
||||
JavaScript patches
|
||||
------------------
|
||||
==================
|
||||
|
||||
Django's admin system leverages the jQuery framework to increase the
|
||||
capabilities of the admin interface. In conjunction, there is an emphasis on
|
||||
@@ -41,7 +41,7 @@ production use (e.g. ``foo.min.js``). Any links to the file in the codebase
|
||||
should point to the compressed version.
|
||||
|
||||
Compressing JavaScript
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
----------------------
|
||||
|
||||
To simplify the process of providing optimized JavaScript code, Django
|
||||
includes a handy Python script which should be used to create a "minified"
|
||||
@@ -61,13 +61,13 @@ Please don't forget to run ``compress.py`` and include the ``diff`` of the
|
||||
minified scripts when submitting patches for Django's JavaScript.
|
||||
|
||||
JavaScript tests
|
||||
----------------
|
||||
================
|
||||
|
||||
Django's JavaScript tests can be run in a browser or from the command line.
|
||||
The tests are located in a top level ``js_tests`` directory.
|
||||
|
||||
Writing tests
|
||||
~~~~~~~~~~~~~
|
||||
-------------
|
||||
|
||||
Django's JavaScript tests use `QUnit`_. Here is an example test module:
|
||||
|
||||
@@ -101,12 +101,12 @@ Please consult the QUnit documentation for information on the types of
|
||||
`assertions supported by QUnit <https://api.qunitjs.com/category/assert/>`_.
|
||||
|
||||
Running tests
|
||||
~~~~~~~~~~~~~
|
||||
-------------
|
||||
|
||||
The JavaScript tests may be run from a web browser or from the command line.
|
||||
|
||||
Testing from a web browser
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To run the tests from a web browser, open up ``js_tests/tests.html`` in your
|
||||
browser.
|
||||
@@ -119,7 +119,7 @@ over HTTP. To view code coverage:
|
||||
* Open http://localhost:8000/js_tests/tests.html in your web browser.
|
||||
|
||||
Testing from the command line
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To run the tests from the command line, you need to have `Node.js`_ installed.
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ with associated patches will get fixed *far* more quickly than those
|
||||
without patches.
|
||||
|
||||
Typo fixes and trivial documentation changes
|
||||
--------------------------------------------
|
||||
============================================
|
||||
|
||||
If you are fixing a really trivial issue, for example changing a word in the
|
||||
documentation, the preferred way to provide the patch is using GitHub pull
|
||||
@@ -16,7 +16,7 @@ requests without a Trac ticket.
|
||||
See the :doc:`working-with-git` for more details on how to use pull requests.
|
||||
|
||||
"Claiming" tickets
|
||||
------------------
|
||||
==================
|
||||
|
||||
In an open-source project with hundreds of contributors around the world, it's
|
||||
important to manage communication efficiently so that work doesn't get
|
||||
@@ -62,7 +62,7 @@ and time availability), claim it by following these steps:
|
||||
.. _Contributor License Agreement: https://www.djangoproject.com/foundation/cla/
|
||||
|
||||
Ticket claimers' responsibility
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
-------------------------------
|
||||
|
||||
Once you've claimed a ticket, you have a responsibility to work on that ticket
|
||||
in a reasonably timely fashion. If you don't have time to work on it, either
|
||||
@@ -80,7 +80,7 @@ your claim on the ticket may be revoked.
|
||||
As always, more communication is better than less communication!
|
||||
|
||||
Which tickets should be claimed?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
--------------------------------
|
||||
|
||||
Of course, going through the steps of claiming tickets is overkill in some
|
||||
cases.
|
||||
@@ -96,7 +96,7 @@ or not, to submit patches to a ticket if you happen to have a patch ready.
|
||||
.. _patch-style:
|
||||
|
||||
Patch style
|
||||
-----------
|
||||
===========
|
||||
|
||||
Make sure that any contribution you do fulfills at least the following
|
||||
requirements:
|
||||
@@ -143,7 +143,7 @@ Regardless of the way you submit your work, follow these steps.
|
||||
.. _Development dashboard: https://dashboard.djangoproject.com/
|
||||
|
||||
Non-trivial patches
|
||||
-------------------
|
||||
===================
|
||||
|
||||
A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
|
||||
that introduces Django functionality and makes some sort of design decision.
|
||||
@@ -157,7 +157,7 @@ ask.
|
||||
.. _deprecating-a-feature:
|
||||
|
||||
Deprecating a feature
|
||||
---------------------
|
||||
=====================
|
||||
|
||||
There are a couple reasons that code in Django might be deprecated:
|
||||
|
||||
@@ -233,7 +233,7 @@ In each :term:`feature release`, all ``RemovedInDjangoXXWarning``\s matching
|
||||
the new version are removed.
|
||||
|
||||
JavaScript patches
|
||||
------------------
|
||||
==================
|
||||
|
||||
For information on JavaScript patches, see the :ref:`javascript-patches`
|
||||
documentation.
|
||||
@@ -241,7 +241,7 @@ documentation.
|
||||
.. _patch-review-checklist:
|
||||
|
||||
Patch review checklist
|
||||
----------------------
|
||||
======================
|
||||
|
||||
Use this checklist to review a pull request. If you are reviewing a pull
|
||||
request that is not your own and it passes all the criteria below, please set
|
||||
@@ -260,7 +260,7 @@ Looking to get your patch reviewed? Ensure the Trac flags on the ticket are
|
||||
set so that the ticket appears in that queue.
|
||||
|
||||
Documentation
|
||||
~~~~~~~~~~~~~
|
||||
-------------
|
||||
|
||||
* Does the documentation build without any errors (``make html``, or
|
||||
``make.bat html`` on Windows, from the ``docs`` directory)?
|
||||
@@ -269,13 +269,13 @@ Documentation
|
||||
* Are there any :ref:`spelling errors <documentation-spelling-check>`?
|
||||
|
||||
Bugs
|
||||
~~~~
|
||||
----
|
||||
|
||||
* Is there a proper regression test (the test should fail before the fix
|
||||
is applied)?
|
||||
|
||||
New Features
|
||||
~~~~~~~~~~~~
|
||||
------------
|
||||
|
||||
* Are there tests to "exercise" all of the new code?
|
||||
* Is there a release note in ``docs/releases/A.B.txt``?
|
||||
@@ -284,12 +284,12 @@ New Features
|
||||
``.. versionadded:: A.B`` or ``.. versionchanged:: A.B``?
|
||||
|
||||
Deprecating a feature
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
---------------------
|
||||
|
||||
See the :ref:`deprecating-a-feature` guide.
|
||||
|
||||
All code changes
|
||||
~~~~~~~~~~~~~~~~
|
||||
----------------
|
||||
|
||||
* Does the :doc:`coding style
|
||||
</internals/contributing/writing-code/coding-style>` conform to our
|
||||
@@ -300,7 +300,7 @@ All code changes
|
||||
to build the pull request against our continuous integration server.
|
||||
|
||||
All tickets
|
||||
~~~~~~~~~~~
|
||||
-----------
|
||||
|
||||
* Is the pull request a single squashed commit with a message that follows our
|
||||
:ref:`commit message format <committing-guidelines>`?
|
||||
|
||||
@@ -16,10 +16,10 @@ how to write new tests.
|
||||
.. _running-unit-tests:
|
||||
|
||||
Running the unit tests
|
||||
----------------------
|
||||
======================
|
||||
|
||||
Quickstart
|
||||
~~~~~~~~~~
|
||||
----------
|
||||
|
||||
If you are on Python 2, you'll first need to install a backport of the
|
||||
``unittest.mock`` module that's available in Python 3. See
|
||||
@@ -48,7 +48,7 @@ Having problems? See :ref:`troubleshooting-unit-tests` for some common issues.
|
||||
.. _running-unit-tests-settings:
|
||||
|
||||
Using another ``settings`` module
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
---------------------------------
|
||||
|
||||
The included settings module allows you to run the test suite using
|
||||
SQLite. If you want to test behavior using a different database (and
|
||||
@@ -92,7 +92,7 @@ test settings dictionary for the applicable database.
|
||||
.. _runtests-specifying-labels:
|
||||
|
||||
Running only some of the tests
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
------------------------------
|
||||
|
||||
Django's entire test suite takes a while to run, and running every single test
|
||||
could be redundant if, say, you just added a test to Django that you want to
|
||||
@@ -119,7 +119,7 @@ Going beyond that, you can specify an individual test method like this::
|
||||
$ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests.test_lazy_objects
|
||||
|
||||
Running the Selenium tests
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
--------------------------
|
||||
|
||||
Some tests require Selenium and a Web browser (Firefox, Google Chrome, or
|
||||
Internet Explorer). To allow those tests to be run rather than skipped, you must
|
||||
@@ -131,7 +131,7 @@ install the selenium_ package into your Python path and run the tests with the
|
||||
.. _running-unit-tests-dependencies:
|
||||
|
||||
Running all the tests
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
---------------------
|
||||
|
||||
If you want to run the full suite of tests, you'll need to install a number of
|
||||
dependencies:
|
||||
@@ -188,7 +188,7 @@ associated tests will be skipped.
|
||||
.. _pip requirements files: https://pip.pypa.io/en/latest/user_guide.html#requirements-files
|
||||
|
||||
Code coverage
|
||||
~~~~~~~~~~~~~
|
||||
-------------
|
||||
|
||||
Contributors are encouraged to run coverage on the test suite to identify areas
|
||||
that need additional tests. The coverage tool installation and use is described
|
||||
@@ -211,7 +211,7 @@ and also excludes several directories not relevant to the results
|
||||
.. _contrib-apps:
|
||||
|
||||
Contrib apps
|
||||
------------
|
||||
============
|
||||
|
||||
Tests for contrib apps can be found in the ``tests/`` directory, typically
|
||||
under ``<app_name>_tests``. For example, tests for ``contrib.auth`` are located
|
||||
@@ -220,10 +220,10 @@ in ``tests/auth_tests``.
|
||||
.. _troubleshooting-unit-tests:
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
===============
|
||||
|
||||
Many test failures with ``UnicodeEncodeError``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
----------------------------------------------
|
||||
|
||||
If the ``locales`` package is not installed, some tests will fail with a
|
||||
``UnicodeEncodeError``.
|
||||
@@ -234,7 +234,7 @@ You can resolve this on Debian-based systems, for example, by running::
|
||||
$ dpkg-reconfigure locales
|
||||
|
||||
Tests that only fail in combination
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
-----------------------------------
|
||||
|
||||
In case a test passes when run in isolation but fails within the whole suite,
|
||||
we have some tools to help analyze the problem.
|
||||
@@ -279,7 +279,7 @@ cause any trouble::
|
||||
$ ./runtests.py basic --reverse
|
||||
|
||||
Seeing the SQL queries run during a test
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
----------------------------------------
|
||||
|
||||
If you wish to examine the SQL being run in failing tests, you can turn on
|
||||
:ref:`SQL logging <django-db-logger>` using the ``--debug-sql`` option. If you
|
||||
@@ -288,7 +288,7 @@ combine this with ``--verbosity=2``, all SQL queries will be output::
|
||||
$ ./runtests.py basic --debug-sql
|
||||
|
||||
Seeing the full traceback of a test failure
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
-------------------------------------------
|
||||
|
||||
By default tests are run in parallel with one process per core. When the tests
|
||||
are run in parallel, however, you'll only see a truncated traceback for any
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
===========================
|
||||
Working with Git and GitHub
|
||||
===========================
|
||||
|
||||
@@ -14,7 +15,7 @@ You could also upload a traditional patch to Trac, but it's less practical for
|
||||
reviews.
|
||||
|
||||
Installing Git
|
||||
--------------
|
||||
==============
|
||||
|
||||
Django uses `Git`_ for its source control. You can `download
|
||||
<http://git-scm.com/download>`_ Git, but it's often easier to install with
|
||||
@@ -38,7 +39,7 @@ used to associate your commits with your GitHub account.
|
||||
.. _GitHub: https://github.com/
|
||||
|
||||
Setting up local repository
|
||||
---------------------------
|
||||
===========================
|
||||
|
||||
When you have created your GitHub account, with the nick "GitHub_nick", and
|
||||
forked Django's repository, create a local copy of your fork::
|
||||
@@ -64,7 +65,7 @@ You can add other remotes similarly, for example::
|
||||
git remote add akaariai git@github.com:akaariai/django.git
|
||||
|
||||
Working on a ticket
|
||||
-------------------
|
||||
===================
|
||||
|
||||
When working on a ticket create a new branch for the work, and base that work
|
||||
on upstream/master::
|
||||
@@ -94,7 +95,7 @@ necessary::
|
||||
git commit -m 'Added two more tests for edge cases'
|
||||
|
||||
Publishing work
|
||||
~~~~~~~~~~~~~~~
|
||||
---------------
|
||||
|
||||
You can publish your work on GitHub just by doing::
|
||||
|
||||
@@ -143,7 +144,7 @@ ready for merging -- or sufficiently close that a committer will finish it
|
||||
himself.
|
||||
|
||||
Rebasing branches
|
||||
~~~~~~~~~~~~~~~~~
|
||||
-----------------
|
||||
|
||||
In the example above you created two commits, the "Fixed ticket_xxxxx" commit
|
||||
and "Added two more tests" commit.
|
||||
@@ -189,7 +190,7 @@ commit hashes do not match any more. This is acceptable, as the branch is merely
|
||||
a topic branch, and nobody should be basing their work on it.
|
||||
|
||||
After upstream has changed
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
--------------------------
|
||||
|
||||
When upstream (django/django) has changed, you should rebase your work. To
|
||||
do this, use::
|
||||
@@ -215,7 +216,7 @@ This way your branch will contain only commits related to its topic, which
|
||||
makes squashing easier.
|
||||
|
||||
After review
|
||||
~~~~~~~~~~~~
|
||||
------------
|
||||
|
||||
It is unusual to get any non-trivial amount of code into core without changes
|
||||
requested by reviewers. In this case, it is often a good idea to add the
|
||||
@@ -247,7 +248,7 @@ Note that the committer is likely to squash the review commit into the previous
|
||||
commit when committing the code.
|
||||
|
||||
Working on a patch
|
||||
------------------
|
||||
==================
|
||||
|
||||
One of the ways that developers can contribute to Django is by reviewing
|
||||
patches. Those patches will typically exist as pull requests on GitHub and
|
||||
@@ -264,7 +265,7 @@ For more detail on working with pull requests see the
|
||||
:ref:`guidelines for committers <handling-pull-requests>`.
|
||||
|
||||
Summary
|
||||
-------
|
||||
=======
|
||||
|
||||
* Work on GitHub if you can.
|
||||
* Announce your work on the Trac ticket by linking to your GitHub branch.
|
||||
|
||||
Reference in New Issue
Block a user