diff options
Diffstat (limited to 'docs/internals/contributing')
7 files changed, 62 insertions, 57 deletions
diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt index 2dc42d8853..c2dc0eee48 100644 --- a/docs/internals/contributing/committing-code.txt +++ b/docs/internals/contributing/committing-code.txt @@ -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: diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt index c0d87dcb7c..aac1354e5e 100644 --- a/docs/internals/contributing/triaging-tickets.txt +++ b/docs/internals/contributing/triaging-tickets.txt @@ -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 diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 125525c737..64ef6c5a51 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -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. diff --git a/docs/internals/contributing/writing-code/javascript.txt b/docs/internals/contributing/writing-code/javascript.txt index 25165206f0..b61fc009b7 100644 --- a/docs/internals/contributing/writing-code/javascript.txt +++ b/docs/internals/contributing/writing-code/javascript.txt @@ -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: diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index 75186111dd..d1d5a8a32d 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -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 ------------ diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 1c993f5fc6..05b2bf09c6 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -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: diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 2654cce06e..ff9bf5da47 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -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: |