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
This commit is contained in:
Michael Krotscheck 2016-06-21 12:58:09 -07:00 committed by Vitaly Kramskikh
parent 81f50b8b99
commit c7286cc7d3
2 changed files with 188 additions and 0 deletions

View File

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

187
doc/source/specs/es2015.rst Normal file
View File

@ -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.