From c7286cc7d37ef1d39e4fe09b8d2e8458a2d0e9d7 Mon Sep 17 00:00:00 2001 From: Michael Krotscheck Date: Tue, 21 Jun 2016 12:58:09 -0700 Subject: [PATCH] Spec for ECMAScript 2015 and Transpiler support This spec describes how we're going to handle delivering artifacts to more than one platform. Change-Id: I42fa0754c08ecd05891f31f87d7c046b5fc8bc07 --- doc/source/specs.rst | 1 + doc/source/specs/es2015.rst | 187 ++++++++++++++++++++++++++++++++++++ 2 files changed, 188 insertions(+) create mode 100644 doc/source/specs/es2015.rst diff --git a/doc/source/specs.rst b/doc/source/specs.rst index 82b6c44..59ff957 100644 --- a/doc/source/specs.rst +++ b/doc/source/specs.rst @@ -34,6 +34,7 @@ permits. :maxdepth: 1 specs/devstack + specs/es2015.rst Implemented Specifications diff --git a/doc/source/specs/es2015.rst b/doc/source/specs/es2015.rst new file mode 100644 index 0000000..d13c722 --- /dev/null +++ b/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.