Release-Notes-for-AppKit-1.0.md

+## App Kit 1.0 Ruby Gems
+
+Main web app gems:
+
+* osc_machete_rails (1.0.0) - for building Rails based web apps
+* awesim_rails (1.0.0) - AweSim branding and helpers
+* awesim_rails_logging (1.0.0) - logging modification to eventually support log access for developers
+
+Utility gems
+
+* osc-reservations (1.0.0) - for accessing reservation information
+* osc-vnc (1.0.0) - for starting VNC sessions
+
+Dependencies
+
+* osc-machete (1.0.0) - dependency of osc_machete_rails
+* pbs (1.0.0) - dependency of multiple gems: uses Torque C libraries to qsub, qstat, and qdel jobs
+
+## How to get it
+
+* For preexisting apps, follow the migration plan at the bottom of this document.
+* For new apps, just run `awesim rails new` to generate a new app. It will already be configured to use the new code.
+
+## Overview of new features and changes
+
+* **Re-architecture**: All rails specific code is moved into osc_machete_rails gem (a rails engine) from osc-machete gem
+  * Better test coverage – Rails specific integration and unit tests
+  * Enables us to eventually add shared models, controllers, views to provide developers default solutions to problems without developers having to write a single line of code
+  * Enables us to add generators for quickly scaffolding code required to manage a simulation
+* **Rails generators for building workflows**
+  * From the very beginning of choosing Rails to build the App Kit we envisioned having generators to quickly scaffold an application. Now we have this.
+  * Custom rails generators turns a multi-step process into a single command run from the terminal. Generator creates workflow and job models, associated controllers, views, and a default job template, including the database migrations necessary to support these
+  * Reduces what new developers need to learn to get started
+  * Saves development time
+* **Error handling**
+  * We now properly handle errors from qstat, qsub, or qdel. Exceptions are thrown and are handled appropriately by the default controllers to both log the error and display a helpful error message to the user
+  * We can more quickly determine during development why things are not working
+  * We better protect against the state of simulations from being corrupted when something goes wrong
+* **Reduced complexity in dealing with simulation status**
+  * Previously, status was represented as a character, the same one that was, putting the onus on the developer to know what these characters meant and what user friendly strings to use in their place
+  * We now use a Status value object to encapsulate the complexity, reducing the amount of code we need to maintain
+  * These changes are (mostly) backwards compatible with current apps
+* **Better documentation**
+  * Tutorials
+  * Short migration plan
+  * Documentation to address problems previously addressed in email exchanges with developers
+* **Support for submitting jobs to the Ruby cluster**
+* **Speeds up app development**
+  * Generators, status value, other additions shorten time to develop app
+  * Having a rails engine will allow us to eventually make a certain class of applications buildable in minutes, using just configuration (no code modifications required)
+* **Backwards compatibility with preexisting database schemas.** Developers have the option to port existing apps and it will not require a database migration, so existing users can use the updated app
+* **Handle simulation deletion properly**: When deleting a simulation, we handle qdel-ing jobs and removing the simulation directory automatically. Before developers had to manually manage this.
+
+## Details
+
+For a list of all the changes made, see:
+
+* [osc-machete changelog](https://github.com/AweSim-OSC/osc-machete/blob/master/CHANGELOG.md#100---2016-02-03) 
+* [osc_machete_rails changelog](https://github.com/AweSim-OSC/osc_machete_rails/blob/master/CHANGELOG.md#100---2016-02-03)
+
+Bugfixes include:
+
+* `update_status!` on the `Job` models (models that include `OscMacheteRails::Statusable`) is called at beginning of each request instead of in the `after_find` hook, so you no longer need to preload to trigger the update (a big hangup we had earlier for each new developer)
+* even if you did preload for the `Job` models, superfluous sql calls were being made for each model - this was eliminated
+* with the latest version of torque new status values were causing problems with status display on simulations. Introducing the Status value object fixed this problem
+* proper error handling avoided various odd behavior that resulted if job submission failed
+  * i.e. `TorqueHelper#qstat`, used by `Job#status` would return nil if the job completed or if an error occurred with `qstat` shell command; now `TorqueHelper#qstat` throws exception in error cases and returns a valid `Status` value otherwise
+
+## Migrating existing apps
+
+* Some breaking changes were introduced in App Kit 1.0. [This page explains how to update your app](Port-an-existing-app-to-AppKit-1.0) so you can use the latest versions of each gem.