Document new repository layout

CONTRIBUTING.md

@@ -1,41 +1,3 @@
 # Contributing to Pageflow
 
-See the [GitHub wiki](https://github.com/codevise/pageflow/wiki) for
-details on how to contribute to Pageflow.
-
-## Running the Test Suite
-
-Pageflow expects credentials of a MySQL user in the environment
-variables `$PAGEFLOW_DB_USER` AND `PAGEFLOW_DB_PASSWORD`. By default
-`"root"` and the empty password are used. If your MySQL is on a
-different host, you can specify a MySQL host in the environment
-variable `$PAGEFLOW_DB_HOST` and a port in `$PAGEFLOW_DB_PORT`
-(default: 3306).
-
-Use the binstubs to invoke the Ruby test suite
-
-    $ bin/rspec
-
-or the headless browser based Javascript test suite
-
-    $ bin/teaspoon
-
-PhantomJS has to be installed on the system.
-
-The dummy Rails app used for tests is created automatically through the
-install generator during test runs. To have it regenerated,
-simply delete the contents of the `spec/dummy` directory. This is
-required everytime new migrations are added or if tests are failing
-after pulling changes into the local working tree.
-
-Pageflow can run its test suite against Rails 4.0 and 4.1
-applications. The dummy app is created by a Rails template using the
-`pageflow:install` generator. There are two ways to specify the Rails
-version to develop and test against: Either set
-`$PAGEFLOW_RAILS_VERSION` environment variable or create a
-`.rails_version` file in the project root containing the Rails version
-number. The environment variable takes precendence.
-
-Remember to delete the ignored `Gemfile.lock` and running `bundle
-install` after changing the Rails version through either of these
-methods.
+See the [Contributing section](./doc/index.md#contributing) in the guides list.

README.md

@@ -43,13 +43,15 @@ Pageflow assumes the following choice of libraries:
 * [Resque](https://github.com/resque/resque) for background jobs
 * [FriendlyId](https://github.com/norman/friendly_id) for pretty URLs
 * [Paperclip](https://github.com/thoughtbot/paperclip) for attachment handling
-* [Backbone](http://backbonejs.org/) [Marionette](http://marionettejs.com/) for client side development
+* [Backbone](http://backbonejs.org/) [Marionette](http://marionettejs.com/) for the editor
+* [React](https://facebook.github.io/react/)/[Redux](http://redux.js.org/) for the frontend
 
 ## Requirements
 
 Pageflow runs in environments with:
 
 * Ruby >= 2.1
+* Node >= 6.9.5
 * Rails 4.2
 * Redis server (for Resque)
 * A database server supported by Active Record (tested with MySQL)
@@ -85,7 +87,7 @@ Add this line to your application's Gemfile:
     # Gemfile
     gem 'pageflow'
 
-    # Required for Rails 4.1:
+    # Required for Rails 4.2 compatibility
     gem 'state_machine', git: 'https://github.com/codevise/state_machine.git'
 
 Run bundler to install dependencies:

doc/contributing/directory_layout_overview.md

@@ -0,0 +1,28 @@
+# Directory Layout Overview
+
+Pageflow consists of a two main parts:
+
+* A Rails engine packages as a gem that can be mounted into a Rails
+  application to provide the admin and the editor and serve Pageflow
+  entries. The engine is located at the root of the repository,
+  following standard Rails conventions for the directory layout.
+
+* A Node module located inside the `node_package` directory that
+  contains JavaScript built using Webpack.
+
+Historically, all of the assets (JavaScript, stylesheets and images)
+where contained in the Rails engine and built using Sprockets. With
+the move towards React and Redux for Pageflow's frontend, more and
+more of these assets will be extracted into the Node module. This is
+an ongoing process.
+
+At the moment, the Node module is not published by itself. Instead,
+Webpack outputs build products into the engine's `assets` directory
+(into `app/assets/javascripts/pageflow/dist`) where it is picked up by
+Sprockets and made available via the global variable `pageflow.react`.
+
+With Rails 5.1 support for Yarn and Webpack, it will be possible to
+let Rails applications depend on the `pageflow` node package
+directly. This opens up interesting opportunities, including
+distributing Pageflow plugins as Node packages.
+<

doc/contributing/node_package_development.md

@@ -0,0 +1,32 @@
+# Node Package Development
+
+The repository contains bin stubs to run `npm` commands inside the
+`node_package` directory.
+
+## Installing Dependencies
+
+Ensure the development machine meets the requirements listed in the
+readme. From the repository root run:
+
+    $ bin/npm install
+
+## Running the Test Suite
+
+The node package contains co-located tests inside
+`node_package/src/**/__spec__` directories. Those can run from the
+repository root:
+
+    $ bin/npm test
+
+## Running Development Watchers
+
+To invoke the Webpack build and the test suite when changing files,
+run the following command from the repository root:
+
+    $ bin/npm start
+
+## Building for Release
+
+To output a production ready build, run:
+
+    $ bin/npm build

doc/contributing/rails_engine_development.md

@@ -0,0 +1,38 @@
+# Rails Engine Development
+
+## Installing Dependencies
+
+Ensure the development machine meets the requirements listed in the
+readme. From the repository root run:
+
+    $ bundle install
+    $ bin/npm install
+
+Build node package to `assets` directory:
+
+    $ bin/npm run build
+
+## Running the Test Suite
+
+Pageflow expects credentials of a MySQL user in the environment
+variables `$PAGEFLOW_DB_USER` AND `PAGEFLOW_DB_PASSWORD`. By default
+`"root"` and the empty password are used. If your MySQL is on a
+different host, you can specify a MySQL host in the environment
+variable `$PAGEFLOW_DB_HOST` and a port in `$PAGEFLOW_DB_PORT`
+(default: 3306).
+
+Use the binstubs to invoke the Ruby test suite
+
+    $ bin/rspec
+
+or the headless browser based Javascript test suite
+
+    $ bin/teaspoon
+
+PhantomJS has to be installed on the system.
+
+The dummy Rails app used for tests is created automatically through the
+install generator during test runs. To have it regenerated,
+simply delete the contents of the `spec/dummy` directory. This is
+required everytime new migrations are added or if tests are failing
+after pulling changes into the local working tree.

doc/index.md

@@ -14,3 +14,12 @@ extend Pageflow.
 * [Creating Page types](./creating_page_types.md)
 * [Creating Widget types](./creating_widget_types.md)
 
+### Contributing
+
+Making changes to Pageflow itself. See also the
+[GitHub wiki](https://github.com/codevise/pageflow/wiki#contributing-to-pageflow)
+for high level guides on common Git workflows.
+
+* [Directory Layout Overview](./contributing/directory_layout_overview.md)
+* [Rails Engine Development](./contributing/rails_engine_development.md)
+* [Node Package Development](./contributing/node_package_development.md)