[Bug 1139127,1139128,1143941,1143945] Community top contributors

bower.json

@@ -12,7 +12,9 @@
   ],
   "dependencies": {
     "ace": "ace-builds#1.1.8",
+    "classnames": "~1.1.4",
     "d3": "d3#3.1.5",
+    "fontawesome": "#4.3.0",
     "jquery": "jquery#1.10.1",
     "jquery-ui": "jquery-ui#1.10.2",
     "mailcheck": "mailcheck#1.1.0",
@@ -21,6 +23,8 @@
     "normalize-css": "normalize-css#3.0.2",
     "nunjucks": "nunjucks#1.0.5",
     "nwmatcher": "nwmatcher#1.3.4",
+    "pikaday": "~1.3.2",
+    "react": "#0.13.0",
     "underscore": "underscore#1.2.1"
   }
 }

docs/development.rst

@@ -4,8 +4,8 @@ Development
 
 This covers loosely how we do big feature changes.
 
-Changes that involve new dependencies
-=====================================
+Changes that involve new Python dependencies
+============================================
 
 We use peep to install dependencies. That means that all dependencies have an
 associated hash (or several) that are checked at download time. This ensures
@@ -55,6 +55,23 @@ package. When you are satisfied that you have what you want, commit, push, and
 rejoice.
 
 
+Changes that involve new Node.js dependencies
+=============================================
+
+We are using `npm-lockdown <https://github.com/mozilla/npm-lockdown>`_ to
+handle installing the Node dependencies securely. To add a new package to the
+lockdown file, install it as normal with ``npm install package``, and then
+run lockdown-relock::
+
+    $ ./node_modules/.bin/lockdown-relock
+
+This will update ``lockdown.json`` with the appropriate hashes.
+
+Lockdown works by proxying between NPM and the package registry. Each file
+downloaded hash its hash checked, and if it does not match, Lockdown responds
+to NPM with a 404. This causes NPM to give the error: "npm ERR! notarget No
+valid targets found."
+
 
 Changes that involve database migrations
 ========================================

docs/frontend.rst

@@ -0,0 +1,110 @@
+=======================
+Frontend Infrastructure
+=======================
+
+Frontends assets for Kitsune are managed through `Django Pipeline`_.
+
+.. _Django Pipeline: https://django-pipeline.readthedocs.org/en/latest/
+
+
+Bundles
+=======
+
+To reduce the number of requests per page and increase overall performance,
+JS and CSS resources are grouped into *bundles*. These are defined in
+``kitsune/bundles.py``, and are loaded into pages with template tags. Each
+bundle provides a list of files which will be compiled (if necessary), minified,
+and concatenated into the final bundle product.
+
+In development, the minification and concatenation steps are skipped. In
+production, each file is renamed to contain a hash of it's contents in the
+name, and files are rewritten to account for the changed names. This is
+called cache busting, and allows the CDN to be more aggressive in caching these
+resources, and for clients to get updates faster when we make changes.
+
+Style Sheets
+============
+
+The styles written for Kitsune is written in `Less`_. Libraries, of course,
+have styles written in CSS. These are combined into bundles and shipped as
+minified CSS.
+
+Less files are recognized by an extension of ``.less``.
+
+.. _Less: http://lesscss.org/
+
+Javascript
+==========
+
+There are a few kinds of Javascript in use in Kitsune.
+
+Plain JS
+--------
+
+Plain JS is not suspect to any compilation step, and is only minified and
+concatenated. Plain JS files should be written to conform to ES3 standards, for
+compatibility.
+
+Plain JS files have an extension of ``.js``.
+
+ES6 JavaScript
+--------------
+
+EcmaScript 6 is the next version JavaScript that has been recently
+standardized. Because it is very new, it does not have wide spread browser
+support yet, and so it is compiled using `Babel`_ to ES5. Because it is
+compiled to ES5, and not ES3, it is not suitable for use in user facing parts
+of the site, which require maximum compatibility.
+
+These files are recognized by the ES6 compiler by an extension of ``.es6``, and
+*should* end in ``.js.es6`` for clarity. However, see the note about Browserify
+below.
+
+For more information about ES6 syntax and features, see
+`lukehoban/es6featurse`_.
+
+.. _Babel: https://babeljs.io/
+.. _es6: https://github.com/lukehoban/es6features
+
+JSX
+---
+
+JSX is a syntax extension on top of ES6 (and in some places, ES7) which adds
+support for an XML-like trees. It is used in Kitsune as a way to specify DOM
+elements in React Component render methods. JSX is compiled using Babel as
+well, and in fact all ES6 files may contain JSX syntax, since Babel compiles
+it by default.
+
+These files don't have a specific individual extension, but use the ``.es6``
+extension. For clarity, standalone jsx files should use the extension of
+``.jsx.es6``.
+
+Browserify
+----------
+
+Files with the extension ``.browserify.js`` are treated as Browserify entry
+points. They may include other JS files using `ES6 modules syntax`_. The files
+included in this way may also make use of the ES6 module system, regardless of
+their extension.
+
+All files loaded this way are treated as ES6+JSX files. This is generally the
+only way ES6 and JSX code should be included in a bundle, and so in practice
+the extensions assigned to those files don't matter to Django Pipeline, and
+should be named to be clear to the reader.
+
+Browserify has been configured with the babelify and bowerify transformers, to
+be able to load ES6 files and files from Bower.
+
+.. _ES6 modules syntax: https://github.com/lukehoban/es6features#modules
+
+
+Bower
+=====
+
+Frontend dependencies are downloaded using Bower. In a bundle file, they are
+listed as ``package-name/path/in/package.js``. Django Pipeline will find the
+correct Bower package to pull files from.
+
+Bower is not normally compatible with Browserify. A Browserify transformer
+called bowerify makes an include request for Bower packages load the primary
+entry point of the Bower package to make them compatible.

