mirror of
https://github.com/django/django.git
synced 2025-10-24 14:16:09 +00:00
Refs #36485 -- Rewrapped docs to 79 columns line length.
Lines in the docs files were manually adjusted to conform to the 79 columns limit per line (plus newline), improving readability and consistency across the content.
This commit is contained in:
@@ -4,7 +4,8 @@ Committing code
|
||||
|
||||
This section is addressed to the mergers and to anyone interested in knowing
|
||||
how code gets committed into Django. If you're a community member who wants to
|
||||
contribute code to Django, look at :doc:`writing-code/working-with-git` instead.
|
||||
contribute code to Django, look at :doc:`writing-code/working-with-git`
|
||||
instead.
|
||||
|
||||
.. _handling-pull-requests:
|
||||
|
||||
|
||||
@@ -438,10 +438,10 @@ Next, we mark the current point in history as being "bad" since the test fails:
|
||||
|
||||
Now, we need to find a point in git history before the regression was
|
||||
introduced (i.e. a point where the test passes). Use something like
|
||||
``git checkout HEAD~100`` to check out an earlier revision (100 commits earlier,
|
||||
in this case). Check if the test fails. If so, mark that point as "bad"
|
||||
(``git bisect bad``), then check out an earlier revision and recheck. Once you
|
||||
find a revision where your test passes, mark it as "good":
|
||||
``git checkout HEAD~100`` to check out an earlier revision (100 commits
|
||||
earlier, in this case). Check if the test fails. If so, mark that point as
|
||||
"bad" (``git bisect bad``), then check out an earlier revision and recheck.
|
||||
Once you find a revision where your test passes, mark it as "good":
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -96,13 +96,12 @@ Python style
|
||||
|
||||
* In docstrings, follow the style of existing docstrings and :pep:`257`.
|
||||
|
||||
* In tests, use
|
||||
:meth:`~django.test.SimpleTestCase.assertRaisesMessage` and
|
||||
:meth:`~django.test.SimpleTestCase.assertWarnsMessage`
|
||||
instead of :meth:`~unittest.TestCase.assertRaises` and
|
||||
:meth:`~unittest.TestCase.assertWarns` so you can check the
|
||||
exception or warning message. Use :meth:`~unittest.TestCase.assertRaisesRegex`
|
||||
and :meth:`~unittest.TestCase.assertWarnsRegex` only if you need regular
|
||||
* In tests, use :meth:`~django.test.SimpleTestCase.assertRaisesMessage` and
|
||||
:meth:`~django.test.SimpleTestCase.assertWarnsMessage` instead of
|
||||
:meth:`~unittest.TestCase.assertRaises` and
|
||||
:meth:`~unittest.TestCase.assertWarns` so you can check the exception or
|
||||
warning message. Use :meth:`~unittest.TestCase.assertRaisesRegex` and
|
||||
:meth:`~unittest.TestCase.assertWarnsRegex` only if you need regular
|
||||
expression matching.
|
||||
|
||||
Use :meth:`assertIs(…, True/False)<unittest.TestCase.assertIs>` for testing
|
||||
@@ -149,9 +148,10 @@ Imports
|
||||
|
||||
* Put imports in these groups: future, standard library, third-party libraries,
|
||||
other Django components, local Django component, try/excepts. Sort lines in
|
||||
each group alphabetically by the full module name. Place all ``import module``
|
||||
statements before ``from module import objects`` in each section. Use absolute
|
||||
imports for other Django components and relative imports for local components.
|
||||
each group alphabetically by the full module name. Place all
|
||||
``import module`` statements before ``from module import objects`` in each
|
||||
section. Use absolute imports for other Django components and relative
|
||||
imports for local components.
|
||||
|
||||
* On each line, alphabetize the items with the upper case items grouped before
|
||||
the lowercase items.
|
||||
|
||||
@@ -17,8 +17,8 @@ Code style
|
||||
for indentation, but there are some exceptions.
|
||||
|
||||
* When naming variables, use ``camelCase`` instead of ``underscore_case``.
|
||||
Different JavaScript files sometimes use a different code style. Please try to
|
||||
conform to the code style of each file.
|
||||
Different JavaScript files sometimes use a different code style. Please try
|
||||
to conform to the code style of each file.
|
||||
|
||||
* Use the `ESLint`_ code linter to check your code for bugs and style errors.
|
||||
ESLint will be run when you run the JavaScript tests. We also recommended
|
||||
@@ -89,8 +89,8 @@ 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 :source:`js_tests/tests.html` in your
|
||||
browser.
|
||||
To run the tests from a web browser, open up :source:`js_tests/tests.html` in
|
||||
your browser.
|
||||
|
||||
To measure code coverage when running the tests, you need to view that file
|
||||
over HTTP. To view code coverage:
|
||||
|
||||
@@ -204,9 +204,12 @@ whether to accept it.
|
||||
|
||||
Some examples of DEPs that have been approved and fully implemented:
|
||||
|
||||
* `DEP 181: ORM Expressions <https://github.com/django/deps/blob/main/final/0181-orm-expressions.rst>`_
|
||||
* `DEP 182: Multiple Template Engines <https://github.com/django/deps/blob/main/final/0182-multiple-template-engines.rst>`_
|
||||
* `DEP 201: Simplified routing syntax <https://github.com/django/deps/blob/main/final/0201-simplified-routing-syntax.rst>`_
|
||||
* `DEP 181: ORM Expressions
|
||||
<https://github.com/django/deps/blob/main/final/0181-orm-expressions.rst>`_
|
||||
* `DEP 182: Multiple Template Engines
|
||||
<https://github.com/django/deps/blob/main/final/0182-multiple-template-engines.rst>`_
|
||||
* `DEP 201: Simplified routing syntax
|
||||
<https://github.com/django/deps/blob/main/final/0201-simplified-routing-syntax.rst>`_
|
||||
|
||||
.. _Django Forum: https://forum.djangoproject.com/
|
||||
.. _Django Enhancement Proposals: https://github.com/django/deps
|
||||
@@ -226,19 +229,19 @@ There are a couple of reasons that code in Django might be deprecated:
|
||||
no longer needs to support the older version of Python that doesn't include
|
||||
the library, the library will be deprecated in Django.
|
||||
|
||||
As the :ref:`deprecation policy<internal-release-deprecation-policy>` describes,
|
||||
the first release of Django that deprecates a feature (``A.B``) should raise a
|
||||
``RemovedInDjangoXXWarning`` (where XX is the Django version where the feature
|
||||
will be removed) when the deprecated feature is invoked. Assuming we have good
|
||||
test coverage, these warnings are converted to errors when :ref:`running the
|
||||
test suite <running-unit-tests>` with warnings enabled:
|
||||
As the :ref:`deprecation policy<internal-release-deprecation-policy>`
|
||||
describes, the first release of Django that deprecates a feature (``A.B``)
|
||||
should raise a ``RemovedInDjangoXXWarning`` (where XX is the Django version
|
||||
where the feature will be removed) when the deprecated feature is invoked.
|
||||
Assuming we have good test coverage, these warnings are converted to errors
|
||||
when :ref:`running the test suite <running-unit-tests>` with warnings enabled:
|
||||
``python -Wa runtests.py``. Thus, when adding a ``RemovedInDjangoXXWarning``
|
||||
you need to eliminate or silence any warnings generated when running the tests.
|
||||
|
||||
The first step is to remove any use of the deprecated behavior by Django itself.
|
||||
Next you can silence warnings in tests that actually test the deprecated
|
||||
behavior by using the ``ignore_warnings`` decorator, either at the test or class
|
||||
level:
|
||||
The first step is to remove any use of the deprecated behavior by Django
|
||||
itself. Next you can silence warnings in tests that actually test the
|
||||
deprecated behavior by using the ``ignore_warnings`` decorator, either at the
|
||||
test or class level:
|
||||
|
||||
#) In a particular test::
|
||||
|
||||
@@ -305,8 +308,9 @@ Finally, there are a couple of updates to Django's documentation to make:
|
||||
applicable, to the current release notes (``docs/releases/A.B.txt``) under
|
||||
the "Features deprecated in A.B" heading.
|
||||
|
||||
#) Add an entry in the deprecation timeline (``docs/internals/deprecation.txt``)
|
||||
under the appropriate version describing what code will be removed.
|
||||
#) Add an entry in the deprecation timeline
|
||||
(``docs/internals/deprecation.txt``) under the appropriate version
|
||||
describing what code will be removed.
|
||||
|
||||
Once you have completed these steps, you are finished with the deprecation.
|
||||
In each :term:`feature release <Feature release>`, all
|
||||
@@ -402,10 +406,10 @@ Bugs
|
||||
|
||||
* Is there a proper regression test (the test should fail before the fix
|
||||
is applied)?
|
||||
* If it's a bug that :ref:`qualifies for a backport <supported-versions-policy>`
|
||||
to the stable version of Django, is there a release note in
|
||||
``docs/releases/A.B.C.txt``? Bug fixes that will be applied only to the main
|
||||
branch don't need a release note.
|
||||
* If it's a bug that :ref:`qualifies for a backport
|
||||
<supported-versions-policy>` to the stable version of Django, is there a
|
||||
release note in ``docs/releases/A.B.C.txt``? Bug fixes that will be applied
|
||||
only to the main branch don't need a release note.
|
||||
|
||||
New Features
|
||||
------------
|
||||
|
||||
@@ -398,9 +398,9 @@ and also excludes several directories not relevant to the results
|
||||
Contrib apps
|
||||
============
|
||||
|
||||
Tests for contrib apps can be found in the :source:`tests/` directory, typically
|
||||
under ``<app_name>_tests``. For example, tests for ``contrib.auth`` are located
|
||||
in :source:`tests/auth_tests`.
|
||||
Tests for contrib apps can be found in the :source:`tests/` directory,
|
||||
typically under ``<app_name>_tests``. For example, tests for ``contrib.auth``
|
||||
are located in :source:`tests/auth_tests`.
|
||||
|
||||
.. _troubleshooting-unit-tests:
|
||||
|
||||
|
||||
@@ -205,8 +205,8 @@ All Python code blocks should be formatted using the :pypi:`blacken-docs`
|
||||
auto-formatter. This is automatically run by the :ref:`pre-commit hook
|
||||
<coding-style-pre-commit>` if configured.
|
||||
|
||||
The check can also be run manually: provided that ``blacken-docs`` is installed,
|
||||
run the following command from the ``docs`` directory:
|
||||
The check can also be run manually: provided that ``blacken-docs`` is
|
||||
installed, run the following command from the ``docs`` directory:
|
||||
|
||||
.. console::
|
||||
|
||||
@@ -245,8 +245,8 @@ Entries that have a status of "broken" need to be fixed. Those that have a
|
||||
status of "redirected" may need to be updated to point to the canonical
|
||||
location, e.g. the scheme has changed ``http://`` → ``https://``. In certain
|
||||
cases, we do not want to update a "redirected" link, e.g. a rewrite to always
|
||||
point to the latest or stable version of the documentation, e.g. ``/en/stable/`` →
|
||||
``/en/3.2/``.
|
||||
point to the latest or stable version of the documentation, e.g.
|
||||
``/en/stable/`` → ``/en/3.2/``.
|
||||
|
||||
Writing style
|
||||
=============
|
||||
@@ -523,12 +523,12 @@ General improvements or other changes to the APIs that should be emphasized
|
||||
should use the "``.. versionchanged:: X.Y``" directive (with the same format
|
||||
as the ``versionadded`` mentioned above.
|
||||
|
||||
These ``versionadded`` and ``versionchanged`` blocks should be "self-contained."
|
||||
In other words, since we only keep these annotations around for two releases,
|
||||
it's nice to be able to remove the annotation and its contents without having
|
||||
to reflow, reindent, or edit the surrounding text. For example, instead of
|
||||
putting the entire description of a new or changed feature in a block, do
|
||||
something like this:
|
||||
These ``versionadded`` and ``versionchanged`` blocks should be
|
||||
"self-contained." In other words, since we only keep these annotations around
|
||||
for two releases, it's nice to be able to remove the annotation and its
|
||||
contents without having to reflow, reindent, or edit the surrounding text. For
|
||||
example, instead of putting the entire description of a new or changed feature
|
||||
in a block, do something like this:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
@@ -659,12 +659,12 @@ you'd like to help translate the documentation into another language.
|
||||
``django-admin`` man page
|
||||
=========================
|
||||
|
||||
Sphinx can generate a manual page for the
|
||||
:doc:`django-admin </ref/django-admin>` command. This is configured in
|
||||
``docs/conf.py``. Unlike other documentation output, this man page should be
|
||||
included in the Django repository and the releases as
|
||||
``docs/man/django-admin.1``. There isn't a need to update this file when
|
||||
updating the documentation, as it's updated once as part of the release process.
|
||||
Sphinx can generate a manual page for the :doc:`django-admin
|
||||
</ref/django-admin>` command. This is configured in ``docs/conf.py``. Unlike
|
||||
other documentation output, this man page should be included in the Django
|
||||
repository and the releases as ``docs/man/django-admin.1``. There isn't a need
|
||||
to update this file when updating the documentation, as it's updated once as
|
||||
part of the release process.
|
||||
|
||||
To generate an updated version of the man page, in the ``docs`` directory, run:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user