vendor/oojs/oojs-ui/README.md

   1 [![npm](https://img.shields.io/npm/v/oojs-ui.svg?style=flat)](https://www.npmjs.com/package/oojs-ui) [![Packagist](https://img.shields.io/packagist/v/oojs/oojs-ui.svg?style=flat)](https://packagist.org/packages/oojs/oojs-ui) [![David](https://img.shields.io/david/dev/wikimedia/oojs-ui.svg?style=flat)](https://david-dm.org/wikimedia/oojs-ui#info=devDependencies)
   2
   3 OOjs UI
   4 =================
   5
   6 OOjs UI is a modern JavaScript UI toolkit. It provides common widgets, layouts, dialogs and icons that are ready to use, as well as many useful and convenient classes for constructing custom user interfaces. It is the standard user-interface library in Wikimedia Foundation Web products, having been originally created for use by [VisualEditor](https://www.mediawiki.org/wiki/VisualEditor), which uses it for its entire user interface.
   7
   8 Quick start
   9 ----------
  10
  11 This library is available as an [npm](https://npmjs.org/) package! Install it right away:
  12 <pre lang="bash">
  13 npm install oojs-ui
  14 </pre>
  15
  16 If you don't want to use npm, you can:
  17
  18 1. Clone the repo and move into it, `$ git clone https://phabricator.wikimedia.org/diffusion/GOJU/oojs-ui.git oojs-ui && cd oojs-ui`.
  19
  20 2. Install Grunt command-line utility:<br>`$ npm install -g grunt-cli`
  21
  22 3. Install [composer](https://getcomposer.org/download/) and make sure running `composer` will execute it (*e.g.* add it to `$PATH` in POSIX environments).
  23
  24 4. Install dev dependencies:<br>`$ npm install`
  25
  26 5. Build the library (you can alternatively use `grunt quick-build` if you don't need to rebuild the PNGs):<br>`$ grunt build`
  27
  28 6. You can now copy the distribution files from the dist directory into your project.
  29
  30 7. You can see a suite of demos in `/demos` by executing:<br>`$ npm run-script demos`
  31
  32
  33 Loading the library
  34 -------------------
  35
  36 While the distribution directory is chock-full of files, you will normally only need to load three:
  37
  38 * `oojs-ui.js`, containing the full library;
  39 * One of `oojs-ui-wikimediaui.css` or `oojs-ui-apex.css`, containing theme-specific styles; and
  40 * One of `oojs-ui-wikimediaui.js` or  `oojs-ui-apex.js`, containing theme-specific code
  41
  42 You can load additional icon packs from files named `oojs-ui-mediawiki-icons-*.css` or  `oojs-ui-apex-icons-*.css`.
  43
  44 The remaining files make it possible to load only parts of the whole library.
  45
  46 Furthermore, every CSS file has a right-to-left (RTL) version available, to be used on pages using right-to-left languages if your environment doesn't automatically flip them as needed.
  47
  48
  49 Versioning
  50 ----------
  51
  52 We use the Semantic Versioning guidelines as much as possible.
  53
  54 Releases will be numbered in the following format:
  55
  56 `<major>.<minor>.<patch>`
  57
  58 For more information on SemVer, please visit http://semver.org/.
  59
  60
  61 Issue tracker
  62 -------------
  63
  64 Found a bug or missing feature? Please report it in our [issue tracker Phabricator](https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=PHID-PROJ-dgmoevjqeqlerleqzzx5)!
  65
  66
  67 Contributing
  68 ------------
  69
  70 We are always delighted when people contribute patches. We recommend a few things to make it quicker and easier for you to contribute:
  71
  72 * You will need a [Wikitech account](https://wikitech.wikimedia.org/w/index.php?title=Special:UserLogin&returnto=Help%3AGetting+Started&type=signup) which you can use to login to [Gerrit](https://gerrit.wikimedia.org/), our code review system.
  73 * You will need a [Wikimedia account](https://www.mediawiki.org/w/index.php?title=Special:UserLogin&type=signup), which you can [use to login to Phabricator](https://www.mediawiki.org/w/index.php?title=Special:UserLogin&returnto=Special%3AOAuth%2Fauthorize&returntoquery=oauth_token%3D2fa60627878b83173e0196040b983326%26oauth_consumer_key%3D038ec949b263dc807b0079fd88538f37).
  74 * You should [create a Phabricator ticket](https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=PHID-PROJ-dgmoevjqeqlerleqzzx5) describing the issue you wish to change.
  75 * We automatically lint and style-check changes to JavaScript, PHP, CSS, Ruby and JSON files. You can test these yourself with `npm test` and `composer test` locally before pushing changes. SVG files should be squashed in advance of committing with [SVGO](https://github.com/svg/svgo) using `svgo --pretty --disable=removeXMLProcInst --disable=cleanupIDs <filename>`.
  76 * To submit your patch, follow [the "getting started" quick-guide](https://www.mediawiki.org/wiki/Gerrit/Getting_started). You should expect to get code review within a day or two.
  77 * A new version of the library is cut and released most weeks on Tuesdays.
  78
  79
  80 Release
  81 ----------
  82
  83 Release process:
  84 <pre lang="bash">
  85 $ cd path/to/oojs-ui/
  86 $ git remote update
  87 $ git checkout -B release -t origin/master
  88
  89 # Ensure tests pass
  90 $ npm install && composer update && npm test && composer test
  91
  92 # Avoid using "npm version patch" because that creates
  93 # both a commit and a tag, and we shouldn't tag until after
  94 # the commit is merged.
  95
  96 # Update release notes
  97 # Copy the resulting list into a new section at the top of History.md and edit
  98 # into five sub-sections, in order:
  99 # * Breaking changes
 100 # * Deprecations
 101 # * Features
 102 # * Styles
 103 # * Code
 104 $ git log --format='* %s (%aN)' --no-merges --reverse v$(node -e 'console.log(require("./package.json").version);')...HEAD | grep -v "Localisation updates from" | sort
 105 $ edit History.md
 106
 107 # Update the version number
 108 $ edit package.json
 109
 110 $ git add -p
 111 $ git commit -m "Tag vX.X.X"
 112 $ git review
 113
 114 # After merging:
 115 $ git remote update
 116 $ git checkout origin/master
 117 $ git tag "vX.X.X"
 118 $ npm run publish-build && git push --tags && npm publish
 119 </pre>