documented upcoming changes

web/news.txt

@@ -3,27 +3,86 @@ News
 ====
 
 ..
-  2015-11-XX Version 0.12.2 released
+  2016-01-XX Version 0.13.0 released
   ==================================
 
-  This is a bugfix release.
+  This release implements no new features. Instead existing features have
-
+  been fleshed out as we're heading to version 1.
 
   Changes affecting backwards compatibility
   -----------------------------------------
 
   - ``macros.newLit`` for ``bool`` now produces false/true symbols which
     actually work with the bool datatype.
-  - when compiling to JS, ``Node``, ``NodeType`` and ``Document`` are no longer
+  - When compiling to JS, ``Node``, ``NodeType`` and ``Document`` are no longer
     defined. Use the types defined in ``dom.nim`` instead.
   - The check ``x is iterator`` (used for instance in concepts) was always a
     weird special case (you could not use ``x is proc``) and was removed from
     the language.
-  - Implicit return type for iterators have been removed from the language.
   - Top level routines cannot have the calling convention ``closure``
     anymore.
 
 
+  Syntax changes
+  ~~~~~~~~~~~~~~
+
+  The parser now considers leading whitespace in front of operators
+  to determine if an operator is used in prefix or infix position.
+  This means that finally ``echo $foo`` is parsed as people expect
+  which is as ``echo($foo)``. It used to be parsed as ``(echo) $ (foo)``.
+
+  ``echo $ foo`` continues to be parsed as ``(echo) $ (foo)``.
+
+
+  Iterator changes
+  ~~~~~~~~~~~~~~~~
+
+  Implicit return type inference for iterators has been removed from the language. The following used to work:
+
+  .. code-block:: nim
+    iterator it =
+      yield 7
+
+  This was a strange special case and has been removed. Now you need to write it like so which is consistent with procs:
+
+  .. code-block:: nim
+    iterator it: auto =
+      yield 7
+
+
+  Closure changes
+  ~~~~~~~~~~~~~~~
+
+  The semantics of closures changed: Capturing variables that are in loops do not produce a new environment. Nim closures behave like JavaScript closures now.
+
+  The following used to work as the environment creation used to be attached to the loop body:
+
+  .. code-block:: nim
+
+    proc outer =
+      var s: seq[proc(): int {.closure.}] = @[]
+      for i in 0 ..< 30:
+        let ii = i
+        s.add(proc(): string = return ii*ii))
+
+  This behaviour has changed in 0.13.0 and now needs to be written as:
+  .. code-block:: nim
+
+    proc outer =
+      var s: seq[proc(): int {.closure.}] = @[]
+      for i in 0 ..< 30:
+        (proc () =
+          let ii = i
+          s.add(proc(): int = return ii*ii))()
+
+  The reason is that environment creations are now only performed once
+  per proc call. This change is subtle and unfortunate, but:
+
+  1. Affects almost no code out there.
+  2. Is easier to implement and we are at a point in Nim's development process where simple+stable wins over perfect-in-theory+unstable-in-practice.
+  3. Implies programmers are more in control of where memory is allocated which is benefitical for a systems programming language.
+
+
 2015-10-27 Version 0.12.0 released
 ==================================