update some docs

docs/index.rst

@@ -24,6 +24,7 @@ include:
 * `Marketplace Communication Dashboard <https://github.com/mozilla/commbadge>`_
 * `Marketplace Operator Dashboard <https://github.com/mozilla/marketplace-operator-dashboard>`_
 * `Marketplace Statistics <https://github.com/mozilla/marketplace-stats>`_
+* `Marketplace Style Guide <https://github.com/mozilla/marketplace-style-guide>`_
 
 Pieces that make up the framework include:
 
@@ -32,6 +33,7 @@ Pieces that make up the framework include:
 * `Marketplace Node Modules <https://github.com/mozilla/commonplace>`_
 * `Marketplace API Mock <https://github.com/mozilla/marketplace-api-mock>`_
 * `Marketplace Elements <https://github.com/mozilla/marketplace-elements>`_
+* `Marketplace jQuery <https://github.com/mozilla/marketplace-jquery>`_
 
 Contents
 --------

docs/topics/developing-components.rst

@@ -16,32 +16,34 @@ Bower Components
 ~~~~~~~~~~~~~~~~
 
 Bower is the package manager we use for frontend assets. The assets are
-downloaded to ``bower_components`` and copied into the project with ``make
-install``.
+downloaded to ``bower_components`` and most are currently copied into the
+project with ``make install``.
 
 Development and Testing Workflow
 --------------------------------
 
-For convenience, you can ``git clone`` components straight into the source of
-your frontend project to where it would normally be copied to. That way, you
-can test your modules and handle revisions in the same place (without needing
-to copy modules to a different folder to commit).
+Currently for ``marketplace-core-modules``, you can ``bower link`` from your
+``marketplace-core-modules`` project. And then in your frontend project, you
+can ``bower link marketplace-core-modules`` to set up symlinks. Our webserver
+will rewrite the paths to ``bower_components`` such that development can be
+done directly within ``marketplace-core-modules``. We plan on adding the
+webserver-rewriting functionality for other components.
 
-For example, you can git clone ``marketplace-core-modules`` straight to
-``src/media/js/lib``, and develop and test the modules there.
-
-Be careful as running ``make install`` may overwrite changes you make in that
-directory, which will copy the source files from bower_components over to the
-project directory.
+For most other Bower components, they are copied into JS and CSS ``lib``
+directories into the source tree where the project can locate them and then
+gitignored. You can employ some strategies for developing these such as setting
+up symlinks. We are sorry for this.
 
 Updating a Component
 --------------------
 
 When pushing an update for a component:
 
-- Bump the version in ``bower.json`` (e.g., *1.5.2* to *1.5.3*)
-- Git tag the version (e.g., ``git tag v1.5.3``)
-- Push to Github (i.e., ``git push origin v1.5.3 && git push origin master``)
+- Bump the version in ``bower.json`` (e.g., *1.5.2* to *1.6.0*), following
+  semver
+- Commit the patch and push (e.g., ``git commit -m v1.6.0 important bug fix``)
+- Git tag the version (e.g., ``git tag v1.6.0``)
+- Push to Github (i.e., ``git push origin v1.6.0 && git push origin master``)
 
 To **consume** the updated component from a frontend project:
 
@@ -60,24 +62,29 @@ We have node modules such as Commonplace and Marketplace Gulp.
 Development and Testing Workflow
 --------------------------------
 
-When developing a node module, it is annoying to have to continually rebuild
-it or copy files back and forth between a version-tracked directory.
-``npm link`` eases this:
+When developing a node module, it is annoying to have to continually rebuild it
+or copy files back and forth between a version-tracked directory.  ``npm link``
+eases this:
 
-- Go to the project directory of the node module you are developing (e.g., marketplace-gulp)
+- Go to the project directory of the node module you are developing
+  (e.g., marketplace-gulp)
 - Run ``npm link`` to create a global link
-- Go to the project directory of the frontend project you want test it with (e.g., fireplace)
+- Go to the project directory of the frontend project you want test it with
+  (e.g., fireplace)
 - Run ``npm link <PACKAGE_NAME>`` to link-install the package
 
 Then changes are made in the node module's project directory will be reflected
 within the frontend project it is being tested with.
 
+Currently, ``marketplace-gulp`` has issues with this since Gulp does not play
+well with ``npm link`` when requiring other Gulpfiles.
+
 Updating a Module
 -----------------
 
 When pushing an update for a module:
 
-- Bump the version in ``package.json`` (e.g., *1.5.2* to *1.5.3*)
+- Bump the version in ``package.json`` (e.g., *1.5.2* to *1.6.0*)
 - Commit and push to Github (i.e., ``git push origin master``)
 - Run ``npm publish`` to publish it to npm
 
@@ -94,7 +101,6 @@ Guidelines
 
 When updating a module:
 
-- Bump the ``bower.json`` or ``package.json`` in the same commit
+- Try to bump the ``bower.json`` or ``package.json`` in the same commit
 - Prepend the commit message with the version (e.g., *v1.5.3 updated logs*)
-
-Then proceed as described above.
+- Use `semver's Semantic Versioning <http://semver.org/>`_

docs/topics/guidelines.rst

@@ -58,8 +58,8 @@ We make heavy use of AMD modules in the frontend.
 - Docstring at the top of all modules that describes the module.
 - The `define` line, the dependency list, and the function signature all begin
 on separate lines.
