Fixed #13290 - Added a section about minification of admin JavaScript files to the contributing docs. Thanks to Gabriel Hurley for the report and patch.

jezdez · jezdez · commit b3390fede028 · 2010-04-13T10:29:44.000Z
git-svn-id: http://code.djangoproject.com/svn/django/trunk@12969 bcc190cf-cafb-0310-a4f2-bffc1f526a37
diff --git a/django/contrib/admin/media/js/compress.py b/django/contrib/admin/media/js/compress.py
@@ -9,10 +9,11 @@
 def main():
     usage = "usage: %prog [file1..fileN]"
     description = """With no file paths given this script will automatically
-compress all jQuery based files of the admin app."""
+compress all jQuery-based files of the admin app. Requires the Google Closure
+Compiler library and Java version 6 or later."""
     parser = optparse.OptionParser(usage, description=description)
     parser.add_option("-c", dest="compiler", default="~/bin/compiler.jar",
-                      help="path to closure compiler jar file")
+                      help="path to Closure Compiler jar file")
     parser.add_option("-v", "--verbose",
                       action="store_true", dest="verbose")
     parser.add_option("-q", "--quiet",
@@ -21,7 +22,7 @@ def main():
 
     compiler = os.path.expanduser(options.compiler)
     if not os.path.exists(compiler):
-        sys.exit("Closure compiler jar file %s not found. Please use the -c option to specify the path." % compiler)
+        sys.exit("Google Closure compiler jar file %s not found. Please use the -c option to specify the path." % compiler)
 
     if not args:
         if options.verbose:
diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt
@@ -433,6 +433,44 @@ translated, here's what to do:
 
 .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
 
+Submitting javascript patches
+=============================
+
+.. versionadded:: 1.2
+
+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.
+
+To simplify the process of providing optimized javascript code, Django
+includes a handy script which should be used to create a "minified" version.
+This script is located at ``/contrib/admin/media/js/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 version 6 or higher (Java 1.6 or
+higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with Java
+1.6 by default, so it may be necessary to upgrade your Java installation before
+the tool will be functional. Also note that even after upgrading Java, the
+default `/usr/bin/java` command may remain linked to the previous Java
+binary, so relinking that command may be necessary as well.
+
+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: http://code.google.com/closure/compiler/
+
 Django conventions
 ==================
 
