Merge "Spec for ECMAScript 2015 and Transpiler support"

doc/source/specs.rst

@@ -34,6 +34,7 @@ permits.
    :maxdepth: 1
 
    specs/devstack
+   specs/es2015.rst
 
 
 Implemented Specifications

doc/source/specs/es2015.rst

@@ -0,0 +1,187 @@
+::
+
+  Copyright 2016 Hewlett Packard Development Corporation, L.P.
+
+  This work is licensed under a Creative Commons Attribution 3.0
+  Unported License.
+  http://creativecommons.org/licenses/by/3.0/legalcode
+
+..
+
+===========================
+Support for ECMAScript 2015
+===========================
+
+We need to make a decision on what language this project will use, and
+whether we will transpile to other languages. If we want to use a transpiler,
+we need to support it both for Node.js and browser builds and tests.
+
+Problem Description
+===================
+
+There are four languages currently in active use in the JavaScript community.
+ECMAScript 2015, ECMAScript 5, CoffeeScript, and TypeScript. It also needs to
+support multiple runtimes: Browser and Node.js. We need to settle on which
+language to use, and how to support all of our targeted runtimes.
+
+Proposed Change
+===============
+
+This project will use ECMAScript 2015 as its primary language. Support for
+projects that do not support this language will be provided using Babel as
+a transpiler.
+
+Setting up Babel
+----------------
+
+Babel should be configured using `.babelrc` file, so that configuration will
+be used for all the environments we're targeting.
+
+.. code-block:: json
+
+  {
+    "presets": ["es2015"]
+  }
+
+Node.js Build
+-------------
+
+We're targeting Node.js v4, which doesn't support all the ES2015 features, so
+usage of Babel is required. Babel can be integrated by specifying `prepublish`
+hook which runs Babel to transpile library's code and overriding main module in
+`package.json`.
+
+.. code-block:: json
+
+  {
+    "main": "./dist/index.js",
+    "scripts": {
+      "build": "babel ./src --out-dir ./dist",
+      "prepublish": "npm run build"
+    }
+  }
+
+Browser Build
+-------------
+
+Webpack will be used to create ES5 builds which are intended to run in
+browsers. `babel-loader` should be used to integrate Webpack and Babel.
+
+Since `node-fetch` module which is used for sending HTTP requests isn't
+supposed to be run in browser environments, it should be substituted with
+`whatwg-fetch` polyfill using Webpack's `node` configuration option.
+
+Here is an example of `webpack.config.js` file:
+
+.. code-block:: javascript
+
+  module.exports = {
+    entry: [
+      './src/index.js'
+    ],
+    output: {
+      path: require('path').join(__dirname, '/dist/browser/'),
+      chunkFilename: null,
+      filename: 'openstack-lib-browser.js',
+      sourceMapFilename: 'openstack-lib-browser.js.map'
+    },
+    module: {
+      loaders: [
+        {
+          test: /\.js$/,
+          loader: 'babel',
+          exclude: [/node_modules\//],
+          query: {cacheDirectory: true}
+        }
+      ]
+    },
+    node: {
+      "node-fetch": "whatwg-fetch"
+    }
+  };
+
+Node.js Testing
+---------------
+
+It was agreed that we're using Jasmine for tests. Jasmine can be easily
+integrated with Babel by adding the following entry to `jasmine.json`:
+
+.. code-block:: json
+
+  {
+    "helpers": [
+      "../node_modules/babel-register/lib/node.js"
+    ]
+  }
+
+Browser Testing
+---------------
+
+One of the popular test runners Karma can be easily integrated with Babel and
+Webpack using `karma-webpack` plugin. There is also `karma-babel-preprocessor`
+module, but it's not needed since integration with Babel is described in
+`webpack.config.js` file.
+
+Here is an example of `karma.conf.js` file:
+
+.. code-block:: javascript
+
+module.exports = function(config) {
+  config.set({
+    browsers: ['Chrome', 'Firefox'],
+    plugins: [
+      'karma-webpack'
+    ],
+    preprocessors: {
+      'tests/**/*.js': ['webpack']
+    },
+    webpack: require('./webpack.config')
+  });
+};
+
+Gulp Integration
+----------------
+
+The latest version of Gulp can be easily integrated with Babel just by renaming
+`gulpfile.js` to `gulpfile.babel.js`. Gulp will transpile the Gulpfile using
+Babel configuration from `.babelrc` file.
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  vkramskikh
+
+Gerrit Topic
+------------
+
+Use Gerrit topic "jsdk_es2015" for all patches related to this spec.
+
+.. code-block:: bash
+
+    git-review -t jsdk_es2015
+
+Work Items
+----------
+
+* Babel and related dependencies should be added.
+* Babel configuration should be added.
+* Jasmine and Karma configuration files should be updated to support Babel.
+* Webpack should be added and configured to use Babel.
+* NPM scripts to run node/browser builds/tests should be added to package.json.
+
+Documentation
+-------------
+
+We will need project setup documentation for browsers and node applications.
+All documentation code samples should include examples using all available
+languages.
+
+Testing
+-------
+
+* All code samples should be tested.
+* Our test suite should be run separately on each transpiled artifact.