Announcing Scala.js 0.6.13. #314

sjrd · 2016-10-13T14:45:58Z

Also make relevant changes to the documentation.

sjrd · 2016-10-13T14:47:25Z

Review by @gzm0

I have not yet written documentation for @JSImport and scalaJSModuleKind, other than what is in the release notes.

Tentative announcement date: Monday 17.

sjrd · 2016-10-13T14:48:17Z

Changes to the tutorial can be previewed in this branch: https://github.com/scala-js/scalajs-tutorial/tree/0.6.13-preview

gzm0

Review for release notes only. Will review doc changes later.

gzm0 · 2016-10-13T14:49:42Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+
+We are excited to announce the release of Scala.js 0.6.13!
+
+This release one particularly anticipated feature: the ability to generate CommonJS modules with Scala.js!


This release contains one particularly [...]

gzm0 · 2016-10-13T14:53:09Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+
+We decided to standardize on Node.js for all command-line executions by default because it is always the best alternative.
+Rhino is extremely slow.
+Using by default, although working out-of-the-box, caused a number of users to stick to it and discovering months or years later that their tests could run 10x-100x faster by switching to Node.js.


Consider rephrasing to: Although using it by default works out-of-the-box, it caused a number of users to stick to it and discover months [...] faster just by switching to Node.js.

