Merge "Updates to README.md and CODING.md"

CODING.md

@@ -1,9 +1,108 @@
-# VisualEditor Code Guidelines
+# Contributing to VisualEditor
+
+Thank you for helping us develop VisualEditor!
+
+This document describes how to report bugs, set up your development
+environment, run tests, and build documentation. It also provides the coding
+conventions we use in the project.
+
+## Bug reports
+
+Please report bugs to [bugzilla.wikimedia.org](https://bugzilla.wikimedia.org/enter_bug.cgi?product=VisualEditor&component=General)
+using the `VisualEditor` product.  Feel free to use the `General`
+component if you don't know where else your bug might belong. Don't
+worry about specifying version, severity, hardware, or OS.
+
+## Running tests
+
+VisualEditor's build scripts use the [Grunt](http://gruntjs.com/) task runner.
+To install it make sure you have [node and npm](http://nodejs.org/download/)
+installed, then run:
+
+```sh
+# Install Grunt command-line utility
+$ npm install -g grunt-cli
+
+# Install VisualEditor's dev dependencies
+$ npm install
+```
+
+To run the tests, use:
+```sh
+$ grunt test
+```
+
+For other grunt tasks, see:
+```sh
+$ grunt --help
+```
+
+To run the tests in a web browser, make sure your MediaWiki install is
+[configured](https://www.mediawiki.org/wiki/Manual:JavaScript_unit_testing) to
+allow running of tests. Set in `LocalSettings.php`:
+```php
+// https://www.mediawiki.org/wiki/Manual:JavaScript_unit_testing
+$wgEnableJavaScriptTest = true;
+```
+
+Then open `http://URL_OF_MEDIAWIKI/index.php/Special:JavaScriptTest/qunit`
+(for example, <http://localhost/w/index.php/Special:JavaScriptTest/qunit>).
+
+## Building documentation
+
+VisualEditor uses [JSDuck](https://github.com/senchalabs/jsduck) to process
+documentation comments embedded in the code.  To build the documentation, you
+will need `ruby`, `gem`, and `jsduck` installed.
+
+### Installing ruby and gem
+
+You're mostly on your own here, but we can give some hints for Mac OS X.
+
+##### Installing Gem in Mac OS X
+Ruby ships with OSX but may be outdated. Use [Homebrew](http://mxcl.github.com/homebrew/):
+```sh
+$ brew install ruby
+```
+
+If you've never used `gem` before, don't forget to add the gem's bin to your
+`PATH` ([howto](http://stackoverflow.com/a/14138490/319266)).
+
+### Installing jsduck
+
+Once you have gem, installing [JSDuck](https://github.com/senchalabs/jsduck) is easy:
+```sh
+$ gem install --user-install jsduck --version '< 5'
+```
+
+You need to make sure that you are using jsduck 4.x, as jsduck 5.x introduced
+incompatible changes to custom tags.
+
+### Running jsduck
+
+Creating the documentation is easy:
+```sh
+$ cd VisualEditor
+$ .docs/generate.sh
+```
+
+You may need to set `MW_INSTALL_PATH` in your environment to the location of
+your mediawiki installation if VisualEditor is not checked out directly in the
+mediawiki extensions folder (for example, if you're using a symlink).
+
+The generated documentation is in the `docs/` subdirectory.  View the
+documentation at
+`http://URL_OF_MEDIAWIKI/extensions/VisualEditor/docs/`
+(for example, <http://localhost/w/extensions/VisualEditor/docs>).
+
+Note that `jsduck` doesn't support browsing vis the `file:` protocol.
+
+## VisualEditor Code Guidelines
 
 We inherit the code structure (about whitespace, naming and comments) conventions
-from MediaWiki. See [Manual:Coding conventions/JavaScript#Code structure](https://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript#Code_structure) on mediawiki.org.
+from MediaWiki. See [Manual:Coding conventions/JavaScript](https://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript)
+on mediawiki.org.
 
-## Documentation comments
+### Documentation comments
 
 * End sentences in a full stop.
 * Continue sentences belonging to an annotation on the next line, indented with an
@@ -12,34 +111,6 @@ from MediaWiki. See [Manual:Coding conventions/JavaScript#Code structure](https:
   that are listed in the Types section of this document, otherwise use the identifier
   (full path from the global scope) of the constructor function (e.g. `{ve.dm.BranchNode}`).
 
-### Generate documentation
-
-#### Gem (Mac OS X)
-Ruby ships with OSX but may be outdated. Use [Homebrew](http://mxcl.github.com/homebrew/):
-```
-$ brew install ruby
-```
-
-If you've never used `gem` before, don't forget to add the gem's bin to your `PATH` ([howto](http://stackoverflow.com/a/14138490/319266)).
-
-#### Install
-Once you have gem, installing [JSDuck](https://github.com/senchalabs/jsduck) is easy:
-```
-$ gem install jsduck
-```
-
-#### Run
-```
-$ cd VisualEditor
-$ .docs/generate.sh
-# open http://localhost/VisualEditor/docs/
-```
-
-For more options:
-```
-$ jsduck --help
-```
-
 ### Annotations
 
 We use the following annotations. They should be used in the order as they are described

README.md

@@ -16,8 +16,8 @@ and [Parsoid][] pages on mediawiki.
 For information on installing VisualEditor on a local wiki, please
 see https://www.mediawiki.org/wiki/Extension:VisualEditor
 
-For information about contributing code to VisualEditor, see
-[CODING.md][].  Patch submissions are reviewed and managed with
+For information about running tests and contributing code to VisualEditor,
+see [CODING.md][].  Patch submissions are reviewed and managed with
 [Gerrit][].  There is also [API documentation][] available for the
 VisualEditor.
 

package.json

@@ -11,7 +11,7 @@
   "licenses": [
     {
       "type": "MIT",
-      "url": "https://gerrit.wikimedia.org/r/gitweb?p=mediawiki/extensions/VisualEditor.git;a=blob;f=LICENSE.txt;hb=HEAD"
+      "url": "https://git.wikimedia.org/blob/mediawiki%2Fextensions%2FVisualEditor.git/master/LICENSE.txt"
     }
   ],
   "devDependencies": {