From d732be32ed6edd0e052995ecfe49f9f6e4301dc2 Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Mon, 31 Jul 2017 13:36:34 +0300
Subject: [PATCH] 0.8.0-alpha1

---
 CHANGELOG.md        | 59 +++++++++++++++++++++++++++++++++++++++++++++
 docs/0.8-upgrade.md | 54 +++++++++++++++++++++++++++++++++++++++++
 project.clj         |  2 +-
 3 files changed, 114 insertions(+), 1 deletion(-)
 create mode 100644 docs/0.8-upgrade.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4d4185b..819f6e4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.8.0-alpha1 (31.7.2017)
+
+**[compare](https://github.com/reagent-project/reagent/compare/v0.7.0...v0.8.0-alpha1)**
+
+**BREAKING**: Requires ClojureScript version 1.9.854
+
+This version changes how Reagent depends on React. New ClojureScript
+improves support for [npm packages](https://clojurescript.org/news/2017-07-12-clojurescript-is-not-an-island-integrating-node-modules)
+and also improves the way code can refer to objects from foreign-libs,
+making the transition from foreign libs, like Cljsjs packages, to npm easy: [global exports](https://clojurescript.org/news/2017-07-30-global-exports)
+
+Previously Reagent required foreign-lib namespace `cljsjs.react` and a few others.
+This worked well when using Cljsjs React package, but in other environments,
+like Node, React-native and when using npm packages, users had to
+exclude Cljsjs packages and create empty files providing these `cljsjs.*` namespaces.
+
+With global-exports, foreign-libs can be used like they were real namespaces:
+
+```cljs
+(ns ... (:require [react-dom :as react-dom]))
+
+(react-dom/render ...)
+```
+
+The same code will in all the environments, and is compiled different based on
+compile target and on how the dependency is provided. When targeting
+browser and using foreign libs, ClojureScript compiler uses the `:global-exports`
+definition to resolve the function from global JS var:
+
+```js
+var a = window.ReactDOM;
+a.render(...)
+```
+
+When targeting browser but using node_modules with Closure module processing,
+the CommonJS (or ES6) module is converted to a Closure module, named
+by `module$` and the path of the file, and the generated code is same as
+if this was a Cljs or Closure module:
+
+```js
+module$foo$bar$react$react-dom.render(...)
+```
+
+Then targeting NodeJS the object is retrieved using `require` call:
+
+```js
+var a = require("react-dom");
+a.render(...)
+```
+
+This change requires use of ClojureScript 1.9.854, using the latest Cljsjs
+React packages (15.6.1-1), and it is not yet sure how well other React
+libraries work with these changes, or how this will work with React-native.
+Currently it looks like all the Cljsjs React libraries need to be updated
+to use require `react` instead of `cljsjs.react`, as the foreign-lib
+namespace was renamed to match the npm package.
+
+Read [0.8 upgrade guide](./docs/0.8-upgrade.md) for more information.
+
 ## 0.7.0 (27.6.2017)
 
 **[compare](https://github.com/reagent-project/reagent/compare/v0.6.2...v0.7.0)**
diff --git a/docs/0.8-upgrade.md b/docs/0.8-upgrade.md
new file mode 100644
index 0000000..39798a1
--- /dev/null
+++ b/docs/0.8-upgrade.md
@@ -0,0 +1,54 @@
+# 0.8 Upgrade guide
+
+The necessary changes depend on what environment you target, and
+how you want to provide React.
+
+## Browser - Cljsjs
+
+Using Reagent itself with Cljsjs packages doesn't require changes,
+other than making sure you depend on the latest Cljsjs React packages,
+if you have direct dependencies to them.
+
+If you use additional React packages, you need to update Cljsjs packages
+for these to use new React foreign-lib name, `react` instead of `cljsjs.react`.
+**Subject to change, if this can be solved easily.**
+
+## Browser - node modules
+
+You can use `:npm-deps` and `:install-deps` compiler options to
+install the packages automatically.
+
+If `react`, `react-dom` and `create-react-class` are available in `node_modules`
+directory, ClojureScript compiler will use these with Reagent. **This
+doesn't depend on use of `:npm-deps` option!** `:npm-deps` option is only about
+installing the dependencies, if packages are available in `node_modules`
+directory, they will be used.
+
+You can use `:shim-process` compiler option to provide `process.env.NODE_ENV`
+constant which is used by JS code to enable development and production
+builds. ClojureScript compiler will automatically set this constant to
+`production` value when using `:advanced` optimizations. This enables
+the React production build.
+
+## NodeJS
+
+Install `react`, `react-dom` and `create-react-class` npm packages,
+and ClojureScript should automatically use `require` to
+load React for Reagent.
+
+## Electron
+
+???
+
+## React-native
+
+https://github.com/drapanjanas/re-natal/issues/128
+
+## Common Problems
+
+### Mismatch with Cljsjs and npm packages
+
+If you have one npm package installed, e.g. `react`, you also need
+to provide others (`react-dom` and `create-react-class`), else
+Cljsjs packages would be used for these, and packages from different sources
+don't work together.
diff --git a/project.clj b/project.clj
index c7a58db..989b6be 100644
--- a/project.clj
+++ b/project.clj
@@ -1,4 +1,4 @@
-(defproject reagent "0.8.0-SNAPSHOT"
+(defproject reagent "0.8.0-alpha1"
   :url "http://github.com/reagent-project/reagent"
   :license {:name "MIT"}
   :description "A simple ClojureScript interface to React"