Merge pull request #101 from aldryn/develop

Release 3.4.0

.editorconfig

@@ -11,5 +11,8 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 max_line_length = 120
 
+[*.yml]
+indent_size = 2
+
 [Makefile]
 indent_style = tab

.jshintrc

@@ -3,7 +3,6 @@
     "esnext": true,
     "expr": true,
     "bitwise": true,
-    "camelcase": true,
     "curly": true,
     "eqeqeq": true,
     "immed": true,

.travis.yml

@@ -20,8 +20,5 @@ script:
 env:
   global:
     - secure: ghtK6PdDy13ruL+HGT4doVcUkl8pyzukY1gkHbkIAL8BrOc0eQdGBnAxKpPGZJv/8upWyul69DgXKg26cbS633Gfp0NjM/YPUh6wEgTg46Zjirw1ejX7xmqsQUGukZXOXNsll7/Syql+KEn8ao+JOAh+gjkFfNY2mxD6Oxs56Sc=
-    - secure: Vd/CeUcWVUsgejibIiq8PQT1xfK7SYRdWSdol6ymGb2LVI5ckm4rOGm+FBdbKip43oqgpkM7sLqBzSUTVTsGdea87tiKJKpp4AXaKTgkzG9LzY6eX67fnWvG2WOfTdrLIeUwjY/HVlAQC8ymaZ09Nj6Rhb7dKoziEW7+uqGjGjo=
-    - secure: gRrsTzeBs+2N7pi95FQ4lhhAzqXlwsVR8fBwPfYVY6s+kqFzyh7KeFuy2uH5JiS3MPP+XIihT9r6jf5rmmhoLIGTEpos3HZYGkaSEPSPybvNVdVoTnMzaNlrMdCLgw1/S15K1luhyR6PqvfVxoD+PTUNeT0s/YUuxMpsuvMgGtE=
-
-addons:
-  sauce_connect: true
+    - secure: LJw6Cd29/2EdavwQyALzgteQM5+tasvJu0FpS9HJnJPw77HAEl+u8HhRzV2V+/4n2ZMOG9lvDjS1ON+crAolXvo8FO607QNxKFfaMRU2ESynr7+A+itLD/4x3ljPXh72Mypw4Sh0geeVYyZ613jfjzXwKK6lazE/ZhzfcyD4hYk=
+    - secure: Nwqm4GQfjZ52MvcQZ/mP068RapB6Jg3sMVmitqsYwUmZsC9xDdmjkJlv3ViWmtZYcvYvQKT7+/iZ4+NjVvYcw7n2OY2vs9F/Vf+XuXuiQEQ9Ouy5im8vWM+1xxzfzPe0tVIWDIApx2j94G+CnKMebwCUeaPeRS1H8BXClPMVkeo=

CHANGELOG.rst

@@ -3,6 +3,21 @@ Aldryn Boilerplate Bootstrap 3
 ##############################
 
 
+3.4.0
+=====
+- major update to testing infrastructure
+- added integration tests
+- added browserslist
+- added coveralls support
+- added custom icon-font support
+- update dependencies
+- update jshint task to fail on travis correctly
+- update documentation
+- changed all ``{% load static %}`` instances to ``{% load staticfiles %}``
+- move tooling in ``package.json`` from dependencies to **dev**Dependencies
+- removed cl.debug.js
+
+
 3.3.4
 =====
 - update to bootstrap 3.3.5

README.rst

@@ -4,6 +4,8 @@ Bootstrap3 Based Boilerplate
 
 |Build Status| |Coverage Status| |Code Climate| |Dependency Status|
 
+|Browser Matrix|
+
 Aldryn Boilerplate Bootstrap 3 is the most complete **django CMS** based Boilerplate for rapid development. It uses the
 full potential of the `Bootstrap <http://getbootstrap.com/>`_ framework for developing responsive, mobile-first
 projects on the web, and implements various best practices from within the front-end community.
@@ -32,7 +34,9 @@ needs love. Feel free to fork and send us pull requests and checkout the
    :target: https://travis-ci.org/aldryn/aldryn-boilerplate-bootstrap3
 .. |Dependency Status| image:: https://gemnasium.com/aldryn/aldryn-boilerplate-bootstrap3.svg
    :target: https://gemnasium.com/aldryn/aldryn-boilerplate-bootstrap3
-.. |Coverage Status| image:: https://codeclimate.com/github/aldryn/aldryn-boilerplate-bootstrap3/badges/coverage.svg
-   :target: https://codeclimate.com/github/aldryn/aldryn-boilerplate-bootstrap3
+.. |Coverage Status| image:: https://coveralls.io/repos/github/aldryn/aldryn-boilerplate-bootstrap3/badge.svg?branch=master%2Fcoveralls
+   :target: https://coveralls.io/github/aldryn/aldryn-boilerplate-bootstrap3?branch=master%2Fcoveralls
 .. |Code Climate| image:: https://codeclimate.com/github/aldryn/aldryn-boilerplate-bootstrap3/badges/gpa.svg
    :target: https://codeclimate.com/github/aldryn/aldryn-boilerplate-bootstrap3
+.. |Browser Matrix| image:: https://saucelabs.com/browser-matrix/aldryn-boilerboot3.svg
+   :target: https://saucelabs.com/u/aldryn-boilerboot3

boilerplate.json

@@ -1,7 +1,7 @@
 {
     "identifier": "bootstrap3",
     "package-name": "aldryn-bootstrap3-boilerplate",
-    "version": "3.3.4",
+    "version": "3.4.0",
     "templates": [
         ["fullwidth.html", "full width"],
         ["sidebar_left.html", "sidebar left"],

browserslist

@@ -0,0 +1,4 @@
+# Browsers that we support
+
+last 2 versions
+ie >= 9

docs/general/configuration.rst

@@ -16,3 +16,24 @@ already added the general Bootstrap utilities for you. The file can be found at:
 ``/static/js/addons/ckeditor.wysiwyg.js``.
 
 .. image:: /_static/editor-wysiwyg.png
+
+
+Custom Icons
+============
+
+We added support for custom icon-font generation through Gulp. There are some
+configuration steps required if you want to use them:
+
+#. Add your SVG fonts to ``/private/icons``. Gulp gets all SVG files from
+   the ``/private/icons/**/*.svg`` pattern and generates the fonts for you.
+#. Run ``gulp icons`` to generate the icon-font
+#. Uncomment ``// @import iconfont;`` from
+   ``/private/sass/layout/_iconography.scss`` to include it in your gulp build
+
+The ``gulp icons`` command will automatically generate the
+``/private/sass/layout/_iconfont.scss`` file where you find the class reference
+and mixins for all icons.
+
+The generated icon-font will use the ``.icon`` css namespace for all
+custom icons. We recommend using the ``icon(*)`` mixin instead of
+``@extend .icon-*``.

docs/general/installation.rst

@@ -59,11 +59,13 @@ All front-end related tasks are handled via the `Gulp <http://gulpjs.com/>`_ tas
 
 We also offer some standalone commands:
 
-- ``gulp jslint`` runs JavaScript linting
-- ``gulp scsslint`` runs Sass linting
-- ``gulp images`` optimises images within ``/static/img``
 - ``gulp docs`` compiles YUIDoc into ``static/docs``
-- ``gulp karma`` only runs karma for debugging
+- ``gulp images`` optimises images within ``/static/img``
+- ``gulp lint:javascript`` runs JavaScript linting
+- ``gulp lint:sass`` runs Sass linting
+- ``gulp tests:unit`` runs unit tests
+- ``gulp tests:integration`` runs integration tests
+- ``gulp tests:watch`` runs tests in debugging mode
 
 We love code over configuration.
 

docs/general/whatsinside.rst

@@ -67,8 +67,14 @@ In addition several commonly-used shims are available to you including:
 Addons
 ------
 
-We are currently implementing the `select2.js bootstrap version <http://fk.github.io/select2-bootstrap-css/>`_ and
-`cl.debug.js <http://finalangel.github.io/classjs-plugins/>`_ as default addons.
+We are currently implementing the `select2.js bootstrap version
+<http://fk.github.io/select2-bootstrap-css/>`_ as default addon.
+
+
+Gulp
+----
+
+We use `Gulp <http://gulpjs.com/>`_ to manage our frontend workflow.
 
 
 Template Language

docs/guidelines/comments.rst

@@ -22,16 +22,12 @@ They do not need to describe:
 Section Comments
 ================
 
-The first separation style is *section comment*. This uses the full 120 width span ideally placed to separate large
-chunks of logic or a nice addition to the top of a file::
+In addition to the regular comments, we introduced the *section comment*. Use
+this style to separate large chungs of logic (which you should generally avoid).
+The line is exactly 80 characters long::
 
-    // #####################################################################################################################
-    // #NAME#
-
-The second available style separates smaller code blocks using 60 only lines::
-
-    // #########################################################
-    // #NAME#
+    // #############################################################################
+    // NAME
 
 
 Inline Comments

docs/testing/general.rst

@@ -0,0 +1,104 @@
+*******
+General
+*******
+
+We use two kinds of tests: **unit** and **integration** tests. Unit tests are
+simple test cases, that test a single piece of functionality within a given
+JavaScript file in an isolated environment without the DOM. Integration tests
+test the users interaction following certain move, click and keyboard
+interactions.
+
+This testing infrastructure includes them both with `Jasmine
+<http://jasmine.github.io/>`_ as the test suite and `Karma
+<http://karma-runner.github.io/>`_ as the test runner for unit tests.
+`Protractor <http://www.protractortest.org>`_ serves as the integration tests framework.
+Both tests can be run separately as described in :ref:`testing_commands` below.
+
+All tests are located within ``/tests``. Each pull request is validated on
+`Travis <https://github.com/aldryn/aldryn-boilerplate-bootstrap3/blob
+/master/.travis.yml>`_, which runs the test executing the ``gulp tests``
+command. You can also run this command locally, if you followed the
+:doc:`/general/installation` instructions.
+
+.. _testing_commands:
+
+Commands
+========
+
+The following commands are available to you:
+
+- ``gulp tests`` runs the entire test suite
+- ``gulp tests:unit`` only runs the unit tests
+- ``gulp tests:integration`` only runs the integration tests
+- ``gulp tests:watch`` to start karma to watch unit tests
+
+
+Naming
+======
+
+The naming for tests should adhere to the conventions established in
+:doc:`/guidelines/general` and :doc:`/guidelines/javascript`.
+
+**Unit tests** should be prefixed using ``test`` before the name file name and
+**integration tests** use ``spec``. For example:
+
+.. code-block:: text
+
+    test.header.js
+    test.footer.js
+    test.content.typography.js
+    test.content.wysiwyg.js
+    ...
+
+.. code-block:: text
+
+    spec.header.js
+    spec.footer.js
+    spec.content.typography.js
+    spec.content.wysiwyg.js
+    ...
+
+
+Structure
+=========
+
+Unit tests are located within ``/tests/unit`` and integration tests within
+``/tests/integration`` to create a clear separation. There are several
+configuration files available within the ``/tests`` directory described in
+:doc:`/testing/unit_tests` and :doc:`/testing/integration_tests` respectively.
+
+The starting structure looks like this:
+
+.. code-block:: text
+
+    tests/
+    ├─ fixtures/
+    ├─ integration/
+    ├─ unit/
+    ├─ base.conf.js
+    ├─ karma.conf.js
+    └─ protractor.conf.js
+
+Fixtures and coverage are described in more depth within
+:doc:`/testing/unit_tests`.
+
+
+Configuration
+=============
+
+The configuration files are located at the root of the ``/tests`` folder.
+``karma.conf.js`` defines the settings for the ``gulp tests:unit`` command and
+``protractor.conf.js`` for the ``gulp tests:integration`` command.
+
+The function of these configuration files is described in more depth within
+:doc:`/testing/unit_tests` or :doc:`/testing/integration_tests`.
+
+Browserslist
+============
+
+`Browserslist <https://github.com/ai/browserslist>`_ enables us to provide a
+compiled and ready to use browser-list to services such as Sauce Labs,
+Autoprefixer and more.
+
+Simply add the required browser to the ``browserslist`` file. Our configuration
+includes the `last 2 versions` and `ie >= 9`.

docs/testing/index.rst

@@ -4,40 +4,16 @@ Testing
 
 .. note::
 
-    We are using the `Jasmine <http://jasmine.github.io/>`_ test suite and the `Karma <http://karma-runner.github.io/>`_
-    test runner for behaviour driven tests.
-
-
-*******
-General
-*******
-
-All tests are located within ``/tests``. Each pull request gets validated through `Travis
-<https://github.com/aldryn/aldryn-boilerplate-bootstrap3/blob/master/.travis.yml>`_ by running those tests
-using ``gulp tests``. You can also run this command on your local computer considering you followed the
-:doc:`/general/installation` instructions.
-
-
-*********
-Structure
-*********
-
-Name the files according to the :doc:`/guidelines/general` guidelines and consider the :doc:`/guidelines/javascript`
-additions for proper prefixing, for example:
-
-.. code-block:: text
-
-    test.header.js
-    test.footer.js
-    test.content.typography.js
-    test.content.wysiwyg.js
-    ...
-
-
-********
-Coverage
-********
-
-The success of your project does not depend on the tests or the percentage of your code coverage. Yet it will
-improve maintanance and further development for you and other contributors. We should "Aim for the highest" possible
-test coverage.
+    This section describes the unit and integration tests setup using
+    `Jasmine <http://jasmine.github.io/>`_ and
+    `Protractor <http://www.protractortest.org>`_. You will find advice on how to setup
+    your own testing infrastructure, integrate it into `Travis <travis-ci.org>`_
+    and connect with `Sauce Labs <http://saucelabs.com>`_.
+
+.. toctree::
+    :maxdepth: 2
+
+    general
+    unit_tests
+    integration_tests
+    services

docs/testing/integration_tests.rst

@@ -0,0 +1,52 @@
+*****************
+Integration Tests
+*****************
+
+
+Configuration
+=============
+
+The main configuration file to look at is ``/tests/protractor.conf.js``.
+It configures our ``browserName``.
+
+In ``browserName`` we specify the browser that will be used to launch the tests.
+It can be set to ``phantomjs``, ``firefox`` or ``chrome``.
+
+You can find more information about this in the
+`protractor referenceConf.js
+<https://github.com/angular/protractor/blob/master/docs/referenceConf.js>`_ documentation.
+
+All spec files should be placed in ``/tests/integration/specs`` and all page
+object files should be in ``/tests/integration/pages``. So, the file organisation
+structure is:
+
+.. code-block:: text
+
+    tests/
+    └─ integration/
+       ├─ specs/
+       │   ├─ spec.name.js
+       │   └─ spec.another.name.js
+       └─ pages/
+           ├─ page.name.js
+           └─ page.another.name.js
+
+The specs that will be launched are defined in the ``gulpfile.js``. They can be
+specified using patterns:
+
+.. code-block:: javascript
+
+    return gulp.src([PROJECT_PATH.tests + '/integration/specs/*.js'])
+
+By default all specs inside ``/tests/integration/specs`` folder will be launched.
+
+
+Coverage
+========
+
+Integration coverage is measured by the number of critical path or regression
+test cases that were automated. Keep in mind that the success of your project
+does not depend on the tests or the percentage of your code coverage, but it
+will improve maintenance and give you and other contributors more confidence in
+the quality of the product you produce. We should aim for the highest possible
+coverage and quality.