diff options
Diffstat (limited to 'docs/internals/contributing/writing-code')
5 files changed, 54 insertions, 53 deletions
diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 5dfe9c00f9..805741da6d 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -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`. diff --git a/docs/internals/contributing/writing-code/javascript.txt b/docs/internals/contributing/writing-code/javascript.txt index a3b34c564e..8b8534e384 100644 --- a/docs/internals/contributing/writing-code/javascript.txt +++ b/docs/internals/contributing/writing-code/javascript.txt @@ -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. diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index aad0abf6e7..1c6abbd473 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -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>`? diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 31e795ee66..1de6caacb5 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -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 diff --git a/docs/internals/contributing/writing-code/working-with-git.txt b/docs/internals/contributing/writing-code/working-with-git.txt index c7d551f24d..a7588361f2 100644 --- a/docs/internals/contributing/writing-code/working-with-git.txt +++ b/docs/internals/contributing/writing-code/working-with-git.txt @@ -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. |