-- Alphabetize dependencies in module definitions based on the name of the
-dependency module.
+- Generally, alphabetize dependencies in module definitions based on the name
+of the dependency module.
 - Keep with 80-chars. When a dependency list grows too long, line-break it
 and use a visual-based indent.
 - If there is a line break in the dependency list, match the line break in
@@ -111,3 +111,5 @@ Some additional guidelines:
   middle.
 - Prefix Stylus classes by page or component (e.g., :code:`.big-dropdown-label`
   rather than just :code:`.label`).
+- Try to contain as much view logic in JS as you can rather than Nunjucks
+  templates. Nunjucks templates usually generate more code than JS.

docs/topics/testing.rst

@@ -110,37 +110,30 @@ live in the ``tests`` directory. This directory comprises of:
   various assertion facilities, utilities, and sets up necessary callbacks.
 - ``ui`` holds the actual test suites.
 
-CasperJS spins up PhantomJS or SlimerJS to run the tests.
+If you wish to run end-to-end tests with just one of the browser targets, you
+can run ``make uitest-phantom`` or ``make uitest-slimer``. To run end-to-tests
+targetting both PhantomJS and SlimerJS, run::
 
-To run the suite with PhantomJS::
+    make uitest
 
-    make uitest-phantom
+You can run a single test file or folder by setting ``UITEST_FILE`` environment
+variable::
 
-To run the suite with SlimerJS::
-
-    make uitest-slimer
+    UITEST_FILE=tests/ui/search.js make uitest-slimer
 
 SlimerJS runs against an external Firefox binary. By default the tests will try
-to use a Firefox installed to ``/Applications/Firefox.app/Contents/MacOS/firefox``.
-This will only work on Mac and will use whatever version of Firefox you have
-installed there. For best results it is suggested to use Firefox 30 which can be
-downloaded from `ftp.mozilla.org
-<http://ftp.mozilla.org/pub/mozilla.org/firefox/releases/30.0/>`_. You can set
-the version of Firefox to use with ``SLIMERJSLAUNCHER``, you may want to include
-``export SLIMERJSLAUNCHER=/path/to/firefox`` in your shell's setup script.
+to use ``/Applications/Firefox.app/Contents/MacOS/firefox``.
+This only works on Mac and uses the installed version of Firefox.
+We recommended downloading and running tests with
+`Firefox 30 <http://ftp.mozilla.org/pub/mozilla.org/firefox/releases/30.0/>`_.
+You can then set the version of Firefox to use with ``SLIMERJSLAUNCHER``. For
+convenience, include ``export SLIMERJSLAUNCHER=/path/to/firefox`` in your
+shell's setup script.
 
 .. code-block:: bash
 
     SLIMERJSLAUNCHER=/Applications/Firefox-30.app/Contenst/MacOS/firefox make uitest-slimer
 
-To run PhantomJS followed by SlimerJS use::
-
-    make uitest
-
-You can run a single test file with the ``UITEST_FILE`` environment variable::
-
-    UITEST_FILE=tests/ui/search.js make uitest-slimer
-
 Writing an End-to-End Test
 --------------------------
 
@@ -248,9 +241,13 @@ Debugging Tests
 
 Some useful tips when debugging a failing test:
 
-- Set the system environment variable, ``SHOW_TEST_CONSOLE``, to see every ``console.log``
-that is sent to the client-side console. This is useful for
+- Set the system environment variable, ``SHOW_TEST_CONSOLE``, to see every
+``console.log`` that is sent to the client-side console. This is useful for
 debugging tests.
+- Set the environment varible, ``FILTER_TEST_CONSOLE``, along with
+``SHOW_TEST_CONSOLE`` to see only logs that start with whatever is passed to
+``FILTER_TEST_CONSOLE``. Often, you can console.log ``[debug]`` in a
+casper.evaluate context and filter on that to poke around.
 - Whenever a test fails, CasperJS will automatically take a screenshot using
 PhantomJS. The screenshot is stored in the ``tests/captures`` directory. Check
 it out to see what the page looked like when an assertion fails.

docs/topics/usage.rst

@@ -62,7 +62,7 @@ and recompile anything if necessary. Here is what the webserver watches for:
 
 To run the webserver on a different port::
 
-    PORT=8000 make serve
+    MKT_PORT=8000 make serve
 
 To serve with compressed assets (bundled CSS/JS/templates with no RequireJS),
 pass in the `MKT_COMPILED` flag. This is useful for testing in a more
@@ -76,6 +76,12 @@ CSS stylesheets live without a page refresh. To disable LiveReload::
 
     NO_LIVERELOAD=1 make serve
 
+The webserver will rewrite ``src/media/js/lib/marketplace-core-modules`` to the
+``bower_components`` directory such that the modules don't need to be copied
+into the project. Our build tools at ``marketplace-gulp`` will be able to
+find the JS modules in the ``bower_components`` directory. We plan on doing
+this with our other JS dependencies.
+
 Generated index.html
 ____________________
 
@@ -136,11 +142,11 @@ Other things that will be generated:
 
 If you want to test the project with the built bundles above, serve with a
 template that uses the bundle, such as `src/app.html`. Read about the webserver
-above for more details
+above for more details.
 
 If you want to disable uglification and minification of JS and CSS::
 
-    NO_MINIFY=1 make build
+    MKT_NO_MINIFY=1 make build
 
 
 Additional Command-Line Interface