resources/lib/oojs/README.md

   1 [![npm](https://img.shields.io/npm/v/oojs.svg?style=flat)](https://www.npmjs.com/package/oojs) [![David](https://img.shields.io/david/dev/wikimedia/oojs.svg?style=flat)](https://david-dm.org/wikimedia/oojs#info=devDependencies)
   2
   3 OOjs
   4 =================
   5
   6 OOjs is a JavaScript library for working with objects.
   7
   8 Key features include inheritance, mixins and utilities for working with objects.
   9
  10 <pre lang="javascript">
  11 /* Example */
  12 ( function ( oo ) {
  13     function Animal() {}
  14     function Magic() {}
  15     function Unicorn() {
  16         Animal.call( this );
  17         Magic.call( this );
  18     }
  19     oo.inheritClass( Unicorn, Animal );
  20     oo.mixinClass( Unicorn, Magic );
  21 }( OO ) );
  22 </pre>
  23
  24 Quick start
  25 ----------
  26
  27 This library is available as an [npm](https://npmjs.org/) package! Install it right away:
  28 <pre lang="bash">
  29 npm install oojs
  30 </pre>
  31
  32 Or clone the repo, `git clone https://phabricator.wikimedia.org/diffusion/GOJS/oojs.git`.
  33
  34 ECMAScript 5
  35 ----------
  36
  37 OOjs requires a modern ECMAScript 5 environment. It is not necessarily compatible with ES3 engines (such as for IE 6-8). For ES3 environments, the old 1.x releases are available but not recommended.
  38
  39 jQuery
  40 ----------
  41
  42 If your project uses jQuery, use the optimised `oojs.jquery.js` build instead.
  43
  44 This build assumes jQuery is present and omits various chunks of code in favour of references to jQuery.
  45
  46 jQuery 3.0.0 or higher is required.
  47
  48 Versioning
  49 ----------
  50
  51 We use the Semantic Versioning guidelines as much as possible.
  52
  53 Releases will be numbered in the following format:
  54
  55 `<major>.<minor>.<patch>`
  56
  57 For more information on SemVer, please visit http://semver.org/.
  58
  59 Bug tracker
  60 -----------
  61
  62 Found a bug? Please report it in the [issue tracker](https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=OOjs)!
  63
  64 Release
  65 ----------
  66
  67 Release process:
  68 <pre lang="bash">
  69 $ cd path/to/oojs/
  70 $ git remote update
  71 $ git checkout -B release -t origin/master
  72
  73 # Ensure tests pass
  74 $ npm install && npm test
  75
  76 # Avoid using "npm version patch" because that creates
  77 # both a commit and a tag, and we shouldn't tag until after
  78 # the commit is merged.
  79
  80 # Update release notes
  81 # Copy the resulting list into a new section on History.md
  82 $ git log --format='* %s (%aN)' --no-merges --reverse v$(node -e 'console.log(require("./package.json").version);')...HEAD
  83 $ edit History.md
  84
  85 # Update the version number
  86 $ edit package.json
  87
  88 $ git add -p
  89 $ git commit -m "Tag vX.X.X"
  90 $ git review
  91
  92 # After merging:
  93 $ git remote update
  94 $ git checkout origin/master
  95 $ git tag "vX.X.X"
  96 $ git push --tags
  97 $ npm publish
  98 </pre>