Merge branch 'master' into jam/package-run-cmd

README.md

@@ -130,6 +130,8 @@ Where to go from here? There are a few places you should check out:
   - [Test dependencies](#test-dependencies)
   - [Bundle a project into a single JS file](#bundle-a-project-into-a-single-js-file)
   - [Enable source maps](#enable-source-maps)
+    - [Node](#node)
+    - [Browsers](#browsers)
   - [Skipping the "build" step](#skipping-the-build-step)
   - [Generated build info/metadata](#generated-build-infometadata)
   - [Generate documentation for my project](#generate-documentation-for-my-project)
@@ -146,6 +148,8 @@ Where to go from here? There are a few places you should check out:
   - [The lock file](#the-lock-file)
 - [FAQ](#faq)
   - [Why can't `spago` also install my npm dependencies?](#why-cant-spago-also-install-my-npm-dependencies)
+- [Differences from legacy spago](#differences-from-legacy-spago)
+  - [Watch mode](#watch-mode)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -218,6 +222,8 @@ The new package sets are instead pointing at the Registry, and can fetch compres
 
 To figure out what package set you're supposed to be using, see the section about [querying package sets](#querying-package-sets).
 
+You might also want to check out the section about [differences from legacy spago](#differences-from-legacy-spago).
+
 ### Migrate from `bower`
 
 Same as above, but with an additional `spago init` command just after you install [spago-legacy], so that the `bower.json` file is converted into a `spago.dhall` file.
@@ -1420,6 +1426,20 @@ there's enough demand).
 So this is the reason why if you or one of your dependencies need to depend on some "native"
 packages, you should run the appropriate package-manager for that (e.g. npm).
 
+## Differences from legacy spago
+
+### Watch mode
+Spago dropped support for the --watch flag in `spago build` and `spago test`. 
+
+VSCode users are recommended to use the [Purescript IDE](purescript-ide) extension for seamless experiences with automatic rebuilds.
+
+Users of other editors, e.g. vim, emacs, etc., can make use of the underlying [LSP plugin](purescript-language-server).
+
+If you want a very simple drop in replacement for `spago test --watch`, you can use a general purpose tool such as [watchexec]:
+```console
+watchexec -e purs,js,yaml -- spago test
+```
+
 [jq]: https://jqlang.github.io/jq/
 [acme]: https://hackage.haskell.org/package/acme-everything
 [pulp]: https://github.com/purescript-contrib/pulp
@@ -1441,3 +1461,6 @@ packages, you should run the appropriate package-manager for that (e.g. npm).
 [bazel-workspace]: https://bazel.build/concepts/build-ref
 [purescript-overlay]: https://github.com/thomashoneyman/purescript-overlay
 [sample-package-set]: https://github.com/purescript/registry/blob/main/package-sets/41.2.0.json
+[watchexec]: https://github.com/watchexec/watchexec#quick-start
+[purescript-langugage-server]: https://github.com/nwolverson/purescript-language-server
+[ide-purescript]: https://marketplace.visualstudio.com/items?itemName=nwolverson.ide-purescript