CONTRIBUTING.md: Add tip for AnyBar integration (Automattic#12017)

* CONTRIBUTING.md: Add tip for AnyBar integration

* Docs: Add development-workflow.md

* Docs: Add server/tests monitoring tips

* Docs: Remove mention of hot reloading; fix typos

It hasn't been living up to its name in a while; might as well not
oversell it.

* Add some more testing details

We shouldn’t ask users to click one more time just to find out how to
run some basic tests.

* Explain what does the workflow document contain

Otherwise users may not know whether to click on the link at all.

.github/CONTRIBUTING.md

@@ -30,43 +30,9 @@ For more detailed instructions, see [Installing Calypso](../docs/install.md).
 
 ## Development Workflow
 
-### Build
+Running `make run` will build all the code and continuously watch the front-end JS and CSS/Sass for changes and rebuild accordingly.
 
-Running `make run` will build all the code and continuously watch the front-end JS and CSS/Sass for changes and rebuild accordingly. In the case of React components, after the rebuild, the code is reloaded live in the browser and you should be able to see the changes without a refresh (CSS and changes deeper in the logic still need a refresh, but this will change, soon).
-
-### Tests
-
-The [test/README.md](../test/README.md) file documents how to create new tests, and how to run all or just some tests from the test suite.
-
-### Errors and Warnings
-
-Errors and warning appear in the normal places – the terminal where you ran `make run` and the JavaScript console in the browser. If something isn’t going the way you expected it, look at those places first.
-
-### Debugging
-
-Calypso uses the [debug](https://github.com/visionmedia/debug) module to handle debug messaging. To turn on debug mode for all modules, type the following in the browser console:
-
-```js
-localStorage.setItem( 'debug', '*' );
-```
-
-You can also limit the debugging to a particular scope
-
-```js
-localStorage.setItem( 'debug', 'calypso:*' );
-```
-
-The `node` server uses the `DEBUG` environment variable instead of `localStorage`. `make run` will pass along it’s environment, so you can turn on all debug messages with
-
-```bash
-DEBUG=* make run
-```
-
-or limit it as before with
-
-```bash
-DEBUG=calypso:* make run
-```
+See [Development Workflow](../docs/development-workflow.md) for details on how to run tests, control what debug messages to receive, and where to look for errors and warnings.
 
 ## Pull Requests
 

client/devdocs/style.scss

@@ -126,6 +126,11 @@
  color: $invert;
  }
  }
+
+ video {
+ max-width: 100%;
+ margin-bottom: 1em;
+ }
 }
 
 .devdocs__doc-header {

docs/development-workflow.md

@@ -0,0 +1,77 @@
+Development Workflow
+====================
+
+## Build
+
+Running `make run` will build all the code and continuously watch the front-end JS and CSS/Sass for changes and rebuild accordingly.
+
+## Tests
+
+If you want to run the tests for a specific library in `client/` use:
+
+```bash
+> npm run test-client client/<subdirectory>/test
+```
+
+or for running all tests (client, server, test), use:
+
+```bash
+> npm test
+```
+
+The [test/README.md](../test/README.md) file documents how to create new tests, how to watch for file changes, and how to run all or just some tests from the test suite.
+
+## Errors and Warnings
+
+Errors and warning appear in the normal places – the terminal where you ran `make run` and the JavaScript console in the browser. If something isn’t going the way you expected it, look at those places first.
+
+## Debugging
+
+Calypso uses the [debug](https://github.com/visionmedia/debug) module to handle debug messaging. To turn on debug mode for all modules, type the following in the browser console:
+
+```js
+localStorage.setItem( 'debug', '*' );
+```
+
+You can also limit the debugging to a particular scope:
+
+```js
+localStorage.setItem( 'debug', 'calypso:*' );
+```
+
+The `node` server uses the `DEBUG` environment variable instead of `localStorage`. `make run` will pass along its environment, so you can turn on all debug messages with:
+
+```bash
+DEBUG=* make run
+```
+
+or limit it as before with:
+
+```bash
+DEBUG=calypso:* make run
+```
+
+## Monitoring builds and tests
+
+Throughout your Calypso development workflow, you will find yourself waiting — either for a build to finish or for tests to run. Rather than standing idle looking at terminals while you wait, you can use status indicators and/or system notifications.
+
+One such tool is [AnyBar](https://github.com/tonsky/AnyBar) (_macOS only_), a very barebones menubar indicator. Here's a brief screencast of AnyBar reporting builds and tests for Calypso:
+
+<video src="https://cldup.com/LOqXUo351n.mp4" controls>
+<a href="https://cldup.com/LOqXUo351n.mp4">(video)</a>
+</video>
+
+### Set-up
+
+- Install [AnyBar](https://github.com/tonsky/AnyBar): `brew cask install anybar`
+- Run it at the default port: `open -a AnyBar`
+- Obtain this [handler shell script](https://gist.github.com/mcsf/56911ae03c6d87ec61429cefc7707cb7/)
+- Optionally, place the script somewhere memorable and make it executable: `chmod +x ~/bin/anybar-calypso`
+- From now on, pipe your Calypso commands through it:
+ * `make run | anybar-calypso`
+ * `npm run test-client:watch client/my-component | anybar-calypso`
+- Feel free to tweak the script and share improvements with the Calypso project
+
+### Other platforms
+
+`anybar-calypso` communicates with AnyBar by sending simple strings via UDP to a local port. This means that it can trivially be adapted to work with any other notification system, either by listening to UDP traffic or by altering `anybar-calypso` directly.

docs/install.md

@@ -30,10 +30,12 @@ $ cd wp-calypso
 $ make run
 ```
 
-The `make run` command will install any `npm` dependencies and start the development server. When changes are made to either the JavaScript files or the Sass stylesheets, the build process will run automatically. In some cases it will even automatically reload the code in the browser (for React components code). The build process compiles both the JavaScript and CSS to make sure that you have the latest versions of both.
+The `make run` command will install any `npm` dependencies and start the development server. When changes are made to either the JavaScript files or the Sass stylesheets, the build process will run automatically. The build process compiles both the JavaScript and CSS to make sure that you have the latest versions of both.
 
 To run Calypso locally, you'll need to add `127.0.0.1 calypso.localhost` to [your hosts file](http://www.howtogeek.com/howto/27350/beginner-geek-how-to-edit-your-hosts-file/), and load the app at [http://calypso.localhost:3000](http://calypso.localhost:3000) instead of just `localhost`. This is necessary, because when running locally Calypso is using the remote version of the WordPress.com REST API, which allows only certain origins via our current authentication methods.
 
+See [Development Workflow](../docs/development-workflow.md) for more.
+
 ## Using a portable development environment
 
 You can install Calypso very quickly via a portable development environment called [Calypso Bootstrap](https://github.com/Automattic/wp-calypso-bootstrap). It uses Vagrant and Puppet behind the scenes to install and configure a virtual machine with Calypso ready to run - with a single command.