CoffeeScript 2 announcement #4695

GeoffreyBooth · 2017-09-10T07:11:52Z

See https://github.com/GeoffreyBooth/coffeescript/blob/announcing-2/documentation/sections/announcing_coffeescript_2.md

Feedback very much welcome. This feels too long, yet I also feel like I’m missing topics that should be covered. There are also no code samples in this, though I’m not sure where I’d add any (especially not if I want to avoid this getting really really long).

For the final product I’ll find a way to output this like the current docs page, and save it into /docs/v2/announcing-coffeescript-2/index.html so that it appears at http://coffeescript.org/announcing-coffeescript-2/ once we launch 2.0.0 and make the 2 docs the primary docs.

@jashkenas @lydell @connec

lydell

This looks really, really good! I left some comments for potential changes.

lydell · 2017-09-10T15:55:20Z

documentation/sections/announcing_coffeescript_2.md

+
+From the beginning, CoffeeScript has been described as being “just JavaScript.” And today, JavaScript is ES2015 (well, ES2017). CoffeeScript welcomes the changes in the ES world and we’re happy to stop outputting ES3  syntax for modern CoffeeScript and ES2015+ features.
+
+(Quick history lesson: ECMAScript is the official name of JavaScript, after the ECMA standards body that defines it. ECMAScript version 3, or ES3, was released in 1999 and is the lowest common denominator version of JavaScript that anyone today considers supporting. There was no ES4, and ES5 came out in 2009. What would’ve been ES6 was eventually released as ES2015, a change in naming meant to indicate that future versions would be released every year. When we write “ES2015+”, we mean ES2015, ES2016, ES2017 and future successors.)


While I like this section, if you’re looking to shorten the post, I guess this paragraph is a good place to do it.

lydell · 2017-09-10T15:56:43Z

documentation/sections/announcing_coffeescript_2.md

+
+Many ES2015 features, such as `=>`, were adopted directly from CoffeeScript and are one-to-one compatible, or very nearly so. This has made outputting many of CoffeeScript’s innovations into ES2015 syntax straightforward: not only does `=>` become `=>`, but `{ a } = obj` becomes `{ a } = obj`, `"a#{b}c"` becomes `` `a${b}c` `` and so on.
+
+The following CoffeeScript features were updated in 2 to output using ES2015+ syntax (or added in 1.11–2, output using modern syntax):


Is it better to consistently refer to the new version as “CoffeeScript 2,” and not just a bare “2” like here?

1.11–2 → 1.11–1.12

lydell · 2017-09-10T16:07:23Z

documentation/sections/announcing_coffeescript_2.md

+- Object rest/spread properties
+- Interpolated strings/template literals (ES2015 backticked strings)
+- Tagged template literals
+- ES2015’s `for…of` is now available as CoffeeScript’s `for…from` (we already had a `for…of`)


Idea: Will it be easier for folks who aren’t super familiar with the names of every JS feature if we add a “code example” to each bullet point?

- Modules (`import`/`export`) - Classes (`class Animal`) - Async functions (`async`/`await`) - Bound/arrow functions (`=>`) - Function default parameters (`(delay = 0) ->`) - Function splat/rest parameters (`(items...) ->`) - Destructuring, for both arrays and objects (`[first, second] = items`/`{length} = items`) - Object rest/spread properties (`{options..., force: true}`/`{force, otherOptions...} = options`) - Interpolated strings/template literals (ES2015 backticked strings) (`"Hello, #{user}!"`) - Tagged template literals (`html"<strong>coffee</strong>"`) - ES2015’s `for…of` is now available as CoffeeScript’s `for…from` (we already had a `for…of`)

lydell · 2017-09-10T16:10:41Z

documentation/sections/announcing_coffeescript_2.md

