diff options
Diffstat (limited to 'docs')
4 files changed, 81 insertions, 33 deletions
diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 2aa967c88d..54c2bd47e2 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -7,6 +7,11 @@ 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 + indentation and whitespace issues. The Python files use 4 spaces for + indentation and the HTML files use 2 spaces. + * Unless otherwise specified, follow :pep:`8`. Use `flake8`_ to check for problems in this area. Note that our ``setup.cfg`` @@ -286,4 +291,11 @@ Miscellaneous change to the ``AUTHORS`` file in your patch if you make more than a single trivial change. +JavaScript style +---------------- + +For details about the JavaScript code style used by Django, see +:doc:`javascript`. + +.. _editorconfig: http://editorconfig.org/ .. _flake8: https://pypi.python.org/pypi/flake8 diff --git a/docs/internals/contributing/writing-code/index.txt b/docs/internals/contributing/writing-code/index.txt index fe9c3cc933..98e2b8dfa2 100644 --- a/docs/internals/contributing/writing-code/index.txt +++ b/docs/internals/contributing/writing-code/index.txt @@ -13,3 +13,4 @@ chances to be included in Django core: unit-tests submitting-patches working-with-git + javascript diff --git a/docs/internals/contributing/writing-code/javascript.txt b/docs/internals/contributing/writing-code/javascript.txt new file mode 100644 index 0000000000..fa3685720e --- /dev/null +++ b/docs/internals/contributing/writing-code/javascript.txt @@ -0,0 +1,64 @@ +========== +JavaScript +========== + +While most of Django core is Python, the ``admin`` and ``gis`` contrib apps +contain JavaScript code. + +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 + indentation and whitespace issues. Most of the JavaScript files use 4 spaces + 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. + +* Use the `JSHint`_ code linter to check your code for bugs and style errors. + JSHint will be run when you run the JavaScript tests. We also recommended + installing a JSHint plugin in your text editor. + +.. _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 +admin JavaScript performance and minimizing overall admin media file size. +Serving compressed or "minified" versions of JavaScript files is considered +best practice in this regard. + +To that end, patches for JavaScript files should include both the original +code for future development (e.g. ``foo.js``), and a compressed version for +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" +version. To run it:: + + python django/contrib/admin/bin/compress.py + +Behind the scenes, ``compress.py`` is a front-end for Google's +`Closure Compiler`_ which is written in Java. However, the Closure Compiler +library is not bundled with Django directly, so those wishing to contribute +complete JavaScript patches will need to download and install the library +independently. The Closure Compiler library requires `Java`_ 7 or higher. + +Please don't forget to run ``compress.py`` and include the ``diff`` of the +minified scripts when submitting patches for Django's JavaScript. + +.. _Closure Compiler: https://developers.google.com/closure/compiler/ +.. _EditorConfig: http://editorconfig.org/ +.. _Java: https://www.java.com +.. _jshint: http://jshint.com/ diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index d9302169b6..bc7503518f 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -145,6 +145,8 @@ Regardless of the way you submit your work, follow these steps. obvious that the ticket includes a patch, and it will add the ticket to the `list of tickets with patches`_. +.. _list of tickets with patches: https://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority +.. _ticket tracker: https://code.djangoproject.com/newticket Non-trivial patches ------------------- @@ -245,39 +247,8 @@ the new version are removed. 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 -admin JavaScript performance and minimizing overall admin media file size. -Serving compressed or "minified" versions of JavaScript files is considered -best practice in this regard. - -To that end, patches for JavaScript files should include both the original -code for future development (e.g. ``foo.js``), and a compressed version for -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" -version. To run it:: - - python django/contrib/admin/bin/compress.py - -Behind the scenes, ``compress.py`` is a front-end for Google's -`Closure Compiler`_ which is written in Java. However, the Closure Compiler -library is not bundled with Django directly, so those wishing to contribute -complete JavaScript patches will need to download and install the library -independently. The Closure Compiler library requires `Java`_ 7 or higher. - -Please don't forget to run ``compress.py`` and include the ``diff`` of the -minified scripts when submitting patches for Django's JavaScript. - -.. _Closure Compiler: https://developers.google.com/closure/compiler/ -.. _list of tickets with patches: https://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority -.. _ticket tracker: https://code.djangoproject.com/newticket -.. _Java: https://www.java.com +For information on JavaScript patches, see the :ref:`javascript-patches` +documentation. .. _patch-review-checklist: |