resources/lib/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 OOUI
   4 =================
   5
   6 OOUI is a component-based JavaScript UI library. Key features:
   7
   8 * Common widgets, layouts, and dialogs
   9 * Classes, elements, and mixins to create custom interfaces
  10 * Internationalization and localization, like right-to-left (RTL) languages support
  11 * Theme-ability
  12 * Built-in icons
  13 * Accessibility features
  14
  15 It is the standard library for Web products at the Wikimedia Foundation, having been originally created for use by [VisualEditor](https://www.mediawiki.org/wiki/VisualEditor).
  16
  17
  18 Quick start
  19 ----------
  20
  21 The library is available on [npm](https://www.npmjs.com/package/oojs-ui). To install:
  22
  23 <pre lang="bash">
  24 $ npm install oojs-ui
  25 </pre>
  26
  27 Once installed, include the following scripts and styles to get started:
  28
  29 <pre lang="html">
  30 <script src="node_modules/jquery/dist/jquery.min.js"></script>
  31 <script src="node_modules/oojs/dist/oojs.min.js"></script>
  32
  33 <script src="node_modules/oojs-ui/dist/oojs-ui.min.js"></script>
  34 <script src="node_modules/oojs-ui/dist/oojs-ui-wikimediaui.min.js"></script>
  35 <link rel="stylesheet" href="node_modules/oojs-ui/dist/oojs-ui-wikimediaui.min.css">
  36 </pre>
  37
  38
  39 Loading the library
  40 -------------------
  41
  42 While the distribution directory is chock-full of files, you will normally load only the following three:
  43
  44 * `oojs-ui.js`, containing the full library;
  45 * One of `oojs-ui-wikimediaui.css` or `oojs-ui-apex.css`, containing theme-specific styles; and
  46 * One of `oojs-ui-wikimediaui.js` or  `oojs-ui-apex.js`, containing theme-specific code
  47
  48 You can load additional icon packs from files named `oojs-ui-wikimediaui-icons-*.css` or `oojs-ui-apex-icons-*.css`.
  49
  50 The remaining files make it possible to load only parts of the whole library.
  51
  52 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.
  53
  54
  55 Issue tracker
  56 -------------
  57
  58 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)!
  59
  60
  61 Contributing
  62 ------------
  63
  64 We are always delighted when people contribute patches. To setup your development environment:
  65
  66
  67 1. Clone the repo: `$ git clone https://phabricator.wikimedia.org/diffusion/GOJU/oojs-ui.git oojs-ui`
  68
  69 2. Move into the library directory:<br>`$ cd oojs-ui`
  70
  71 3. Install [composer](https://getcomposer.org/download/) and make sure running `composer` will execute it (*e.g.* add it to `$PATH` in POSIX environments).
  72
  73 4. Install dev dependencies:<br>`$ npm install`
  74
  75 5. Build the library (you can alternatively use `grunt quick-build` if you don't need to rebuild the PNGs):<br>`$ grunt build`
  76
  77 6. You can see a suite of demos in `/demos` by executing:<br>`$ npm run-script demos`
  78
  79 7. You can also copy the distribution files from the dist directory into your project.
  80
  81
  82 We use [Gerrit](https://gerrit.wikimedia.org/) for code review, and [Phabricator](https://phabricator.wikimedia.org) to track issues. To contribute patches or join discussions all you need is a [developer account](https://wikitech.wikimedia.org/w/index.php?title=Special:CreateAccount&returnto=Help%3AGetting+Started).
  83
  84 * If you've found a bug, or wish to request a feature [raise a ticket on Phabricator](https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=PHID-PROJ-dgmoevjqeqlerleqzzx5).
  85 * To submit your patch, follow [the "getting started" quick-guide](https://www.mediawiki.org/wiki/Gerrit/Getting_started). We try to review patches within a week.
  86 * We automatically lint and style-check changes to JavaScript, PHP, LESS/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>`.
  87
  88 A new version of the library is released most weeks on Tuesdays.
  89
  90 Community
  91 ---------
  92
  93 Get updates, ask questions and join the discussion with maintainers and contributors:
  94
  95 * Join the Wikimedia Developers mailing list, [wikitech-l](https://lists.wikimedia.org/mailman/listinfo/wikitech-l).
  96 * Chat with the maintainers on `#wikimedia-dev` on `irc.freenode.net`.
  97 * Ask questions on [StackOverflow](https://stackoverflow.com/tags/oojs-ui/info).
  98 * Watchlist the [documentation](https://www.mediawiki.org/wiki/OOUI) on MediaWiki to stay updated.
  99
 100
 101 Versioning
 102 ----------
 103
 104 We use the [Semantic Versioning guidelines](http://semver.org/).
 105
 106 Releases will be numbered in the following format:
 107
 108 `<major>.<minor>.<patch>`
 109
 110
 111 Release
 112 ----------
 113
 114 Release process:
 115 <pre lang="bash">
 116
 117     $ cd path/to/oojs-ui/
 118     $ git remote update
 119     $ git checkout -B release -t origin/master
 120
 121     # Ensure tests pass
 122     $ npm install && composer update && npm test && composer test
 123
 124     # Avoid using "npm version patch" because that creates
 125     # both a commit and a tag, and we shouldn't tag until after
 126     # the commit is merged.
 127
 128     # Update release notes
 129     # Copy the resulting list into a new section at the top of History.md and edit
 130     # into five sub-sections, in order:
 131     # * Breaking changes
 132     # * Deprecations
 133     # * Features
 134     # * Styles
 135     # * Code
 136     $ git log --format='* %s (%aN)' --no-merges --reverse v$(node -e 'console.log(require("./package.json").version);')...HEAD | grep -v "Localisation updates from" | sort
 137     $ edit History.md
 138
 139     # Update the version number
 140     $ edit package.json
 141
 142     $ git add -p
 143     $ git commit -m "Tag vX.X.X"
 144     $ git review
 145
 146     # After merging:
 147     $ git remote update
 148     $ git checkout origin/master
 149     $ git tag "vX.X.X"
 150     $ npm run publish-build && git push --tags && npm publish
 151
 152 </pre>