Jforrester has uploaded a new change for review. ( https://gerrit.wikimedia.org/r/351213 )
Change subject: lib: Update README files for OOjs and OOjs UI ...................................................................... lib: Update README files for OOjs and OOjs UI Change-Id: I1413136830ce6072315869075704d0d13b7eecb3 --- A lib/oojs-ui/AUTHORS.txt A lib/oojs-ui/LICENSE-MIT A lib/oojs-ui/README.md M lib/oojs/README.md 4 files changed, 189 insertions(+), 23 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/VisualEditor/VisualEditor refs/changes/13/351213/1 diff --git a/lib/oojs-ui/AUTHORS.txt b/lib/oojs-ui/AUTHORS.txt new file mode 100644 index 0000000..a17f3a4 --- /dev/null +++ b/lib/oojs-ui/AUTHORS.txt @@ -0,0 +1,46 @@ +Principal Authors (major contributors, alphabetically) + +Bartosz Dziewoński <[email protected]> +Ed Sanders <[email protected]> +James D. Forrester <[email protected]> +Kirsten Menger-Anderson <[email protected]> +Kunal Mehta <[email protected]> +Prateek Saxena <[email protected]> +Roan Kattouw <[email protected]> +Rob Moen <[email protected]> +Timo Tijhof <[email protected]> +Trevor Parscal <[email protected]> + +Patch Contributors (minor contributors, alphabetically) + +Alex Monk <[email protected]> +Amir E. Aharoni <[email protected]> +Antoine Musso <[email protected]> +Brad Jorsch <[email protected]> +C. Scott Ananian <[email protected]> +David Lynch <[email protected]> +Derk-Jan Hartman <[email protected]> +eranroz <[email protected]> +Erick Guan <[email protected]> +Erik Moeller <[email protected]> +Florian <[email protected]> +Gilles Dubuc <[email protected]> +Inez Korczyński <[email protected]> +Juliusz Gonera <[email protected]> +Kyle Florence <[email protected]> +Matthew Flaschen <[email protected]> +May Tee-Galloway <[email protected]> +Moriel Schottlender <[email protected]> +Mr. Stradivarius <[email protected]> +Niklas Laxström <[email protected]> +Nirzar Pangarkar <[email protected]> +Ricordisamoa <[email protected]> +rillke <[email protected]> +Ryan Kaldari <[email protected]> +Sam Reed <[email protected]> +Stephane Bisson <[email protected]> +Sucheta Ghoshal <[email protected]> +Thalia Chan <[email protected]> +Volker Eckl <[email protected]> +Wei-Ko Kao <[email protected]> +Željko Filipin <[email protected]> diff --git a/lib/oojs-ui/LICENSE-MIT b/lib/oojs-ui/LICENSE-MIT new file mode 100644 index 0000000..25303af --- /dev/null +++ b/lib/oojs-ui/LICENSE-MIT @@ -0,0 +1,20 @@ +Copyright 2011-2017 OOjs UI Team and other contributors. + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/lib/oojs-ui/README.md b/lib/oojs-ui/README.md new file mode 100644 index 0000000..5cbc067 --- /dev/null +++ b/lib/oojs-ui/README.md @@ -0,0 +1,119 @@ +[](https://www.npmjs.com/package/oojs-ui) [](https://packagist.org/packages/oojs/oojs-ui) [](https://david-dm.org/wikimedia/oojs-ui#info=devDependencies) + +OOjs UI +================= + +OOjs UI is a modern JavaScript UI toolkit for browsers. It provides a library of common widgets, layouts and windows that are ready to use, as well as many foundational classes for constructing custom user interfaces. The library was originally created for use by [VisualEditor](https://www.mediawiki.org/wiki/VisualEditor), which uses it for its entire user interface, and is now completely independent, and more useful and convenient for other use cases. + +Quick start +---------- + +This library is available as an [npm](https://npmjs.org/) package! Install it right away: +<pre lang="bash"> +npm install oojs-ui +</pre> + +If you don't want to use npm, you can: + +1. Clone the repo and move into it, `$ git clone https://phabricator.wikimedia.org/diffusion/GOJU/oojs-ui.git oojs-ui && cd oojs-ui`. + +2. Install Grunt command-line utility:<br/>`$ npm install -g grunt-cli` + +3. Install [composer](https://getcomposer.org/download/) and make sure running `composer` will execute it (*e.g.* add it to `$PATH` in POSIX environments). + +4. Install dev dependencies:<br/>`$ npm install` + +5. Build the library (you can alternatively use `grunt quick-build` if you don't need to rebuild the PNGs):<br/>`$ grunt build` + +6. You can now copy the distribution files from the dist directory into your project. + +7. You can see a suite of demos in `/demos` by executing:<br/>`$ npm run-script demos` + + +Loading the library +------------------- + +While the distribution directory is chock-full of files, you will normally only need to load three: + +* `oojs-ui.js`, containing the full library +* One of `oojs-ui-apex.css` or `oojs-ui-mediawiki.css`, containing theme-specific styles +* One of `oojs-ui-apex.js` or `oojs-ui-mediawiki.js`, containing theme-specific code + +You can load additional icon packs from files named `oojs-ui-apex-icons-*.css` or `oojs-ui-mediawiki-icons-*.css`. + +The remaining files make it possible to load only parts of the whole library. + +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. + + +Versioning +---------- + +We use the Semantic Versioning guidelines as much as possible. + +Releases will be numbered in the following format: + +`<major>.<minor>.<patch>` + +For more information on SemVer, please visit http://semver.org/. + + +Issue tracker +------------- + +Found a bug or missing feature? Please report it in the [issue tracker](https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=PHID-PROJ-dgmoevjqeqlerleqzzx5)! + + +Contributing +------------ + +We are always delighted when people contribute patches. We recommend a few things to make it quicker and easier for you to contribute: + +* 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. +* 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). +* 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. +* 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>`. +* 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. +* A new version of the library is cut and released most weeks on Tuesdays. + + +Release +---------- + +Release process: +<pre lang="bash"> +$ cd path/to/oojs-ui/ +$ git remote update +$ git checkout -B release -t origin/master + +# Ensure tests pass +$ npm install && composer update && npm test && composer test + +# Avoid using "npm version patch" because that creates +# both a commit and a tag, and we shouldn't tag until after +# the commit is merged. + +# Update release notes +# Copy the resulting list into a new section at the top of History.md and edit +# into five sub-sections, in order: +# * Breaking changes +# * Deprecations +# * Features +# * Styles +# * Code +$ git log --format='* %s (%aN)' --no-merges --reverse v$(node -e 'console.log(require("./package.json").version);')...HEAD | grep -v "Localisation updates from" | sort +$ edit History.md + +# Update the version number +$ edit package.json + +$ git add -p +$ git commit -m "Tag vX.X.X" +$ git review + +# After merging: +$ git remote update +$ git checkout origin/master +$ git tag "vX.X.X" +$ npm run publish-build && git push --tags && npm publish +</pre> diff --git a/lib/oojs/README.md b/lib/oojs/README.md index df6b2f9..ec14576 100644 --- a/lib/oojs/README.md +++ b/lib/oojs/README.md @@ -29,31 +29,12 @@ npm install oojs </pre> -Or clone the repo, `git clone https://git.wikimedia.org/git/oojs/core.git`. +Or clone the repo, `git clone https://phabricator.wikimedia.org/diffusion/GOJS/oojs.git`. ECMAScript 5 ---------- -OOjs is optimised for modern ECMAScript 5 environments. However, care has been taken to maintain -parser compatibility with ES3 engines (such as for IE 6-8). - -No ES5 syntax or unpolyfillable features are used. To support ES3 engines, ensure an appropriate -polyfill is loaded before OOjs. - -These are the methods used: - -* Array.isArray -* Object.keys -* JSON.stringify - -Additionally, Object.create is used if available. As it is impossible to fully polyfill, OOjs -includes a fallback implementing the minimal set of required features. - -While there are no plans to ship a polyfill for remaining methods, we recommend the following and -use them ourselves in the unit tests to assert support for older browsers. - -* [json2.js](https://github.com/douglascrockford/JSON-js) (only for IE6/IE7) -* [es5-shim.js](https://github.com/es-shims/es5-shim) +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. jQuery ---------- @@ -62,7 +43,7 @@ This build assumes jQuery is present and omits various chunks of code in favour of references to jQuery. -jQuery 1.8.3 or higher is recommended. +jQuery 3.0.0 or higher is required. Versioning ---------- @@ -78,7 +59,7 @@ Bug tracker ----------- -Found a bug? Please report it in the [issue tracker](https://phabricator.wikimedia.org/maniphest/task/create/?projects=OOjs)! +Found a bug? Please report it in the [issue tracker](https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=OOjs)! Release ---------- -- To view, visit https://gerrit.wikimedia.org/r/351213 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I1413136830ce6072315869075704d0d13b7eecb3 Gerrit-PatchSet: 1 Gerrit-Project: VisualEditor/VisualEditor Gerrit-Branch: master Gerrit-Owner: Jforrester <[email protected]> _______________________________________________ MediaWiki-commits mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