gzm0 · 2016-10-13T14:53:45Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+ Rhino is however *deprecated*, and will not be supported anymore in 1.0.0.
+* PhantomJS: `jsEnv := PhantomJSEnv().value`.
+
+Also, remember that you can also use Selenium with Scala.js, using [scalajs-env-selenium](https://github.com/scala-js/scala-js-env-selenium).


Double "also"

gzm0 · 2016-10-13T14:55:35Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+
+Emitting CommonJS modules is also not compatible with `persistLauncher := true`, as a different launcher needs to be emitted for fastOpt versus fullOpt.
+
+### Importing stuff from other CommonJS modules


You absolutely should add a disclaimer here, that jsDependencies support for this is pending and that this will only work for builds that manage their JS dependencies externally.

gzm0 · 2016-10-13T14:56:30Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+
+{% highlight scala %}
+@js.native
+@JSImport("bar.js", JSImport.Default) // JS: import bar from "bar.js"


Default or Namespace?

Default, as we're mostly in the section about CommonJS modules, which implies that your (CommonJS) dependencies are necessarily of the "legacy" sort.

gzm0 · 2016-10-13T14:58:05Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+val result = Bar.aFunction(5) // JS: bar.aFunction(5)
+{% endhighlight %}
+
+When importing an actual ECMAScript 2015 module (as opposed to a CommonJS module), you should use `JSImport.Namespace` instead of `JSImport.Default`:


What do you mean by importing an actual ECMAScript 2015 module? We don't have ES2015 import support yet. Also, why should one specifically use a Namespace import? Isn't whatever import type one needs fine?

This part is weird, I agree. As long as we don't have ES6 module support per se, there is probably no real reason to use a JSImport.Namespace.

It might make sense if someone has an ES6 bundling pipeline, and configures it to understand CommonJS in addition (somehow, by auto-converting or something).

Maybe we should just leave out this part, and always recommend Default for now. At least in the release notes, where we don't have much space to explain all the subtleties.

So initially I wanted to first show Namespace, and only then Default. Namespace is more logical in combination with the first example.

In theory, when importing from legacy modules, the first example is wrong. It should be @JSImport("bar.js", "default.Foo"), so that it has the following ES semantics:

import bar from "bar.js" new bar.Foo(5);

But that's confusing :s And import { Foo } from "bar.js" works just as well in all the implementations we've seen so far.

I'm not sure what we should recommend.

Updated with keeping Namespace and dropping Default from the release notes. It should be the least confusing, and is expected to work in all known cases.

sjrd · 2016-10-14T14:46:34Z

Added documentation about modules. From my point of view, this is now complete.

gzm0 · 2016-10-15T13:01:10Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+Emitting CommonJS modules is also not compatible with `persistLauncher := true`, as a different launcher needs to be emitted for fastOpt versus fullOpt.
+
+More importantly, the CommonJS module support is completely incompatible with the `jsDependencies` mechanism.
+If you emit CommonJS modules, you have to manage your JavaScript dependencies on your own (possibly through `npm`).


I would put this in the "importing" section. I do not expect that exporting as a CommonJS module and running in Node.js with jsDependencies will work any worse than before. But importing will definitely not work at all with jsDependencies.

gzm0 · 2016-10-15T13:02:33Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+import js.annotation._
+
+@js.native
+@JSImport("bar.js", "Foo") // JS: import Foo from "bar.js"


Consider adding the JS comment for both ES5 and ES6:

// ES6: import Foo from "bar.js" // ES5: var Foo = require("bar.js").Foo

gzm0 · 2016-10-15T13:03:21Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+
+{% highlight scala %}
+@js.native
+@JSImport("bar.js", JSImport.Namespace) // JS: import * as bar from "bar.js"


Same here:

// ES5: var bar = require("bar.js") // ES6: import * as bar from "bar.js"

Especially here, most readers can probably much more relate to var x = require("x.js"); than the ES2015 equivalent.

gzm0 · 2016-10-15T13:15:24Z

doc/interoperability/facade-types.md

+
+val y = Bar.exportedFunction(5)
+{% endhighlight %}
+


You should document how these map to CommonJS constructs. The only place this is currently documented is inside the compiler.
The choice between default and namespace is particularly involved. It essentially requires the developer to guess, how the module is going to export its members in an ES2015 module:

If the whole module is moving to the default export, use JSImport.Default. This makes sense for modules exporting a single class. For example:

var JSZip = require("jszip.js"); var zip = new JSZip();

If the individual members will be exported, use JSImport.Namespace. For example:

var _ = require("underscore.js"); _.each(...);

It is important to understand that this is only a guess (if there is no ES2015 version of the module yet) or must be based on how this particular module exports itself to CommonJS vs ES2015.

This becomes of course only relevant, once we actually support emitting ES2015 modules. However, it is important in the documentation now, to understand the difference between JSImport.Default and JSImport.Namespace, because there is no difference between them for most CommonJS modules.

OK I'll try to make all this clearer.

sjrd

I'll address the comments tonight when I'm back home.

sjrd · 2016-10-16T10:59:54Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+Emitting CommonJS modules is also not compatible with `persistLauncher := true`, as a different launcher needs to be emitted for fastOpt versus fullOpt.
+
+More importantly, the CommonJS module support is completely incompatible with the `jsDependencies` mechanism.
+If you emit CommonJS modules, you have to manage your JavaScript dependencies on your own (possibly through `npm`).


sjrd · 2016-10-16T11:00:54Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+import js.annotation._
+
+@js.native
+@JSImport("bar.js", "Foo") // JS: import Foo from "bar.js"


sjrd · 2016-10-16T11:01:03Z

_posts/news/2016-10-17-announcing-scalajs-0.6.13.md

+
+{% highlight scala %}
+@js.native
+@JSImport("bar.js", JSImport.Namespace) // JS: import * as bar from "bar.js"


sjrd · 2016-10-16T11:03:35Z

doc/interoperability/facade-types.md

+
+val y = Bar.exportedFunction(5)
+{% endhighlight %}
+


OK I'll try to make all this clearer.

Also make relevant changes to the documentation.

sjrd · 2016-10-16T23:22:46Z

Updated.

sjrd force-pushed the scalajs-0.6.13 branch from 0109103 to 26fd230 Compare October 13, 2016 14:56

gzm0 requested changes Oct 13, 2016

View reviewed changes

sjrd force-pushed the scalajs-0.6.13 branch 3 times, most recently from 03339b5 to 9546d2a Compare October 14, 2016 14:45

sjrd force-pushed the scalajs-0.6.13 branch from 9546d2a to 571024a Compare October 14, 2016 15:14

gzm0 requested changes Oct 15, 2016

View reviewed changes

sjrd commented Oct 16, 2016

View reviewed changes

Announcing Scala.js 0.6.13.

99168bb

Also make relevant changes to the documentation.

sjrd force-pushed the scalajs-0.6.13 branch from 571024a to 99168bb Compare October 16, 2016 23:22

gzm0 approved these changes Oct 17, 2016

View reviewed changes

sjrd merged commit 9761489 into scala-js:master Oct 17, 2016

sjrd deleted the scalajs-0.6.13 branch October 17, 2016 08:44


		We are excited to announce the release of Scala.js 0.6.13!

		This release one particularly anticipated feature: the ability to generate CommonJS modules with Scala.js!


		Emitting CommonJS modules is also not compatible with `persistLauncher := true`, as a different launcher needs to be emitted for fastOpt versus fullOpt.

		### Importing stuff from other CommonJS modules

Announcing Scala.js 0.6.13. #314

Announcing Scala.js 0.6.13. #314

Uh oh!

Conversation

sjrd commented Oct 13, 2016

sjrd commented Oct 13, 2016

sjrd commented Oct 13, 2016

gzm0 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sjrd commented Oct 14, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sjrd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sjrd commented Oct 16, 2016

Labels

2 participants