mirror of
https://github.com/django/django.git
synced 2025-08-03 18:38:50 +00:00
Fixed #22463 -- Added code style guide and JavaScript linting (EditorConfig and ESLint)
This commit is contained in:
Trey Hunner
Tim Graham
parent
1e63652e44
commit
ec4f219ecb
26 changed files with 1014 additions and 849 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -13,3 +13,4 @@ chances to be included in Django core:
|
|||
unit-tests
|
||||
submitting-patches
|
||||
working-with-git
|
||||
javascript
|
||||
|
|
|
|||
64
docs/internals/contributing/writing-code/javascript.txt
Normal file
64
docs/internals/contributing/writing-code/javascript.txt
Normal file
|
|
@ -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/
|
||||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue