Docs update

_config.yml

@@ -55,7 +55,9 @@ defaults:
   - scope:
       path: "_docs/04-source"
     values:
-      layout: splash
+      layout: single
+      sidebar:
+        nav: "source"
   - scope:
       path: "_docs/05-roadmap"
     values:

_data/navigation.yml

@@ -77,4 +77,10 @@ concepts:
       - title: "State Persistence"
         url: /concepts/esp-js-ui/state-persistence/
       - title: "Logging"
-        url: /concepts/esp-js-ui/logging/
+        url: /concepts/esp-js-ui/logging/
+
+source:
+  - title: Overview
+    url: /source/
+  - title: Releasing
+    url: /source/releasing/

_docs/01-concepts/01-esp-js/02-event-router.md

@@ -14,12 +14,8 @@ The below diagram shows it's core interfaces.
 
 The snippet below shows each interface being used.
 
-<p class="codepen" data-height="605" data-theme-id="dark" data-default-tab="js" data-user="KeithWoods" data-slug-hash="RwPGKdx" style="height: 605px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="ESP Router API Example">
-  <span>See the Pen <a href="https://codepen.io/KeithWoods/pen/RwPGKdx">
-  ESP Router API Example</a> by Keith (<a href="https://codepen.io/KeithWoods">@KeithWoods</a>)
-  on <a href="https://codepen.io">CodePen</a>.</span>
-</p>
-<script async src="https://static.codepen.io/assets/embed/ei.js"></script>
+<script src="https://gist.github.com/KeithWoods/08d96239c6805a69582953bcc08a6ebd.js"></script>
+
 <br />
 
 The registered model will always be some form of JavaScript object, in the above an object literal.

_docs/01-concepts/02-esp-js-polimer/01-index.md

@@ -18,3 +18,13 @@ Overview of the bits:
   The state handlers are responsible for updating those states.
 * [Event Streams](./04-event-streams.md) - these streams simply have 'event in, event out' semantics. 
   They are RXJS observable streams which are used for side effects and asynchronous operations.   
+
+## External Dependencies
+
+{% include draftdocs.html %}
+
+esp-js-polimer relies on lerna, but it does not re bundle it.
+
+TODO update guidance here   
+
+

_docs/04-source/index.md → _docs/04-source/01-index.md

@@ -3,8 +3,6 @@ title: Source
 permalink: /source/
 ---
 
-# Source
-
 You can find all the esp packages on github: [github.com/esp/esp-js](https://github.com/esp/esp-js).
 
 All package have TypeScript declaration files. 

_docs/04-source/02-releasing.md

@@ -0,0 +1,58 @@
+---
+title: Releasing
+permalink: /source/releasing/
+---
+
+This document describes how to push the esp packages to npm.
+It's a reference for the maintainers.
+
+The project is published using [Lerna](https://github.com/lerna/lerna).
+
+There is explicit configuration for the lerna publish command in `lerna.json` so the below should be read with that in mind.
+
+The root `package.json`  has script targets for the most common publishing scenarios:
+
+```
+{
+  ...
+  "scripts": {
+    ...
+    "release-major": "yarn clean && yarn build-prod && lerna publish major",
+    "release-minor": "yarn clean && yarn build-prod && lerna publish minor",
+    "release-patch": "yarn clean && yarn build-prod && lerna publish patch",
+    "pre-release-major": "yarn clean && yarn build-prod && lerna publish premajor --preid next --dist-tag next",
+    "pre-release-minor": "yarn clean && yarn build-prod && lerna publish preminor --preid next --dist-tag next",
+    "pre-release-patch": "yarn clean && yarn build-prod && lerna publish prepatch --preid next --dist-tag next"
+  },
+  ...
+}
+```
+
+Each of these scripts:
+* Builds and tests all the code.
+* Uses lerna to bump the version, make a commit and push to the current branch.
+* If using a  `pre-release-x` script target, the package version will include a preid (e.g. `esp-js-ui@2.1.0-next.0`) and will push to npm using a non 'latest' dist tag, e.g. 'next'
+  This will stop a default `yarn install esp-js` from pulling the pre release  packages.
+
+Procedure
+
+Releases are carried out on a release branch named `release-x.x.x` (namings with a slash, i.e. `release/x.x.x` currently not supported due to a lerna error).
+Simply run the appropriate yarn command, e.g: `yarn release-minor`.
+
+If you have some issues with the above, lerna may have already pushed some tags which you'll have to delete before trying again:
+
+```
+// Delete locally
+git tag -d vx.x.x
+// Delete remotely
+git push --delete origin vx.x.x
+```
+
+Once the release has been pushed:
+
+1. Raise and merge a PR to master
+1. Manually create an explicit release on the GitHub UI
+
+### Reference  
+* [lerna version docs](https://github.com/lerna/lerna/tree/master/commands/version#readme).
+* [lerna publish docs](https://github.com/lerna/lerna/tree/master/commands/publish#readme). 

index.md

@@ -12,7 +12,7 @@ ESP was born out of the need to manage complex streaming state in reactive appli
 A pitfall of pure reactive applications is that state gets held up in observable sequences, there is no central business model to manage state in these sequences.
 Streaming reactive patterns are great for pure data or event procurement, triggering workflows and so on, however are poor for complex business modeling.
 Inherently, observable logic often gets intermingled with business modeling making both reasoning and maintenance hard.
-Business modeling requires a more structured approach that's free from observable plumbing, easy reason with, easy to test and easier to maintain. 
+Business modeling requires a more structured approach that's free from observable plumbing, easier to reason with, test and maintain. 
 
 ESP solves this by placing an ordered queue of state change events in front of a well structured model.
 The models in your application can be either immutable or object oriented, and are by and large free from reactive plumbing concerns.