Initial version

OpenLayers-v5.x.md

@@ -0,0 +1,52 @@
+OpenLayers v5.x will be a set of ES2015 modules, similar to the v4.x [ol](https://npmjs.com/package/ol) package. The difference is that from v5.0.0 on, the sources will be authored and maintained as ES2015 modules. OpenLayers will no longer depend on and be compatible with [closure-util](https://npmjs.com/package/closure-util).
+
+## Upgrade notes
+
+### Users of the v4.x [ol](https://npmjs.com/package/ol) package
+
+Class modules will have CamelCase names, instead of the current lowercase names. This means that imports like
+
+    import Map from `ol/map`;
+
+will change to
+
+    import Map from `ol/Map`;
+
+We will be providing a code transform to automate this change.
+
+In addition to that, we will be adding named exports for modules like `ol/extent` or `ol/proj`, which will allow users to import less and get smaller build sizes. The default exports of v4.x will still work though.
+
+### Users of a full build (`ol.js` or `ol-debug.js`).
+
+The full build will still be provided, but we encourage everyone to switch to the [ol](https://npmjs.com/package/ol) package.
+
+### Users of [closure-util](https://npmjs.com/package/closure-util)
+
+If you build your application together with OpenLayers using [closure-util](https://npmjs.com/package/closure-util), we recommend to upgrade your application to use ES2015 modules instead of `goog.require` and `goog.provide`.
+
+Existing code like
+```js
+goog.provide('MyApp');
+goog.require('ol.Map');
+
+MyApp.createMap = function() {
+  return new ol.Map({});
+};
+```
+will have to be changed to
+```js
+import Map from 'ol/map';
+
+export function createMap() {
+  return new Map({});
+}
+```
+Note that ES2015, other than `goog.provide` and `goog.require`, do not assume and use global namespacing.
+
+For the build environment, you can use anything that works with ES2015 modules. Some examples (including some that use the Closure Compiler) are linked from the [ol](https://npmjs.com/package/ol) package README.
+
+As an interim solution, when working with webpack, the [closure-loader](https://www.npmjs.com/package/closure-loader) may help to make OpenLayers 5.x work with existing [closure-util](https://npmjs.com/package/closure-util) based applications.
+
+## Type definitions and type checking
+
+TBD