+- Tagged template literals
+- ES2015’s `for…of` is now available as CoffeeScript’s `for…from` (we already had a `for…of`)
+
+Not all CoffeeScript features were adopted as is; most notably, [default values](http://coffeescript.org/v2/#breaking-changes-default-values) in ES2015 and CoffeeScript 2 are only applied when a variable is `undefined`, not `undefined` or `null` as in CoffeeScript 1; and [classes](http://coffeescript.org/v2/#breaking-changes-classes) have their own differences. See the [breaking changes](http://coffeescript.org/v2/#breaking-changes) for the fine details.


I found it a bit confusing who was adopting what here at first. Doing something like the following might help:

Not all CoffeeScript features were adopted as is → Not all CoffeeScript features were adopted by ES2015 100% the same way

default values in ES2015 and CoffeeScript 2 → default values in ES2015 (and also CoffeeScript 2)

lydell · 2017-09-10T16:11:52Z

documentation/sections/announcing_coffeescript_2.md

+- In CoffeeScript 2, “bare” `super` (calling `super` without arguments) is now no longer allowed, and one must use `super()` or `super arguments...` instead.
+- References to `this`/`@` cannot occur before a call to `super`, per the ES spec.
+
+See the [full details](http://coffeescript.org/v2/#breaking-changes-super-extends). Either the CoffeeScript compiler or Babel will throw errors for either of these cases, so updating your code is a simple matter of fixing each instance as the compiler errors on it, until your code compiles successfully.


Perhaps remove the word “simple” in this paragraph?

lydell · 2017-09-10T16:12:40Z

documentation/sections/announcing_coffeescript_2.md

+
+There are many smaller improvements as well, such as to the `coffee` command-line tool. You can read all the details in the [changelog](http://coffeescript.org/v2/#changelog) for the 2.0.0 betas.
+
+## What About…


Perhaps “What About …?”

lydell · 2017-09-10T16:13:41Z

documentation/sections/announcing_coffeescript_2.md

+
+But Babel exists now, and it does its one job—converting today’s and tomorrow’s JavaScript into yesterday’s—exceedingly well. With Babel around, there’s no need for the CoffeeScript compiler to duplicate its functionality. All the CoffeeScript compiler needs to worry about now is converting the CoffeeScript version of new syntax into the ES version of that syntax, e.g. `import fs from 'fs'` into `import fs from 'fs'`. The CoffeeScript compiler need not do all the work that Babel does. This makes adding support for new ES features much easier than before.
+
+Fortunately, most features added by ECMA in recent years haven’t required any updates at all in CoffeeScript. New global objects, or methods on global objects, are just supported and output as is. Want to use `Object.assign` in CoffeeScript? Just type `Object.assign`. Ditto for `Array.forEach` and `Array.map` and `String.includes` and any number of excellent additions to the language that ECMA has added. You may need to add [polyfills](https://babeljs.io/docs/usage/polyfill/) for these methods if your target runtime(s) don’t support them, but that would be no different than if you used these methods in a plain JavaScript project.


This section about polyfills is also a candidate for shortening or removal if you want to make the whole thing shorter.

GeoffreyBooth · 2017-09-10T17:04:16Z

I guess the question is, who is the audience for this article? I feel like it should probably be written for the developer who may have heard of ES6, but isn't clear that it's the same as ES2015; as in, people who don't follow these topics closely.

Does it feel too long, or should I not worry about length?

lydell · 2017-09-10T17:26:39Z

I don’t think it’s too long.

boris-petrov · 2017-09-10T21:08:52Z

It's a 10-minute read for slow readers. It's perfect, no need to touch it. :)

jashkenas · 2017-09-13T19:27:32Z

My thoughts:

"clean, elegant" is a little horn-tooting. How about just "clean".

All of the "ES2015+" and "ES2017" monikers, and the ECMA history lesson is confusing, and a little beside the point. Let's just call it "modern JavaScript", or "modern JS", and later just "JS", and axe the "Quick History Lesson".

=> was not adopted directly from CoffeeScript. It was in other languages earlier, and ES4 had it on the roadmap before CoffeeScript existed.

"but simply put: let and const and named functions aren’t necessary for compatibility or interoperability with other libraries, and supporting them would add unwanted complexity to CoffeeScript"

It's not so much about "unwanted complexity", just that they don't fit in to CoffeeScript. We purposefully leave them out.

The Future Compatibility section feels a little overly Babel-specific. Don't Traceur and Bublé work too? And whatever transpiler becomes popular next year? Seems like this section could be shrunk a bit to just state our Stage 4 syntax support policy and mention the transpilers you can use for broader compatibility.

Finally, it would be nice to sneak in a small mention that CoffeeScript 1.X still does and will continue to exist. If you want to target lowest-common-denominator JS, which still exists under rocks and in dark corners (Illustrator, remote countries, embedded systems, grandparents), you still can.

GeoffreyBooth · 2017-09-13T21:09:15Z

Agree with most of the above.

Finally, it would be nice to sneak in a small mention that CoffeeScript 1.X still does and will continue to exist. If you want to target lowest-common-denominator JS, which still exists under rocks and in dark corners (Illustrator, remote countries, embedded systems, grandparents), you still can.

I would argue that if you want lowest-common-denominator JS, you should still use CS2 and just transpile your output. I don’t see any benefit to CS1 over CS2-plus-Babel, other than that compilation is faster. Though with CS1 and no transpilation, you need to be careful not to use modules or tagged template literals or generators, the “modern JS” features we added to CS1 without conversion down to ES3/ES5 compatibility. That’s quite a caveat to make sure to remember, though, so the docs should probably be conservative and recommend transpilation (i.e. a post-CoffeeScript compiler Babel step, or #4697) even for CS1, in which case CS1 offers nothing over CS2.

jashkenas · 2017-09-13T21:46:08Z

Fair enough!

GeoffreyBooth · 2017-09-14T05:40:20Z

@jashkenas I tried to revise per your notes. Not sure I got it quite right regarding let/const; maybe I’m better off just not giving a reason here and letting the docs speak for us, assuming you don’t have any notes to that section of the docs (?).

I hadn’t heard of Bublé, it looks cool. Traceur Compiler hasn’t been updated in a year, so I’m not sure how bright its future is, though it is supported by Google. One thing that I found interesting is that all three transpilers support JSX. This reinforces my feeling that we were right to add support for JSX into CoffeeScript.

jashkenas · 2017-09-14T13:58:48Z

Re: var/let/const — probably better to omit the reason from this page ... because this version ain't quite right either.

While it's the case that everything in CoffeeScript is an expression, and we don't declare variables — that's not really the reason why we don't support var/let/const. We could have added different assignment operators for each, or allowed the standard prefix modifiers and just shifted them up to the declaration line at the top of the block.

GeoffreyBooth · 2017-09-15T05:50:51Z

Okay, hopefully this should be it. Any last notes?

If this text is good I’ll convert this into an HTML file like our docs. I’ll just do it once semi-manually, I don’t think I want to create a new cake task for this that won’t ever get used again.

# Conflicts: # documentation/sections/es2015plus_output.md

GeoffreyBooth · 2017-09-16T05:37:16Z

Take a look: http://rawgit.com/GeoffreyBooth/coffeescript/announcing-2/docs/v2/announcing-coffeescript-2/

What do you all think?

lydell

Beautiful!

lydell · 2017-09-16T10:01:47Z

documentation/sections/announcing_coffeescript_2.md

+
+Back when CoffeeScript 1 was created, ES2015 JavaScript and transpilers like [Babel](http://babeljs.io/), [Bublé](https://buble.surge.sh/) or [Traceur Compiler](https://github.com/google/traceur-compiler) were several years away. The CoffeeScript compiler itself had to do what today’s transpilers do, converting modern features like destructuring and arrow functions into equivalent lowest-common-denominator JavaScript.
+
+But transpilers exist now, and they do their job well. With them around, there’s no need for the CoffeeScript compiler to duplicate this functionality. All the CoffeeScript compiler needs to worry about now is converting the CoffeeScript version of new syntax into the JS version of that syntax, e.g. `import fs from 'fs'` into `import fs from 'fs'`. This makes adding support for new JavaScript features much easier than before.


Is this a better example?

e.g. "Hello #{name}!" into `Hello ${name}!`

I find the import fs from 'fs' example a little bit confusing since the CoffeeScript syntax is identical to the JavaScript syntax.

Yes, good call.

…ncing-2 # Conflicts: # docs/v2/index.html # documentation/sections/coffeescript_2.md

CoffeeScript 2 announcement, first draft

c01f8c5

lydell reviewed Sep 10, 2017

View reviewed changes

Lydell's notes

da68ab6

Jeremy’s notes; Rollup is not a transpiler

2e76305

GeoffreyBooth force-pushed the announcing-2 branch from 7ee83a8 to 2e76305 Compare September 14, 2017 05:34

Revise “unsupported features” section

fcdac8c

GeoffreyBooth mentioned this pull request Sep 15, 2017

Option to transpile with Babel #4697

Merged

GeoffreyBooth added 4 commits September 15, 2017 21:52

Merge branch 'master' into announcing-2

11b227a

# Conflicts: # documentation/sections/es2015plus_output.md

Fix links, invalid HTML

43d656a

Announcing CoffeeScript 2 HTML page

014e02b

Link to the announcement

f2b3cee

GeoffreyBooth changed the title ~~[WIP] CoffeeScript 2 announcement~~ CoffeeScript 2 announcement Sep 16, 2017

GeoffreyBooth added 2 commits September 15, 2017 22:40

Add some references

bbb4383

Fix anchors

f98da38

lydell reviewed Sep 16, 2017

View reviewed changes

GeoffreyBooth added 2 commits September 16, 2017 11:47

Better example

68da3f6

Merge branch 'master' of github.com:jashkenas/coffeescript into annou…

263334e

…ncing-2 # Conflicts: # docs/v2/index.html # documentation/sections/coffeescript_2.md

GeoffreyBooth merged commit 4c41831 into jashkenas:master Sep 16, 2017

GeoffreyBooth deleted the announcing-2 branch September 16, 2017 18:57


		From the beginning, CoffeeScript has been described as being “just JavaScript.” And today, JavaScript is ES2015 (well, ES2017). CoffeeScript welcomes the changes in the ES world and we’re happy to stop outputting ES3 syntax for modern CoffeeScript and ES2015+ features.

		(Quick history lesson: ECMAScript is the official name of JavaScript, after the ECMA standards body that defines it. ECMAScript version 3, or ES3, was released in 1999 and is the lowest common denominator version of JavaScript that anyone today considers supporting. There was no ES4, and ES5 came out in 2009. What would’ve been ES6 was eventually released as ES2015, a change in naming meant to indicate that future versions would be released every year. When we write “ES2015+”, we mean ES2015, ES2016, ES2017 and future successors.)


		Many ES2015 features, such as `=>`, were adopted directly from CoffeeScript and are one-to-one compatible, or very nearly so. This has made outputting many of CoffeeScript’s innovations into ES2015 syntax straightforward: not only does `=>` become `=>`, but `{ a } = obj` becomes `{ a } = obj`, `"a#{b}c"` becomes `` `a${b}c` `` and so on.

		The following CoffeeScript features were updated in 2 to output using ES2015+ syntax (or added in 1.11–2, output using modern syntax):


		There are many smaller improvements as well, such as to the `coffee` command-line tool. You can read all the details in the [changelog](http://coffeescript.org/v2/#changelog) for the 2.0.0 betas.

		## What About…


		But Babel exists now, and it does its one job—converting today’s and tomorrow’s JavaScript into yesterday’s—exceedingly well. With Babel around, there’s no need for the CoffeeScript compiler to duplicate its functionality. All the CoffeeScript compiler needs to worry about now is converting the CoffeeScript version of new syntax into the ES version of that syntax, e.g. `import fs from 'fs'` into `import fs from 'fs'`. The CoffeeScript compiler need not do all the work that Babel does. This makes adding support for new ES features much easier than before.

		Fortunately, most features added by ECMA in recent years haven’t required any updates at all in CoffeeScript. New global objects, or methods on global objects, are just supported and output as is. Want to use `Object.assign` in CoffeeScript? Just type `Object.assign`. Ditto for `Array.forEach` and `Array.map` and `String.includes` and any number of excellent additions to the language that ECMA has added. You may need to add [polyfills](https://babeljs.io/docs/usage/polyfill/) for these methods if your target runtime(s) don’t support them, but that would be no different than if you used these methods in a plain JavaScript project.


		Back when CoffeeScript 1 was created, ES2015 JavaScript and transpilers like [Babel](http://babeljs.io/), [Bublé](https://buble.surge.sh/) or [Traceur Compiler](https://github.com/google/traceur-compiler) were several years away. The CoffeeScript compiler itself had to do what today’s transpilers do, converting modern features like destructuring and arrow functions into equivalent lowest-common-denominator JavaScript.

		But transpilers exist now, and they do their job well. With them around, there’s no need for the CoffeeScript compiler to duplicate this functionality. All the CoffeeScript compiler needs to worry about now is converting the CoffeeScript version of new syntax into the JS version of that syntax, e.g. `import fs from 'fs'` into `import fs from 'fs'`. This makes adding support for new JavaScript features much easier than before.

CoffeeScript 2 announcement #4695

CoffeeScript 2 announcement #4695

Uh oh!

Conversation

GeoffreyBooth commented Sep 10, 2017

Uh oh!

lydell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GeoffreyBooth commented Sep 10, 2017

Uh oh!

lydell commented Sep 10, 2017

Uh oh!

boris-petrov commented Sep 10, 2017

Uh oh!

jashkenas commented Sep 13, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GeoffreyBooth commented Sep 13, 2017

Uh oh!

jashkenas commented Sep 13, 2017

Uh oh!

GeoffreyBooth commented Sep 14, 2017

Uh oh!

jashkenas commented Sep 14, 2017

Uh oh!

GeoffreyBooth commented Sep 15, 2017

Uh oh!

GeoffreyBooth commented Sep 16, 2017

Uh oh!

lydell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jashkenas commented Sep 13, 2017 •

edited

Loading