mirror of
https://github.com/django/django.git
synced 2025-08-03 18:38:50 +00:00
Fixed #26020 -- Normalized header stylings in docs.
This commit is contained in:
Elif T. Kus
Tim Graham
parent
79d0a4fdb0
commit
bca9faae95
132 changed files with 1498 additions and 1464 deletions
|
|
@ -32,7 +32,7 @@ general points:
|
|||
.. _reporting-bugs:
|
||||
|
||||
Reporting bugs
|
||||
--------------
|
||||
==============
|
||||
|
||||
Well-written bug reports are *incredibly* helpful. However, there's a certain
|
||||
amount of overhead involved in working with any bug tracking system so your
|
||||
|
|
@ -61,7 +61,7 @@ To understand the lifecycle of your ticket once you have created it, refer to
|
|||
:doc:`triaging-tickets`.
|
||||
|
||||
Reporting user interface bugs and features
|
||||
------------------------------------------
|
||||
==========================================
|
||||
|
||||
If your bug or feature request touches on anything visual in nature, there
|
||||
are a few additional guidelines to follow:
|
||||
|
|
@ -87,7 +87,7 @@ are a few additional guidelines to follow:
|
|||
find your ticket.
|
||||
|
||||
Requesting features
|
||||
-------------------
|
||||
===================
|
||||
|
||||
We're always trying to make Django better, and your feature requests are a key
|
||||
part of that. Here are some tips on how to make a request most effectively:
|
||||
|
|
@ -128,7 +128,7 @@ See also: :ref:`documenting-new-features`.
|
|||
.. _how-we-make-decisions:
|
||||
|
||||
How we make decisions
|
||||
---------------------
|
||||
=====================
|
||||
|
||||
Whenever possible, we strive for a rough consensus. To that end, we'll often
|
||||
have informal votes on |django-developers| about a feature. In these votes we
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ who wants to contribute code to Django, have a look at
|
|||
.. _handling-pull-requests:
|
||||
|
||||
Handling pull requests
|
||||
----------------------
|
||||
======================
|
||||
|
||||
Since Django is now hosted at GitHub, most patches are provided in the form of
|
||||
pull requests.
|
||||
|
|
@ -101,7 +101,7 @@ community, getting work done, and having a usable commit history.
|
|||
.. _committing-guidelines:
|
||||
|
||||
Committing guidelines
|
||||
---------------------
|
||||
=====================
|
||||
|
||||
In addition, please follow the following guidelines when committing code to
|
||||
Django's Git repository:
|
||||
|
|
@ -200,7 +200,7 @@ Django's Git repository:
|
|||
to automate this.
|
||||
|
||||
Reverting commits
|
||||
-----------------
|
||||
=================
|
||||
|
||||
Nobody's perfect; mistakes will be committed.
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ and localization infrastructure available to Django applications, described in
|
|||
the :doc:`i18n documentation </topics/i18n/index>`.
|
||||
|
||||
Translations
|
||||
------------
|
||||
============
|
||||
|
||||
Translations are contributed by Django users worldwide. The translation work is
|
||||
coordinated at `Transifex`_.
|
||||
|
|
@ -53,11 +53,11 @@ translation manager's availability. So don't miss the string freeze period
|
|||
to complete and fix the translations for your language!
|
||||
|
||||
Formats
|
||||
-------
|
||||
=======
|
||||
|
||||
You can also review ``conf/locale/<locale>/formats.py``. This file describes
|
||||
the date, time and numbers formatting particularities of your locale. See
|
||||
:ref:`format-localization` for details.
|
||||
:doc:`/topics/i18n/formatting` for details.
|
||||
|
||||
The format files aren't managed by the use of Transifex. To change them, you
|
||||
must :doc:`create a patch<writing-code/submitting-patches>` against the
|
||||
|
|
@ -75,7 +75,7 @@ Django source tree, as for any code change:
|
|||
.. _translating-documentation:
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
=============
|
||||
|
||||
There is also an opportunity to translate the documentation, though this is a
|
||||
huge undertaking to complete entirely (you have been warned!). We use the same
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ to get started? This is the section for you.
|
|||
tutorial will give you an introduction to the tools and the workflow.
|
||||
|
||||
First steps
|
||||
-----------
|
||||
===========
|
||||
|
||||
Start with these easy tasks to discover Django's development process.
|
||||
|
||||
|
|
@ -70,7 +70,7 @@ Start with these easy tasks to discover Django's development process.
|
|||
|
||||
|
||||
Guidelines
|
||||
----------
|
||||
==========
|
||||
|
||||
As a newcomer on a large project, it's easy to experience frustration. Here's
|
||||
some advice to make your work on Django more useful and rewarding.
|
||||
|
|
@ -138,7 +138,7 @@ some advice to make your work on Django more useful and rewarding.
|
|||
.. _new-contributors-faq:
|
||||
|
||||
FAQ
|
||||
---
|
||||
===
|
||||
|
||||
1. **This ticket I care about has been ignored for days/weeks/months! What can
|
||||
I do to get it committed?**
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ Django is a community project, and every contribution helps. We can't do this
|
|||
without **you**!
|
||||
|
||||
Triage workflow
|
||||
---------------
|
||||
===============
|
||||
|
||||
Unfortunately, not all bug reports and feature requests in the ticket tracker
|
||||
provide all the :doc:`required details<bugs-and-features>`. A number of
|
||||
|
|
@ -96,20 +96,20 @@ require much much more.
|
|||
.. _triage-stages:
|
||||
|
||||
Triage stages
|
||||
-------------
|
||||
=============
|
||||
|
||||
Below we describe in more detail the various stages that a ticket may flow
|
||||
through during its lifetime.
|
||||
|
||||
Unreviewed
|
||||
~~~~~~~~~~
|
||||
----------
|
||||
|
||||
The ticket has not been reviewed by anyone who felt qualified to make a
|
||||
judgment about whether the ticket contained a valid issue, a viable feature,
|
||||
or ought to be closed for any of the various reasons.
|
||||
|
||||
Accepted
|
||||
~~~~~~~~
|
||||
--------
|
||||
|
||||
The big gray area! The absolute meaning of "accepted" is that the issue
|
||||
described in the ticket is valid and is in some stage of being worked on.
|
||||
|
|
@ -142,7 +142,7 @@ Beyond that there are several considerations:
|
|||
explaining what is needed to improve the code.
|
||||
|
||||
Ready For Checkin
|
||||
~~~~~~~~~~~~~~~~~
|
||||
-----------------
|
||||
|
||||
The ticket was reviewed by any member of the community other than the person
|
||||
who supplied the patch and found to meet all the requirements for a
|
||||
|
|
@ -152,7 +152,7 @@ review prior to being committed. See the
|
|||
RFC forever! What should I do?"
|
||||
|
||||
Someday/Maybe
|
||||
~~~~~~~~~~~~~
|
||||
-------------
|
||||
|
||||
This stage isn't shown on the diagram. It's only used by core developers to
|
||||
keep track of high-level ideas or long term feature requests.
|
||||
|
|
@ -163,12 +163,12 @@ consider adding someday to the framework if an excellent patch is submitted.
|
|||
They are not a high priority.
|
||||
|
||||
Other triage attributes
|
||||
-----------------------
|
||||
=======================
|
||||
|
||||
A number of flags, appearing as checkboxes in Trac, can be set on a ticket:
|
||||
|
||||
Has patch
|
||||
~~~~~~~~~
|
||||
---------
|
||||
|
||||
This means the ticket has an associated
|
||||
:doc:`patch<writing-code/submitting-patches>`. These will be reviewed
|
||||
|
|
@ -178,20 +178,20 @@ The following three fields (Needs documentation, Needs tests,
|
|||
Patch needs improvement) apply only if a patch has been supplied.
|
||||
|
||||
Needs documentation
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
-------------------
|
||||
|
||||
This flag is used for tickets with patches that need associated
|
||||
documentation. Complete documentation of features is a prerequisite
|
||||
before we can check them into the codebase.
|
||||
|
||||
Needs tests
|
||||
~~~~~~~~~~~
|
||||
-----------
|
||||
|
||||
This flags the patch as needing associated unit tests. Again, this
|
||||
is a required part of a valid patch.
|
||||
|
||||
Patch needs improvement
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
-----------------------
|
||||
|
||||
This flag means that although the ticket *has* a patch, it's not quite
|
||||
ready for checkin. This could mean the patch no longer applies
|
||||
|
|
@ -199,12 +199,12 @@ cleanly, there is a flaw in the implementation, or that the code
|
|||
doesn't meet our standards.
|
||||
|
||||
Easy pickings
|
||||
~~~~~~~~~~~~~
|
||||
-------------
|
||||
|
||||
Tickets that would require small, easy, patches.
|
||||
|
||||
Type
|
||||
~~~~
|
||||
----
|
||||
|
||||
Tickets should be categorized by *type* between:
|
||||
|
||||
|
|
@ -219,14 +219,14 @@ Tickets should be categorized by *type* between:
|
|||
better, faster, stronger.
|
||||
|
||||
Component
|
||||
~~~~~~~~~
|
||||
---------
|
||||
|
||||
Tickets should be classified into *components* indicating which area of
|
||||
the Django codebase they belong to. This makes tickets better organized and
|
||||
easier to find.
|
||||
|
||||
Severity
|
||||
~~~~~~~~
|
||||
--------
|
||||
|
||||
The *severity* attribute is used to identify blockers, that is, issues which
|
||||
should get fixed before releasing the next version of Django. Typically those
|
||||
|
|
@ -235,26 +235,26 @@ causing severe data losses. This attribute is quite rarely used and the vast
|
|||
majority of tickets have a severity of "Normal".
|
||||
|
||||
Version
|
||||
~~~~~~~
|
||||
-------
|
||||
|
||||
It is possible to use the *version* attribute to indicate in which
|
||||
version the reported bug was identified.
|
||||
|
||||
UI/UX
|
||||
~~~~~
|
||||
-----
|
||||
|
||||
This flag is used for tickets that relate to User Interface and User
|
||||
Experiences questions. For example, this flag would be appropriate for
|
||||
user-facing features in forms or the admin interface.
|
||||
|
||||
Cc
|
||||
~~
|
||||
--
|
||||
|
||||
You may add your username or email address to this field to be notified when
|
||||
new contributions are made to the ticket.
|
||||
|
||||
Keywords
|
||||
~~~~~~~~
|
||||
--------
|
||||
|
||||
With this field you may label a ticket with multiple keywords. This can be
|
||||
useful, for example, to group several tickets of a same theme. Keywords can
|
||||
|
|
@ -266,7 +266,7 @@ as "formset", "modelformset", and "ManagementForm".
|
|||
.. _closing-tickets:
|
||||
|
||||
Closing Tickets
|
||||
---------------
|
||||
===============
|
||||
|
||||
When a ticket has completed its useful lifecycle, it's time for it to be
|
||||
closed. Closing a ticket is a big responsibility, though. You have to be sure
|
||||
|
|
@ -338,7 +338,7 @@ developers and bring the issue to |django-developers| instead.
|
|||
.. _how-can-i-help-with-triaging:
|
||||
|
||||
How can I help with triaging?
|
||||
-----------------------------
|
||||
=============================
|
||||
|
||||
The triage process is primarily driven by community members. Really,
|
||||
**ANYONE** can help.
|
||||
|
|
@ -422,7 +422,7 @@ the ticket database:
|
|||
.. _password reset page: https://www.djangoproject.com/accounts/password/reset/
|
||||
|
||||
Bisecting a regression
|
||||
----------------------
|
||||
======================
|
||||
|
||||
.. highlight:: console
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ This section explains how writers can craft their documentation changes
|
|||
in the most useful and least error-prone ways.
|
||||
|
||||
Getting the raw documentation
|
||||
-----------------------------
|
||||
=============================
|
||||
|
||||
Though Django's documentation is intended to be read as HTML at
|
||||
https://docs.djangoproject.com/, we edit it as a collection of text files for
|
||||
|
|
@ -36,7 +36,7 @@ to have the docs for the last release be up-to-date and correct (see
|
|||
:ref:`differences-between-doc-versions`).
|
||||
|
||||
Getting started with Sphinx
|
||||
---------------------------
|
||||
===========================
|
||||
|
||||
Django's documentation uses the Sphinx__ documentation system, which in turn
|
||||
is based on docutils__. The basic idea is that lightly-formatted plain-text
|
||||
|
|
@ -66,7 +66,7 @@ Primer <sphinx:rst-primer>`. After that, you'll want to read about the
|
|||
metadata, indexing, and cross-references.
|
||||
|
||||
How the documentation is organized
|
||||
----------------------------------
|
||||
==================================
|
||||
|
||||
The documentation is organized into several categories:
|
||||
|
||||
|
|
@ -117,7 +117,7 @@ The documentation is organized into several categories:
|
|||
repeat the same material.
|
||||
|
||||
Writing style
|
||||
-------------
|
||||
=============
|
||||
|
||||
When using pronouns in reference to a hypothetical person, such as "a user with
|
||||
a session cookie", gender neutral pronouns (they/their/them) should be used.
|
||||
|
|
@ -130,7 +130,7 @@ Instead of:
|
|||
* himself or herself... use themselves.
|
||||
|
||||
Commonly used terms
|
||||
-------------------
|
||||
===================
|
||||
|
||||
Here are some style guidelines on commonly used terms throughout the
|
||||
documentation:
|
||||
|
|
@ -160,7 +160,7 @@ documentation:
|
|||
* **website** -- use one word, without capitalization.
|
||||
|
||||
Django-specific terminology
|
||||
---------------------------
|
||||
===========================
|
||||
|
||||
* **model** -- it's not capitalized.
|
||||
|
||||
|
|
@ -172,7 +172,7 @@ Django-specific terminology
|
|||
* **view** -- it's not capitalized.
|
||||
|
||||
Guidelines for reStructuredText files
|
||||
-------------------------------------
|
||||
=====================================
|
||||
|
||||
These guidelines regulate the format of our reST (reStructuredText)
|
||||
documentation:
|
||||
|
|
@ -199,8 +199,26 @@ documentation:
|
|||
* Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
|
||||
documentation.
|
||||
|
||||
* Use these heading styles::
|
||||
|
||||
===
|
||||
One
|
||||
===
|
||||
|
||||
Two
|
||||
===
|
||||
|
||||
Three
|
||||
-----
|
||||
|
||||
Four
|
||||
~~~~
|
||||
|
||||
Five
|
||||
^^^^
|
||||
|
||||
Django-specific markup
|
||||
----------------------
|
||||
======================
|
||||
|
||||
Besides the `Sphinx built-in markup`__, Django's docs defines some extra
|
||||
description units:
|
||||
|
|
@ -251,7 +269,7 @@ __ http://sphinx-doc.org/markup/
|
|||
.. _documenting-new-features:
|
||||
|
||||
Documenting new features
|
||||
------------------------
|
||||
========================
|
||||
|
||||
Our policy for new features is:
|
||||
|
||||
|
|
@ -309,7 +327,7 @@ We can simply remove the ``.. versionadded:: A.B`` annotation without any
|
|||
indentation changes when the time comes.
|
||||
|
||||
Minimizing images
|
||||
-----------------
|
||||
=================
|
||||
|
||||
Optimize image compression where possible. For PNG files, use OptiPNG and
|
||||
AdvanceCOMP's ``advpng``:
|
||||
|
|
@ -324,7 +342,7 @@ This is based on OptiPNG version 0.7.5. Older versions may complain about the
|
|||
``--strip all`` option being lossy.
|
||||
|
||||
An example
|
||||
----------
|
||||
==========
|
||||
|
||||
For a quick example of how it all fits together, consider this hypothetical
|
||||
example:
|
||||
|
|
@ -377,7 +395,7 @@ example:
|
|||
.. setting:: ADMINS
|
||||
|
||||
ADMINS
|
||||
------
|
||||
======
|
||||
|
||||
Default: ``[]`` (Empty list)
|
||||
|
||||
|
|
@ -400,7 +418,7 @@ That's basically how everything fits together.
|
|||
.. _improving-the-documentation:
|
||||
|
||||
Improving the documentation
|
||||
---------------------------
|
||||
===========================
|
||||
|
||||
A few small improvements can be made to make the documentation read and
|
||||
look better:
|
||||
|
|
@ -451,7 +469,7 @@ look better:
|
|||
.. _documentation-spelling-check:
|
||||
|
||||
Spelling check
|
||||
--------------
|
||||
==============
|
||||
|
||||
Before you commit your docs, it's a good idea to run the spelling checker.
|
||||
You'll need to install a couple packages first:
|
||||
|
|
@ -475,7 +493,7 @@ one of the following:
|
|||
to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).
|
||||
|
||||
Translating documentation
|
||||
-------------------------
|
||||
=========================
|
||||
|
||||
See :ref:`Localizing the Django documentation <translating-documentation>` if
|
||||
you'd like to help translate the documentation into another language.
|
||||
|
|
@ -483,7 +501,7 @@ you'd like to help translate the documentation into another language.
|
|||
.. _django-admin-manpage:
|
||||
|
||||
``django-admin`` man page
|
||||
-------------------------
|
||||
=========================
|
||||
|
||||
Sphinx can generate a manual page for the
|
||||
:doc:`django-admin </ref/django-admin>` command. This is configured in
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
================
|
||||
Django internals
|
||||
================
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ anyone.
|
|||
.. _django-users-mailing-list:
|
||||
|
||||
``django-users``
|
||||
----------------
|
||||
================
|
||||
|
||||
This is the right place if you are looking to ask any question regarding the
|
||||
installation, usage, or debugging of Django.
|
||||
|
|
@ -38,7 +38,7 @@ installation, usage, or debugging of Django.
|
|||
.. _django-core-mentorship-mailing-list:
|
||||
|
||||
``django-core-mentorship``
|
||||
--------------------------
|
||||
==========================
|
||||
|
||||
The Django Core Mentorship list is intended to provide a welcoming
|
||||
introductory environment for community members interested in contributing to
|
||||
|
|
@ -55,7 +55,7 @@ the Django Project.
|
|||
.. _django-developers-mailing-list:
|
||||
|
||||
``django-developers``
|
||||
---------------------
|
||||
=====================
|
||||
|
||||
The discussion about the development of Django itself takes place here.
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ The discussion about the development of Django itself takes place here.
|
|||
.. _django-i18n-mailing-list:
|
||||
|
||||
``django-i18n``
|
||||
---------------
|
||||
===============
|
||||
|
||||
This is the place to discuss the internationalization and localization of
|
||||
Django's components.
|
||||
|
|
@ -92,7 +92,7 @@ Django's components.
|
|||
.. _django-announce-mailing-list:
|
||||
|
||||
``django-announce``
|
||||
-------------------
|
||||
===================
|
||||
|
||||
A (very) low-traffic list for announcing new releases of Django and important
|
||||
bugfixes.
|
||||
|
|
@ -108,7 +108,7 @@ bugfixes.
|
|||
.. _django-updates-mailing-list:
|
||||
|
||||
``django-updates``
|
||||
------------------
|
||||
==================
|
||||
|
||||
All the ticket updates are mailed automatically to this list, which is tracked
|
||||
by developers and interested community members.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,3 @@
|
|||
.. _internals-security:
|
||||
|
||||
==========================
|
||||
Django's security policies
|
||||
==========================
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue