Merge branch 'master' into patch-1

Author: pmahnke

.circleci/config.yml

@@ -0,0 +1,80 @@
+version: 2
+
+defaults: &defaults
+  docker:
+    - image: canonicalwebteam/dev
+
+jobs:
+  test-site:
+    <<: *defaults
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: yarn
+      - run:
+          name: Install bower dependencies
+          command: bower --allow-root install
+      - run:
+          name: Build the site resources
+          command: yarn run build-all
+      - run:
+          name: Run the site server
+          command: PORT=80 ./bin/serve
+          background: true
+      - run:
+          name: Check site is accessible
+          command: sleep 4 && curl --head --fail --retry-delay 5 --retry 10  --retry-connrefused http://localhost
+  lint-content:
+    <<: *defaults
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: yarn
+      - run:
+          name: Lint content
+          command: yarn lint-content
+  lint-style:
+    <<: *defaults
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: yarn
+      - run:
+          name: Lint style
+          command: yarn lint-style
+  lint-js:
+    <<: *defaults
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: yarn
+      - run:
+          name: Lint JS
+          command: yarn lint-js
+  lint-polymer:
+    <<: *defaults
+    steps:
+      - checkout
+      - run:
+          name: Install yarn dependencies
+          command: yarn
+      - run:
+          name: Install bower dependencies
+          command: bower --allow-root install
+      - run:
+          name: Lint polymer
+          command: yarn lint-polymer
+
+workflows:
+  version: 2
+  build:
+    jobs:
+      - test-site
+      - lint-content
+      - lint-style
+      - lint-js
+      - lint-polymer

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Done
+
+[List of work items including drive-bys]
+
+## QA
+
+- Check out this feature branch
+- Run the site using the command `./run serve`
+- View the site locally in your web browser at: [http://0.0.0.0:8016/](http://0.0.0.0:8016/)
+- [List additional steps to QA the new features or prove the bug has been resolved]
+
+
+## Issue / Card
+
+[List of links to Github issues/bugs and cards if needed - e.g. `Fixes #1`]
+
+## Screenshots
+
+[if relevant, include a screenshot]

.gitignore

@@ -1,5 +1,5 @@
 # [generated] Bracketed sections updated by Yeoman generator
-# generator-canonical-webteam@2.1.1
+# generator-canonical-webteam@3.2.1
 
 # [os] OS & editor files
 Desktop.ini
@@ -41,6 +41,7 @@ package-lock.json
 /parts/
 /prime/
 /stage/
+*.egg-info
 .snapcraft/
 *.snap
 _site/
@@ -50,6 +51,7 @@ _site/
 .docker-project
 .*.hash
 .envrc
+.env.local
 env/
 env[23]/
 

.stylelintrc

@@ -1,8 +1,120 @@
-extends:
-  - 'stylelint-config-polymer'
 processors:
   - 'stylelint-processor-html'
 rules:
+  'at-rule-empty-line-before':
+    - always
+    -
+      except:
+        - blockless-after-same-name-blockless
+        - first-nested
+    -
+      ignore:
+        - after-comment
+  'at-rule-name-case': lower
+  'at-rule-name-space-after': always-single-line
+  'at-rule-semicolon-newline-after': always
+  'block-closing-brace-empty-line-before': never
+  'block-closing-brace-space-before': always-single-line
+  'block-no-empty': true
+  'block-opening-brace-newline-after': always-multi-line
+  'block-opening-brace-space-after': always-single-line
+  'block-opening-brace-space-before': always
+  'color-hex-case': lower
+  'color-hex-length': short
+  'color-no-invalid-hex': true
+  'comment-empty-line-before':
+    - always
+    -
+      except:
+        - first-nested
+    -
+      ignore:
+      - stylelint-commands
+  'comment-no-empty': true
+  'comment-whitespace-inside': always
+  'custom-property-empty-line-before':
+    - always
+    -
+      except:
+        - after-custom-property
+        - first-nested
+    -
+      ignore:
+        - after-comment
+        - inside-single-line-block
+  'declaration-bang-space-after': never
+  'declaration-bang-space-before': always
+  'declaration-block-no-shorthand-property-overrides': true
+  'declaration-block-semicolon-newline-after': always-multi-line
+  'declaration-block-semicolon-space-after': always-single-line
+  'declaration-block-semicolon-space-before': never
+  'declaration-block-single-line-max-declarations': 1
+  'declaration-block-trailing-semicolon': always
+  'declaration-colon-newline-after': always-multi-line
+  'declaration-colon-space-after': always-single-line
+  'declaration-colon-space-before': never
+  'function-calc-no-unspaced-operator': true
+  'function-comma-newline-after': always-multi-line
+  'function-comma-space-after': always-single-line
+  'function-comma-space-before': never
+  'function-linear-gradient-no-nonstandard-direction': true
+  'function-max-empty-lines': 0
+  'function-name-case': lower
+  'function-parentheses-newline-inside': always-multi-line
+  'function-parentheses-space-inside': never-single-line
+  'indentation': 2
+  'keyframe-declaration-no-important': true
+  'length-zero-no-unit': true
+  'max-empty-lines': 1
+  'media-feature-colon-space-after': always
+  'media-feature-colon-space-before': never
+  'media-feature-name-case': lower
+  'media-feature-parentheses-space-inside': never
+  'media-feature-range-operator-space-after': always
+  'media-feature-range-operator-space-before': always
+  'media-query-list-comma-newline-after': always-multi-line
+  'media-query-list-comma-space-after': always-single-line
+  'media-query-list-comma-space-before': never
+  'no-eol-whitespace': true
+  'no-extra-semicolons': true
+  'no-invalid-double-slash-comments': true
+  'no-missing-end-of-source-newline': true
+  'number-leading-zero': always
+  'number-no-trailing-zeros': true
+  'property-case': lower
+  'selector-attribute-brackets-space-inside': never
+  'selector-attribute-operator-space-after': never
+  'selector-attribute-operator-space-before': never
+  'selector-combinator-space-after': always
+  'selector-combinator-space-before': always
+  'selector-list-comma-newline-after': always
+  'selector-list-comma-space-before': never
+  'selector-max-empty-lines': 0
+  'selector-pseudo-class-case': lower
+  'selector-pseudo-class-no-unknown':
+    - true
+    - ignorePseudoClasses:
+      - host
+  'selector-pseudo-class-parentheses-space-inside': never
+  'selector-pseudo-element-case': lower
+  'selector-pseudo-element-colon-notation': double
+  'selector-pseudo-element-no-unknown':
+    - true
+    - ignorePseudoElements:
+      - 'content'
+      - 'shadow'
+  'selector-type-case': lower
+  'selector-type-no-unknown':
+    - true
+    - ignoreTypes:
+      - /^[a-zA-Z]([a-zA-Z0-9]*-[a-zA-Z0-9]+)+/
+  'shorthand-property-no-redundant-values': true
+  'string-no-newline': true
+  'unit-case': lower
+  'unit-no-unknown': true
+  'value-list-comma-newline-after': always-multi-line
+  'value-list-comma-space-after': always-single-line
+  'value-list-comma-space-before': never
   'block-closing-brace-newline-after': null
   'block-closing-brace-newline-before': null
   'function-url-quotes': always

.travis.yml

@@ -21,11 +21,12 @@ We also make use of a `./run` script that we generate with our [generator-canoni
 - `./run help`: Print help.
 
 NPM/Yarn scripts:
-- `./run node yarn run serve-live`: Run local server with live content.
-- `./run node yarn run build-all`: Generate live tutorials and build live site.
-- `./run node yarn run build-site`: Build site to `build` folder.
-- `./run node yarn run build-tutorials`: Generate live tutorials.
-- `./run node yarn run polymer [args]`: Run a command through Polymer.
+- `./run exec yarn run serve-live`: Run local server with live content.
+- `./run exec yarn run build-all`: Generate live tutorials and build live site.
+- `./run exec yarn run build-site`: Build site to `build` folder.
+- `./run exec yarn run build-tutorials`: Generate live tutorials.
+- `./run exec yarn run start-server`: Start sever with production config.
+- `./run exec yarn run polymer [args]`: Run a command through Polymer.
 
 
 ### Running without Docker
@@ -48,10 +49,12 @@ $ bower install
 #### Quick start
 
 Start up a local server which watches the `examples` folder:
+
 ``` bash
-$ ./yarn run serve examples
+$ yarn run serve ./examples
 ```
-The `examples` in the command can be replaced with another path.
+
+The `./examples` in the command can be replaced with another path.
 
 
 #### Usage
@@ -63,14 +66,13 @@ Scripts are set up through the `package.json` file and run through Yarn:
 - `yarn run serve-live`: Run local server with live content.
 - `yarn run build-site`: Build site to `build` folder.
 - `yarn run build-tutorials`: Generate live tutorials.
+- `yarn run start-server`: Generate live tutorials.
 - `yarn run polymer [args]`: Run a command through Polymer.
 
 
 ## Building Your Application
 
-Running the build command will generate a `build/` folder with `bundled/` and `unbundled/` sub-folders
-containing a bundled (Vulcanized) and unbundled builds, both run through HTML,
-CSS, and JS optimizers.
+Running the build command will generate a `build/` folder with `bundled/` and `unbundled/` sub-folders containing bundled (Vulcanized) and unbundled builds. These builds are run through HTML, CSS, and JS optimizers.
 
 
 ## Dependency management
@@ -82,17 +84,25 @@ When updating NPM packages, please use `yarn add` rather than `npm install`. As
 
 ## Technology
 
-tutorials.ubuntu.com is built with Google's Polymer, using web components. You can find information about these at the following links:
 
-- https://www.polymer-project.org/1.0/
-- https://www.webcomponents.org/community/articles/why-web-components
+### Build tools
+
+The build tool for Tutorials is managed in the [ubuntu/tutorial-deployment](https://github.com/ubuntu/tutorial-deployment) repository. This is used to convert the markdown source files into HTML during the build step, using [Google's `claat`](https://github.com/googlecodelabs/tools/tree/master/claat). It is also used to run a development server which automatically rebuilds tutorials as you work on them.
 
+### API
+The `api` folder contains static json metadata which is created during build.
 
-### Our build tools
+This `tutorial-deployment` tool creates `./api/codelabs.json` which contains json metadata for all the tutorials. During the build step, some smaller API files are generated with `./bin/build-api-feeds`. These files list recent tutorials by category.
+
+### Website
+
+tutorials.ubuntu.com is built with Google's Polymer, using web components. You can find information about these at the following links:
 
-Our tooling used to serve and generate this project is available at our [Ubuntu tutorial deployment repository](https://github.com/ubuntu/tutorial-deployment).
+ - https://www.polymer-project.org/1.0/docs/
+ - https://www.webcomponents.org/community/articles/why-web-components
 
+The website app has a primary entrypoint at `./src/ubuntu-tutorials-app.html`. All traffic to the app is routed through this file and it manages the routing and state. When the website is loaded the primary `api/codelabs.json` is loaded and used to provide metadata to the website components.
 
-### Google's claat
+Tutorials are loaded via AJAX and pushed into the page as required. It loads them via URL, which are served as files from this website. These sources could be moved to a seperate server as needed, being wary of [cross origin policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
 
-Underneath the `codelabs` command, we are using [Google's `claat`](https://github.com/googlecodelabs/tools/tree/master/claat). In that repository, you will find information on the tool and how to download it.
+During the build step, the website is compiled and built into the `build` folder. This folder contains multiple builds for different browser compatibilities which can be customised in the `./polymer.json` file. The Polymer server serves the best version depending on the browser. For example, if the browser does not support the latest ES6 features Polymer will serve the bundle with polyfills to support it.