From 5f392ccec1017afc366ded1ded03f11d1679c7f8 Mon Sep 17 00:00:00 2001 From: "C. Scott Ananian" Date: Tue, 27 Aug 2013 12:13:43 -0400 Subject: [PATCH] Updates to README.md and CODING.md Describe how to report bugs, install grunt, and run tests. Update jsduck instructions. Fix path to license file in package.json. Change-Id: I276ff0ea4324f027dafc044a86fa564b2439089a --- CODING.md | 133 +++++++++++++++++++++++++++++++++++++++------------ README.md | 4 +- package.json | 2 +- 3 files changed, 105 insertions(+), 34 deletions(-) diff --git a/CODING.md b/CODING.md index 4964d27168..9139230faa 100644 --- a/CODING.md +++ b/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, ). + +## 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, ). + +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 diff --git a/README.md b/README.md index 609f80c78c..a8dd1ce926 100644 --- a/README.md +++ b/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. diff --git a/package.json b/package.json index 1e8b3c0e04..b80e08b7e9 100644 --- a/package.json +++ b/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": {