docs/hacking_howto.rst

@@ -197,31 +197,36 @@ For more information on ``peep``, refer to the
    `This Pip issue <https://github.com/pypa/pip/issues/1825>`_ for more details
 
 
-Javascript Packages
+Node.js Packages
 -------------------
 
-Kitsune relies on a small number of Javascript packages. To get those, you will
-need to `install Node.JS and NPM
+Kitsune relies on some Node.js packages. To get those, you will need to
+`install Node.js and NPM
 <https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager>`_.
 
-Now install the javascript dependencies with::
+Now install the Node.js dependencies with::
 
     $ npm install
 
 This should create a directory named ``node_modules`` in your git repo.
 
-We are now using `npm-lockdown <https://github.com/mozilla/npm-lockdown>`_ to handle installing the
-Node dependencies securely. This means if you add a new dependency you will need to run::
+.. Note::
 
-    $ ./node_modules/.bin/lockdown-relock
+    If you see a "npm ERR! notarget No valid targets found." error while
+    installing the Node packages, this is due to npm-lockdown being unable to
+    find a package that matches the hash in ``lockdown.json``.
 
-This will update ``lockdown.json`` with the appropriate hashes.
 
-.. Note::
+Frontend Packages
+-----------------
+
+Kitsune gets libraries and dependencies for client side code from Bower. Bower
+is installed as a part of the NPM packages in the last step. To install these
+front-end dependencies run::
 
-    If you see a "npm ERR! notarget No valid targets found." error while installing the Node
-    packages, this is due to npm-lockdown being unable to find a package that matches the hash in
-    ``lockdown.json``.
+   $ ./node_modules/.bin/bower install
+
+This will download dependencies into ``bower_components``.
 
 
 Configuration and Setup
@@ -256,12 +261,10 @@ database settings. For example, using the settings above::
     mysql> CREATE DATABASE kitsune CHARACTER SET utf8 COLLATE utf8_unicode_ci;
     mysql> GRANT ALL ON kitsune.* TO kitsune@localhost IDENTIFIED BY '<YOUR_PASSWORD>';
 
-
 To initialize the database, do::
 
     $ ./manage.py syncdb --migrate
 
-
 This will ask you to create a superuser account. Just follow the prompts.
 
 You'll now have an empty but up-to-date database!

docs/index.rst

@@ -29,6 +29,7 @@ Part 2: Developer's Guide
    email
    localization
    searchchapter
+   frontend
    armyofawesome
    karma
    wikidocs
@@ -65,4 +66,3 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-

kitsune/bundles.py

@@ -17,6 +17,15 @@
         ),
         'output_filename': 'community-min.css'
     },
+    'community-new': {
+        'source_filenames': (
+            'fontawesome/css/font-awesome.css',
+            'pikaday/css/pikaday.css',
+            'less/wiki-content.less',
+            'less/community-new.less',
+        ),
+        'output_filename': 'community-new-min.css'
+    },
     'mobile-common': {
         'source_filenames': (
             'normalize-css/normalize.css',
@@ -282,6 +291,34 @@
         ),
         'output_filename': 'community-min.js'
     },
+    'community-new-questions': {
+        'source_filenames': (
+            # This uses the minified version because it is optimized to leave
+            # out lots of debug stuff, so it is significantly smaller than
+            # just minifying react.js.
+            # TODO: Figure out how to include the full sized version in dev,
+            # because it produces much nicer error messages.
+            'react/react.min.js',
+            # 'react/react.js',
+            'pikaday/pikaday.js',
+            'js/community-questions.browserify.js',
+        ),
+        'output_filename': 'community-questions-min.js'
+    },
+    'community-new-l10n': {
+        'source_filenames': (
+            # This uses the minified version because it is optimized to leave
+            # out lots of debug stuff, so it is significantly smaller than
+            # just minifying react.js.
+            # TODO: Figure out how to include the full sized version in dev,
+            # because it produces much nicer error messages.
+            'react/react.min.js',
+            # 'react/react.js',
+            'pikaday/pikaday.js',
+            'js/community-l10n.browserify.js',
+        ),
+        'output_filename': 'community-l10n-min.js'
+    },
     'mobile-common': {
         'source_filenames': (
             'js/i18n.js',