added wip to all pages as needed

Author: catmando

docs/README.md

@@ -1,7 +1,5 @@
 # Welcome
 
-## Hyperstack
-
 Hyperstack is a Ruby-based DSL and modern web toolkit for building spectacular, interactive web applications fast!
 
 * **One language** throughout the client and server. All Ruby code is compiled by [Opal](https://opalrb.com/) into JavaScript automatically.
@@ -23,11 +21,14 @@ end
 
 In the code above, if the `good_books` scope changed \(even on the server\), the UI would update automatically. That's the magic of React and Isomorphic Models with bi-directional data at work!
 
-## Website and documentation
+## Website and Documentation
+
+<img align="left" width="100" height="100" style="margin-right: 20px" src="https://github.com/hyperstack-org/hyperstack/blob/edge/docs/wip.png?raw=true">
 
-* Website: [hyperstack.org](https://hyperstack.org)
+While we have over 1000 specs passing, in 3 different configurations, and several large apps using Hyperstack, documentation is a lagging.  If you see this icon it means we are working hard to
+get the docs up to the same state as the code.
 
-Our website serves as a Hyperstack example application. All the doc content is loaded dynamically from this repo and converted to HTML on the fly. It uses React Semantic UI and a client-side JavaScript full-text search engine. Its a Rails app hosted on Heroku.
+Chapters without the work-in-progress flag, are still draft, and any issues are greatly appreciated, or better yet follow the `Edit on Github` link make your propsed corrections, and submit a pull request.
 
 ## Setup and installation
 
@@ -45,9 +46,9 @@ Hyperstack is supported by a friendly, helpful community, both for users, and co
 
 ## Roadmap
 
-Hyperstack is evolving; we are improving it all the time. As much as we love Ruby today, we see ourselves embracing new languages in the future. [Crystal](https://crystal-lang.org/) perhaps? We are also watching [Wasm](https://webassembly.org/) carefully.
+We are currently driving towards our 1.0 release.  Currently we are at 1.0.alpha1.5 release candidate.  There is a list of 163 open issues including some bugs, many requested enhancements.  The plan is to triage the issues, and do a weekly release until the issues are closed as deemed not needed for a 1.0 release.  
 
-Please see the [ROADMAP](https://github.com/hyperstack-org/hyperstack/blob/edge/ROADMAP.md) for more information.
+Please consider contributing by grabbing a "good first issue", or just adding your thoughts, thumbs up, or down on any issues that interest you.
 
 ## Contributing
 

docs/SUMMARY.md

@@ -27,19 +27,18 @@
   * [Further Reading](client-dsl/further-reading.md)
 * [HyperState](hyper-state/README.md)
 * [HyperRouter](hyper-router/README.md)
-* [HyperModel](isomorphic-dsl/README.md)
-  * [Isomorphic Models](isomorphic-dsl/hyper-model.md)
-* [Isomorphic Operations](isomorphic-dsl/hyper-operation.md)
-  * [Policies](isomorphic-dsl/hyper-policy.md)
-* [Internationalization](development-workflow/hyper-i18n.md)
-* [Development Workflow](development-workflow/README.md)
+* [HyperModel](hyper-model/README.md)
+* [Operations](operations/README.md)
+* [Policies](policies/README.md)
+* [Internationalization](internationalization/README.md)
+* [Development Workflow and Procedures](development-workflow/README.md)
   * [Debugging](development-workflow/debugging.md)
+  * [HyperTrace](development-workflow/hyper-trace.md)
   * [HyperSpec](development-workflow/hyper-spec/README.md)
     * [Installation](development-workflow/hyper-spec/01-installation.md)
     * [Tutorial](development-workflow/hyper-spec/02-tutorial.md)
     * [Methods and Features](development-workflow/hyper-spec/03-methods-and-features.md)
     * [Using with Rack](development-workflow/hyper-spec/04-using-with-rack.md)
-  * [Tools](development-workflow/tools.md)
   * [Deploy To Heroku](development-workflow/deploy-to-heroku.md)
 * [Tutorial](tutorial/README.md)
   * [TodoMVC Tutorial Part I](tutorial/todo.md)

docs/development-workflow/README.md

@@ -1,2 +1 @@
-# Development Workflow
-
+# Development Tools and Procedures

docs/development-workflow/debugging.md

@@ -1,24 +1,29 @@
-# Debugging
+Debugging any UI code is difficult.  Hyperstack's declarative approach, and lack of redundant boilerplate helps a lot.  Simply having 1/4 the code base
+to deliver the same functionality is going to make things easier.
 
-**Work in progress - ALPHA \(docs and code\)**
+However all that said, **Debugging UI Code is Difficult.**  The UI's main job is to deal with events coming from multiple directions and unpredictable sources, this makes tracking down failures difficult as timing can become an issue.
 
-## Debugging tips
-
-Tips, good practice will help you debugging your Hyperstack application.
+Here are few tips to go along with the other tools in this section (HyperSpec and HyperTrace) to make your life a bit easier.
 
 ### JavaScript Console
 
-At any time during program execution you can breakout into the JavaScript console by simply adding a line of back-ticked JavaScript to your ruby code:
+At any time during program execution you can breakout into the JavaScript console by simply adding the debugger keyword to your Ruby code.
 
-`debugger;`
+If you have source maps turned on you will then be able to see your ruby code \(and the compiled JavaScript code\) and set browser breakpoints, examine values and continue execution.
 
-If you have source maps turned on you will then be able to see your ruby code \(and the compiled JavaScript code\) and set browser breakpoints, examine values and continue execution. See Opal Source Maps if you are not seeing source maps.
+> Important Note:  The Opal compiler will not handle the `debugger` keyword at the end of blocks, method definitions, or begin..end statements.  
+```ruby
+def buggy_method
+  ...
+  debugger # this will break add any expression on the next line to fix
+end
+```
 
-You can also inspect ruby objects from the JavaScript console.
+You can also inspect Ruby objects from the JavaScript console.  The mapping between the Javascript and Ruby is fairly easy to follow thanks to the great Opal team.
 
 Here are some tips: [https://dev.mikamai.com/2014/11/19/3-tricks-to-debug-opal-code-from-your-browser/](https://dev.mikamai.com/2014/11/19/3-tricks-to-debug-opal-code-from-your-browser/)
 
-### Puts is your friend
+### The `puts` method is your friend
 
 Anywhere in your HyperReact code you can simply puts any\_value which will display the contents of the value in the browser console. This can help you understand React program flow as well as how data changes over time.
 
@@ -51,3 +56,15 @@ class Thing < Hyperstack::Component
 end
 ```
 
+### HyperTrace
+
+Sometimes popping in a trace can reveal a lot about what is going on.  [HyperTrace](hyper-trace.md) wraps your selected method calls in
+a dump of incoming parameters, instance variable state, and return values.  You can also setup conditional
+breakpoints.  So keep HyperTrace handy in your tool belt.
+
+### HyperSpec
+
+IMHO the best debugging tool is a spec.  As soon as you start creating a new feature, or find a bug, start
+writing a spec.  Once you can reproduce the problem by running a spec, you are 90% of the way to fixing the problem,
+and you will have another spec to add to your tests, making your app more robust.  [HyperSpec](hyper-spec/README.md) extends RSpec so that
+can control and interrogate the client from within your specs, using Ruby code.

docs/development-workflow/deploy-to-heroku.md

@@ -0,0 +1,50 @@
+There are a number of issues and additional items that need to been done when deploying to Heroku (or other production environments.)
+Even if not deploying to Heroku these steps will cover most of the gotchas that you will encounter.
+
+If you do find any problems please log an issue, or better yet do a pull request on this page.
+
+1. **You need to use postgresql rather than sqlite or mysql.**  You can find instructions on how to do this online, or better yet when you create your rails app, create it from the beginning with postgresql:  https://www.digitalocean.com/community/tutorials/how-to-set-up-ruby-on-rails-with-postgres
+
+2. **Remove `app/models/application_record.rb`**  This is no longer needed due to a recent rails fix, and confuses Heroku.
+
+3. **Use harmonly uglifier.**  In config/environments/production.rb you need to change this line from:  
+`config.assets.js_compressor = :uglifier`   
+to  
+`config.assets.js_compressor = Uglifier.new(harmony: true)`  
+
+4. **Insure webpacker:compile occurs before assets:precompile:** at the end of the `Rakefile` (in the root directory)  add this line:  
+`Rake::Task["assets:precompile"].enhance(['yarn:install', 'webpacker:compile'])`
+
+5. **Setup your database** Make sure you run   
+`Heroku run rake db:migrate`
+
+6. **Update your production policies** By default the Hyperstack installer will leave your Policies wide open but **not** in production.   
+For a production app you will want to add restrictive Policies to protect your data.  If you just want to get things working on Heroku you can remove the guard from the end of the `policies/application.rb` file.
+
+5. Add `stylesheet_pack_tag`s:   Hyperstack does not automatically pull in the `.css` packs.  Instead you have to add one or both these lines to your layouts, if you are requiring css assets in the pack files:  
+`<%= stylesheet_pack_tag    'client_only' %>`    
+If you are requiring css libraries in the `client_only.js` pack file   
+and    
+`<%= stylesheet_pack_tag    'client_and_server' %>`   
+ If you are requiring css libraries in the `client_and_server.js` pack file
+
+6. Setup ActionCable (see [full instructions](https://blog.Heroku.com/real_time_rails_implementing_websockets_in_rails_5_with_action_cable#deploying-our-application-to-Heroku) for details)
+provision Redis on Heroku `Heroku addons:add redistogo`  
+then get the Heroku url: `Heroku config --app action-cable-example | grep REDISTOGO_URL`  
+use the url in config/cable.yml (in the production section)  
+in config/environments/production.rb add these two lines:   
+`config.web_socket_server_url = "wss://your-app.Herokuapp.com/cable" `  
+`config.action_cable.allowed_request_origins = ['https://your-app.Herokuapp.com', 'http://action-your-app.Herokuapp.com']`
+
+### On Going Development
+
+After updating anything in the hyperstack initializer you will need to force Heroku to clear the cache:
+
+First install the Heroku-repo plugin (on your console)
+`$ Heroku plugins:install Heroku-repo`
+
+and then to clear the cache do:
+
+`$ Heroku repo:purge_cache -a appname`
+`$ git commit --allow-empty -m "Purge cache"`
+`$ git push Heroku master`

docs/development-workflow/hyper-trace.md

@@ -0,0 +1,6 @@
+<img align="left" width="100" height="100" style="margin-right: 20px" src="https://github.com/hyperstack-org/hyperstack/blob/edge/docs/wip.png?raw=true">
+HyperTrace provides a simple way to log information to the Javascript console.  You get a real time display of the parameters being passed to
+the traced methods, the state of their instance variables, and the return values.  You can also set conditional breakpoints so you can stop execution
+and dig deeper from the Javascript console.
+
+## This Page Under Construction

docs/development-workflow/tools.md

@@ -1,6 +1,9 @@
-# Isomorphic Models
+<img align="left" width="100" height="100" style="margin-right: 20px" src="https://github.com/hyperstack-org/hyperstack/blob/edge/docs/wip.png?raw=true">
+HyperModel extends Rails ActiveRecord models so that you have direct access to them on the client, using the same ActiveRecord classes and methods as you
+would on the server.  Nothing new to learn, or configure, just plug in and go.
+
+## This Page Under Construction
 
-**Work in progress - ALPHA \(docs and code\)**
 
 In Hyperstack, your ActiveRecord Models are available in your Isomorphic code.
 
@@ -694,4 +697,3 @@ You can of course simulate server side changes to your Models through this conso
 * **On page load you get a message about super class mismatch for `DummyValue`** You are still have the old `reactive-record` gem in your Gemfile, remove it from your gemfile and your components manifest.
 * **On page load you get a message about no method `session` for `nil`** You are still referencing the old reactive-ruby or reactrb gems either directly or indirectly though a gem like reactrb-router. Replace any gems like `reactrb-router` with `hyper-router`. You can also just remove `reactrb`, as `hyper-model` will be included by the `hyper-model` gem.
 * **You keep seeing the message `WebSocket connection to 'ws://localhost:3000/cable' failed: WebSocket is closed before the connection is established.`** every few seconds in the console. There are probably lots of reasons for this, but it means ActionCable can't get itself going. One reason is that you are trying to run with Passenger instead of Puma, and trying to use `async` mode in cable.yml file. `async` mode requires Puma.
-

docs/isomorphic-dsl/hyper-model.md renamed to docs/hyper-model/README.md

@@ -1,6 +1,12 @@
-# Client-side Routing
 
-HyperRouter is a DSL wrapper for [ReactRouter v4.x](https://github.com/ReactTraining/react-router) to provide client-side routing for Single Page Applications (SPA).
+<img align="left" width="100" height="100" style="margin-right: 20px" src="https://github.com/hyperstack-org/hyperstack/blob/edge/docs/wip.png?raw=true">
+**HyperRouter is a DSL wrapper for [ReactRouter v4.x](https://github.com/ReactTraining/react-router) to provide
+client-side routing for Single Page Applications (SPA).  As the user changes "pages" instead of reloading from the server your App will mount
+different components.**
+
+## This Page Under Construction
+
+
 
 ## Usage
 

docs/hyper-router/README.md

@@ -1,6 +1,6 @@
 
 <img align="left" width="100" height="100" style="margin-right: 20px" src="https://github.com/hyperstack-org/hyperstack/blob/edge/docs/wip.png?raw=true">
-**The `Hyperstack::State::Observable` module allows you to build  
+**The `Hyperstack::State::Observable` module allows you to build
 classes that share their state with Hyperstack Components, and have those components update when objects in those classes change state.**
 
 ## This Page Under Construction