Address feedback

Author: olafurpg

blog/_posts/2017-02-23-scalafix-v0.3.md renamed to blog/_posts/2017-02-25-scalafix-v0.3.md

@@ -6,36 +6,42 @@ title: "Refactor with scalafix v0.3"
 ---
 
 I am happy to announce the release of [scalafix v0.3][scalafix].
-This release leverages the new scala.meta semantic API to provide a re-designed `Rewrite` and `Patch` API for refactorings.
+This release uses the new scala.meta semantic API to provide a re-designed `Rewrite` and `Patch` API for refactorings.
 Let me explain what that means word by word.
 
-## scala.meta semantic API
+> Note. This is the second post on scalafix and scala.meta. You might be
+> interested in reading the first post
+> [here](http://scala-lang.org/blog/2016/10/24/scalafix.html).
+
+## Scala.meta semantic API
 
 Scala.meta recently announced the [first release of its semantic API][meta-1.6].
 This release is the product of close collaboration for the past several months between
-[@xeno-by](https://twitter.com/xeno_by) at Twitter and myself at the Scala Center.
-The semantic API provides operations to query information from the compiler.
+[@xeno_by][] at Twitter and [myself][@olafurpg] at the Scala Center.
+The objective of the semantic API is to provide operations to query information from the compiler.
 
-The first version of the scala.meta semantic API makes it possible to query for the "symbol" of a name that appears in a Scala source file.
-A symbol is a unique identifier of a definition such as a class, val, def or trait.
-For example, the symbol of `println` from the standard library is `_root_.scala.Predef.println(Ljava/lang/Object;)V`.
+The first version of the scala.meta semantic API makes it possible to query for the resolved "symbol" of a name that appears in a Scala source file.
+A name is a reference to some definition, for example `println` or `scala.Predef.println`.
+A symbol is a unique identifier of a single definition.
+For example, `println` from the standard library has the symbol `_root_.scala.Predef.println(Ljava/lang/Object;)V.`.
+The compiler is responsible for resolving names to symbols.
 
-Symbols are created by "scalahost", a compiler plugin.
-Scalahost emits symbols of a source file in the form of a "semantic database".
+Scalahost is a compiler plugin in the scala.meta project that extracts symbols from the compiler and maps them to scala.meta syntax trees.
+Scalahost emits the extracted symbols into a "semantic database".
 The semantic database can be persisted to files on disk and loaded for later analysis.
 Semantic databases from different compilation units, potentially produced by different
 versions of the Scala compiler, can be merged.
 This opens possibilities for large-scale code analysis.
 
 The introduction of the scala.meta semantic API is a game changer for scalafix.
-The ability to query for symbols open possibilities for many scalafix rewrites.
+The ability to resolve names to symbols opens possibilities for many scalafix rewrites.
 
 ## Rewrite: meta.Tree => Seq[Patch]
 
 A scalafix `Patch` is a small operation that can produce a diff on a Scala source file.
 A patch can either be a "token patch" or a "tree patch".
 
-Token patches are low-level but give full control of how small details are handled in a source files, for example formatting and comments 
+Token patches are low-level but give full control over how every detail in a source file is handled, for example formatting and comments.
 Example token patches are `Remove(token)` and `AddLeft(token, toAdd: String)`, which removes or prepends a string to `token`, respectively.
 
 Tree patches are high-level and allow rewrite author to declaratively explain what operation to perform.
@@ -46,8 +52,8 @@ Tree and token patches build a small algebra of operations that can be composed
 A challenge with composing patches is to figure out what to do on conflicts.
 For example, what happens when one patch renames a token while the other patch removes the same token?
 The current strategy in scalafix is to try and resolve as many conflicts as possible on the tree patch level.
-Once we we only have token patches, it is harder to resolve conflicts.
-Unsolvable conflicts on the token level abort the refactoring.
+It can be harder to resolve conflicts on the token level since the original intent of the patch is lost.
+Unsolvable conflicts abort the refactoring.
 In the future, we hope to support more advanced conflict resolution strategies.
 
 In a nutshell, a scalafix `Rewrite` is a `scala.meta.Tree => Seq[Patch]` function.
@@ -56,9 +62,9 @@ To demonstrate how rewrites are implemented with scalafix v0.3, let's step throu
 
 ## Example: Xor to Either
 
-The functional programming library [cats][cats] migrated recently from its `Xor` data type to `Either` from the standard library.
+The functional programming library [cats][] migrated recently from its `Xor` data type to `Either` from the standard library.
 It requires a few mechanical steps to migrate code to use `Either` instead of `Xor`.
-For example, below is a diff that's taken from [circe][xor-circe]'s migration to `Either`.
+For example, below is a diff that's taken from [circe][]'s migration to `Either`.
 
 ```diff
 -final def either: Xor[HCursor, HCursor] = if (succeeded) Xor.right(any) else Xor.left(any)
@@ -108,30 +114,37 @@ The recommended way to use scalafix as tool is the [`sbt-scalafix`][sbt-scalafix
 It's possible define custom tree patches in the [`.scalafix.conf` configuration file][config-patches].
 
 The long-term mission of scalafix is to help automate the migration of deprecated Scala 2.x features to Dotty.
-However, as I have hopefully demonstrated in this post, scalafix can be used for more than just migrating between Scala versions.
+However, as I have demonstrated in this post, scalafix can be used for more than just migrating between Scala versions.
 Scalafix can also be used for ad-hoc library and application migrations.
 
 I am excited to see what applications the community can build with scala.meta and scalafix.
 Some promising ideas that have floated around include
 
-- parse and run rewrites from `@deprecated` warning messages. This would enable library authors
-  to provide exectuable migration guides.
-- use scalafix to cross-build against multiple similar APIs. For example, a
-  library author could write against scalaz and rewrite to cats.
+- parse and run rewrites from `@deprecated` warning messages. This would enable
+  library authors to provide executable migration guides.
+- shim/cross-build libraries with similar APIs. For example,
+  a library could be developed with the scalaz API, and use scalafix to
+  code-generate a version of the library that uses cats instead.
 - build a code search web-interface with "jump to definition" functionality
   powered by the scala.meta's semantic database.
-- replace usage of the infamous `any2StringAdd` in favor of string interpolators or explicit `.toString`.
-- replace usages of `scala.Seq`, which can be mutable, in favor of `scala.collection.immutable.Seq`.
+- replace usage of `scala.Seq`, which can be mutable, in favor of `scala.collection.immutable.Seq`.
 
 If this sounds exciting to you, join us!
 I am happy to answer any question in the [scalafix gitter][gitter] channel.
 
+PS. I want to thank [@ShaneDelmore][] who has provided invaluable feedback from
+the early days of scalafix development and come up with several brilliant ideas
+for scalafix use-cases.
+
+
+[@ShaneDelmore]: https://twitter.com/ShaneDelmore
+[@olafurpg]: https://twitter.com/olafurpg
+[@xeno_by]: https://twitter.com/xeno_by
 [xor2either-test]: https://github.com/scalacenter/scalafix/blob/f61136fad79afcdbb03528ce78c7928afc6eafd6/scalafix-nsc/src/test/resources/syntactic/Xor2Either.source
 [xor2either]: https://github.com/scalacenter/scalafix/blob/f61136fad79afcdbb03528ce78c7928afc6eafd6/core/src/main/scala/scalafix/rewrite/Xor2Either.scala
-[xor-circe]: https://github.com/circe/circe/pull/343/files
+[circe]: https://github.com/circe/circe/pull/343/files
 [cats]: http://github.com/typelevel/cats
 [ghpages]: http://github.com/scalacenter/scalafix
-[prevpost]: http://scala-lang.org/blog/2016/10/24/scalafix.html
 [scalafix]: https://scalacenter.github.io/scalafix/#0.3.0
 [sbt-scalafix]: https://scalacenter.github.io/scalafix/#sbt-scalafix
 [sbt-scalahost]: https://scalacenter.github.io/scalafix/#sbt-scalahost