add section about enums

Author: bishabosha

docs/blog/_posts/2020-11-09-scala3-m1.md

@@ -9,7 +9,7 @@ November 2020 brings an important milestone for Scala 3 – the release of Scala
 
 Once 3.0.0 release candidate is out, no new features or breaking changes will take place on 3.0.x – it will only be updated for bug fixes. However, we are going to continue the work on making the language better and to test out our research in it. These changes will end up in Scala only as of 3.1.0.
 
-For now though, our teams are focusing the efforts on getting done with the remainder of the 40-something projects that we planned for the upcoming release back in July 2020. Many of them are already completed. Those that aren't yet – get revised and re-planned. With the current global uncertainty and with the scale of the project, cannot be certain, but we believe we have a reasonable chance of releasing 3.0.0-RC1 by Christmas.
+For now though, our teams are focusing the efforts on getting done with the remainder of the 40-something projects that we planned for the upcoming release back in July 2020. Many of them are already completed. Those that aren't yet – get revised and re-planned. With the current global uncertainty and with the scale of the project, we cannot be certain, but we believe we have a reasonable chance of releasing 3.0.0-RC1 by Christmas.
 
 Below, you can find a short summary of the changes that took place during between the 0.27.0-RC1 and 3.0.0-M1 releases.
 
@@ -80,6 +80,49 @@ import p.given
 
 This change was implemented by PR [#9949](https://github.com/lampepfl/dotty/pull/9949).
 
+# Final API for enumerations
+`enum` definitions are now released in their final design. since `0.27.0-RC1` we have made the following changes:
+
+For the enum definition of Option:
+```scala
+enum Opt[+T] {
+  case Sm(value: T)
+  case Nn
+}
+```
+we will now generate on the companion objects of class cases `apply` and `copy` methods with the precise subtype:
+```scala
+object Sm {
+  ...
+  def apply[T](value: T): Sm[T]
+  ...
+}
+```
+however expressions that call `apply` or `copy` will be widened to the parent enum type unless the precise type is expected, as we see here:
+```scala
+scala> Sm(23)
+val res0: Opt[Int] = Sm(23)
+
+scala> val sm: Sm[23] = Sm(23)
+val sm: Opt.Sm[23] = Sm(23)
+```
+Previously, when an enumeration declared cases with value parameters, such as `Opt.Sm`, then the `Opt.values` array would no longer have indexes that match the enum case ordinals. We feel that this is problematic, so the `values` and `valueOf` methods will only be generated when an enum has exclusively singleton cases.
+
+If an enumeration adds a case with value parameters, then consumers will recieve an error that explains why `values` has been removed.
+```scala
+scala> Opt.values
+1 |Opt.values
+  |^^^^^^^^^^
+  |value values is not a member of object Opt.
+  |Although class Opt is an enum, it has non-singleton cases,
+  |meaning a values array is not defined
+```
+For code that previously relied upon `values` to lookup singleton cases, we now provide an optimised method `fromOrdinal` that reflects singleton values. This method is always generated:
+```scala
+scala> Opt.fromOrdinal(1)
+val res1: Opt[?] = Nn
+```
+
 # Keep `@alpha` optional for operators
 Following the discussion on [contributors](https://contributors.scala-lang.org/t/the-alpha-notation/4583), we now keep `@alpha` optional for operators. The checking behavior is still available when compiling with the `-Yrequire-alpha`.