Cscott has uploaded a new change for review. https://gerrit.wikimedia.org/r/81272
Change subject: Updates to README.md and CODING.md. ...................................................................... Updates to README.md and CODING.md. Describe how to report bugs, install grunt, and update jsduck instructions. Fix path to license file in package.json. Change-Id: I276ff0ea4324f027dafc044a86fa564b2439089a --- M CODING.md M README.md M package.json 3 files changed, 71 insertions(+), 19 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/VisualEditor refs/changes/72/81272/1 diff --git a/CODING.md b/CODING.md index 5ed791c..baf1ede 100644 --- a/CODING.md +++ b/CODING.md @@ -1,20 +1,49 @@ -# VisualEditor Code Guidelines +# Contributing to Visual Editor -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. +Thank you for helping us develop the Visual Editor! -## Documentation comments +This file discusses how to report bugs, set up a development environment, +run tests, and build documentation. It also provides the code style +guidelines we use on the project. -* End sentences in a full stop. -* Continue sentences belonging to an annotation on the next line, indented with an - additional space. -* Types in documentation comments should be separated by a pipe character. Use types - 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}`). +## Bug reports -### Generate documentation +Please report bugs using the +[Wikimedia Foundation's bugzilla instance](https://bugzilla.wikimedia.org/). +Use the `VisualEditor` product, and 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. -#### Gem (Mac OS X) +## Running tests + +VisualEditor uses the [Grunt](http://gruntjs.com/) task runner. +To install it (and other needed packages), run: +```sh +$ npm install +$ npm install -g grunt-cli +``` + +To run the tests, use: +```sh +$ grunt test +``` + +For other grunt tasks, see: +```sh +$ grunt --help +``` + +## 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/): ``` $ brew install ruby @@ -22,17 +51,25 @@ 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 +### Installing jsduck + Once you have gem, installing [JSDuck](https://github.com/senchalabs/jsduck) is easy: ``` -$ gem install jsduck +$ gem install --user-install jsduck --version '< 5' ``` -#### Run +You need to make sure that you are using jsduck 4.x, as jsduck 5.x introduced +incompatible changes to custom tags. + +### Running jsduck + +First, set `MW_INSTALL_PATH` in your environment to the location of your +mediawiki installation. Then: + ``` $ cd VisualEditor $ .docs/generate.sh -# open http://localhost/VisualEditor/docs/ +$ open ./docs/index.html ``` For more options: @@ -40,6 +77,21 @@ $ jsduck --help ``` + +## 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. + +### Documentation comments + +* End sentences in a full stop. +* Continue sentences belonging to an annotation on the next line, indented with an + additional space. +* Types in documentation comments should be separated by a pipe character. Use types + 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}`). + ### 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 609f80c..a8dd1ce 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,8 @@ 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 1e8b3c0..b80e08b 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": { -- To view, visit https://gerrit.wikimedia.org/r/81272 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I276ff0ea4324f027dafc044a86fa564b2439089a Gerrit-PatchSet: 1 Gerrit-Project: mediawiki/extensions/VisualEditor Gerrit-Branch: master Gerrit-Owner: Cscott <canan...@wikimedia.org> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
