Skip to content

readme: add architecture diagrams #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
NovemLinguae wants to merge 3 commits into
base: master
Choose a base branch
from
Open

readme: add architecture diagrams #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
387c3f5
docs: add architecture diagram
NovemLinguae Dec 6, 2025
f04e46a
move docs back to root, per feedback in another repo
NovemLinguae Dec 9, 2025
6818230
add an OOUI widgets diagram, update main diagram
NovemLinguae Dec 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 65 additions & 62 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,63 +1,66 @@
# Rater
This is the source code for version 2 of the Wikipedia userscript [Rater](https://en.wikipedia.org/wiki/User:Evad37/rater).

## Installation instructions and user guide
See [https://en.wikipedia.org/wiki/User:Evad37/rater](https://en.wikipedia.org/wiki/User:Evad37/rater).

## How to manually test a patch on testwiki
* `npm run build`
* Copy paste the contents of dist/rater.js to https://test.wikipedia.org/wiki/User:[YOUR_USERNAME]/rater/app.js
* Copy paste the contents of https://en.wikipedia.org/wiki/User:Evad37/rater.js to https://test.wikipedia.org/wiki/User:[YOUR_USERNAME]/rater.js
* Change line 37 to `var title = /* </nowiki> */ "User:[YOUR_USERNAME]/rater/app.js"; /* <nowiki> */`. If your username contains spaces, replace them with underscores.
* Change line 38 from en.wikipedia.org to test.wikipedia.org
* Add `importScript('User:[YOUR_USERNAME]/rater.js');` to https://test.wikipedia.org/wiki/[YOUR_USERNAME]/common.js

Testwiki has the following 3 WikiProjects that can be chosen by Rater: Africa, Belgium, China. To add more, a testwiki administrator needs to visit Special:Import, import the template files (e.g. Template:WikiProject Africa), then go modify the template to take the "portal" code out of it (throws a Lua error). Then it should show up in Category:WikiProject banners with quality assessment, which is where Rater gets its list of WikiProjects from.

Improvements to this workflow are planned in [issue #29](https://github.com/wikimedia-gadgets/rater/issues/29)

## How to deploy to enwiki
* be Evad37 or an enwiki interface administrator
* `npm run build`
* copy paste the contents of dist/rater.min.js to https://en.wikipedia.org/wiki/User:Evad37/rater/app.js

Evad37 has [given permission](https://en.wikipedia.org/w/index.php?title=User_talk:Evad37&diff=prev&oldid=1311616009) for English Wikipedia interface administrators to edit Evad37's userspace pages for the purpose of deploying updates to Rater.

Improvements to this workflow are planned in [issue #30](https://github.com/wikimedia-gadgets/rater/issues/30)

## Repository structure
- `index.js` is the main entry point, written in ES5. This is published to [User:Evad37/rater.js](https://en.wikipedia.org/wiki/User:Evad37/rater.js) (when deploying), or [User:Evad37/rater/sandbox.js](https://en.wikipedia.org/wiki/User:Evad37/rater/sandbox.js) (for sandbox testing of changes). Or [User:Evad37/rater/beta.js](https://en.wikipedia.org/wiki/User:Evad37/rater/beta.js) for beta testing.
- `rater-src\` contains the main source code for the app, split into modules, which may be written in ES6. Code here can assume that the ResourceLoader modules specified in the above files have been loaded and that the DOM is ready.
- `App.js` is the entry point
- Related code should be placed in the same module.
- Small pieces of code, not particularly related to anything, can be placed in `rater-src\util.js`
- The source code is bundled, transpiled, and minified using `npm run build`. This writes two files to the `dist\` directory:
- `dist\rater.js` contains bundled and transpiled code, with a source map. It is published to [User:Evad37/rater/sandbox/app.js](https://en.wikipedia.org/wiki/User:Evad37/rater/sandbox/app.js), for testing/debugging purposes.
- `dist\rater.min.js` is the minified version. It is published to [User:Evad37/rater/app.js](https://en.wikipedia.org/wiki/User:Evad37/rater/app.js) (the *live version* of the userscript), once the sandbox version has been adequately tested. Or [User:Evad37/rater/beta/app.js](https://en.wikipedia.org/wiki/User:Evad37/rater/beta/app.js) for beta testing.
- External scripts (other than those provided by MediaWiki) are located in the `lib\` folder, and deployed to subpages of [User:Evad37/rater/lib/](https://en.wikipedia.org/wiki/Special:PrefixIndex?prefix=User%3AEvad37%2Frater%2Flib%2F).
- This allows the bundled source code size to be smaller, and easier to work with. The scripts can be loaded with `mw.loader.getScript`, which returns a promise that resolves when the script is loaded.
- These files must have licencing which, to be compatible with English Wikipedia (CC-BY-SA-3.0/GFDL), is permissive with regards to distribution, modification, and sublicencing. E.g. Apache, BSD, MIT licences are okay; GNU licences are not okay. See [comparison table](https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licenses).

### Tooling
- **eslint** for ES6 linting
- **jshint** for ES5 linting ([ESLint doesn't support override for ecmaVersion](https://github.com/sindresorhus/eslint-config-xo/issues/16#issuecomment-190302577))
- **browserify** with **babelify** for bundling, transpiling, and source-mapping
- **uglifyjs** for minifying

## TODO
- Possible future features:
- [ ] Have a preference for portlet location
- [ ] Have a preference to autostart for particular talkpage categories
- [ ] Have a preference to autostart for subject-page categories that match a word/regex pattern
- [ ] Allow order of banners to be adjusted
- [ ] Investigate unit testing
- Is node-based unit testing even possible, given the reliance on globals like `mw` and `OO`?
- Look at how v1 is using QUnit unit testing. Maybe replicate or iterate on that.
- Or maybe have QUnit tesing inside the app source code, that gets run if the url contains a query parameter such as `&testrater=1`?
- [ ] Improve documentation
- [ ] ... probably other things too - finish off this list, and/or put issues on the github page.

### Roadmap
- [X] Complete the v2 rewrite
- [X] Get beta testers to try out the new version. Fix/adjust things as they get reported.
# Rater
This is the source code for version 2 of the Wikipedia userscript [Rater](https://en.wikipedia.org/wiki/User:Evad37/rater).

## Installation instructions and user guide
See [https://en.wikipedia.org/wiki/User:Evad37/rater](https://en.wikipedia.org/wiki/User:Evad37/rater).

## How to manually test a patch on testwiki
* `npm run build`
* Copy paste the contents of dist/rater.js to https://test.wikipedia.org/wiki/User:[YOUR_USERNAME]/rater/app.js
* Copy paste the contents of https://en.wikipedia.org/wiki/User:Evad37/rater.js to https://test.wikipedia.org/wiki/User:[YOUR_USERNAME]/rater.js
* Change line 37 to `var title = /* </nowiki> */ "User:[YOUR_USERNAME]/rater/app.js"; /* <nowiki> */`. If your username contains spaces, replace them with underscores.
* Change line 38 from en.wikipedia.org to test.wikipedia.org
* Add `importScript('User:[YOUR_USERNAME]/rater.js');` to https://test.wikipedia.org/wiki/[YOUR_USERNAME]/common.js

Testwiki has the following 3 WikiProjects that can be chosen by Rater: Africa, Belgium, China. To add more, a testwiki administrator needs to visit Special:Import, import the template files (e.g. Template:WikiProject Africa), then go modify the template to take the "portal" code out of it (throws a Lua error). Then it should show up in Category:WikiProject banners with quality assessment, which is where Rater gets its list of WikiProjects from.

Improvements to this workflow are planned in [issue #29](https://github.com/wikimedia-gadgets/rater/issues/29)

## How to deploy to enwiki
* be Evad37 or an enwiki interface administrator
* `npm run build`
* copy paste the contents of dist/rater.min.js to https://en.wikipedia.org/wiki/User:Evad37/rater/app.js

Evad37 has [given permission](https://en.wikipedia.org/w/index.php?title=User_talk:Evad37&diff=prev&oldid=1311616009) for English Wikipedia interface administrators to edit Evad37's userspace pages for the purpose of deploying updates to Rater.

Improvements to this workflow are planned in [issue #30](https://github.com/wikimedia-gadgets/rater/issues/30)

## Repository structure
- `index.js` is the main entry point, written in ES5. This is published to [User:Evad37/rater.js](https://en.wikipedia.org/wiki/User:Evad37/rater.js) (when deploying), or [User:Evad37/rater/sandbox.js](https://en.wikipedia.org/wiki/User:Evad37/rater/sandbox.js) (for sandbox testing of changes). Or [User:Evad37/rater/beta.js](https://en.wikipedia.org/wiki/User:Evad37/rater/beta.js) for beta testing.
- `rater-src\` contains the main source code for the app, split into modules, which may be written in ES6. Code here can assume that the ResourceLoader modules specified in the above files have been loaded and that the DOM is ready.
- `App.js` is the entry point
- Related code should be placed in the same module.
- Small pieces of code, not particularly related to anything, can be placed in `rater-src\util.js`
- The source code is bundled, transpiled, and minified using `npm run build`. This writes two files to the `dist\` directory:
- `dist\rater.js` contains bundled and transpiled code, with a source map. It is published to [User:Evad37/rater/sandbox/app.js](https://en.wikipedia.org/wiki/User:Evad37/rater/sandbox/app.js), for testing/debugging purposes.
- `dist\rater.min.js` is the minified version. It is published to [User:Evad37/rater/app.js](https://en.wikipedia.org/wiki/User:Evad37/rater/app.js) (the *live version* of the userscript), once the sandbox version has been adequately tested. Or [User:Evad37/rater/beta/app.js](https://en.wikipedia.org/wiki/User:Evad37/rater/beta/app.js) for beta testing.
- External scripts (other than those provided by MediaWiki) are located in the `lib\` folder, and deployed to subpages of [User:Evad37/rater/lib/](https://en.wikipedia.org/wiki/Special:PrefixIndex?prefix=User%3AEvad37%2Frater%2Flib%2F).
- This allows the bundled source code size to be smaller, and easier to work with. The scripts can be loaded with `mw.loader.getScript`, which returns a promise that resolves when the script is loaded.
- These files must have licencing which, to be compatible with English Wikipedia (CC-BY-SA-3.0/GFDL), is permissive with regards to distribution, modification, and sublicencing. E.g. Apache, BSD, MIT licences are okay; GNU licences are not okay. See [comparison table](https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licenses).

[![Architecture diagram](architecture_main.svg)](architecture_main.svg)
[![OOUI widgets diagram](ooui.svg)](ooui.svg)

### Tooling
- **eslint** for ES6 linting
- **jshint** for ES5 linting ([ESLint doesn't support override for ecmaVersion](https://github.com/sindresorhus/eslint-config-xo/issues/16#issuecomment-190302577))
- **browserify** with **babelify** for bundling, transpiling, and source-mapping
- **uglifyjs** for minifying

## TODO
- Possible future features:
- [ ] Have a preference for portlet location
- [ ] Have a preference to autostart for particular talkpage categories
- [ ] Have a preference to autostart for subject-page categories that match a word/regex pattern
- [ ] Allow order of banners to be adjusted
- [ ] Investigate unit testing
- Is node-based unit testing even possible, given the reliance on globals like `mw` and `OO`?
- Look at how v1 is using QUnit unit testing. Maybe replicate or iterate on that.
- Or maybe have QUnit tesing inside the app source code, that gets run if the url contains a query parameter such as `&testrater=1`?
- [ ] Improve documentation
- [ ] ... probably other things too - finish off this list, and/or put issues on the github page.

### Roadmap
- [X] Complete the v2 rewrite
- [X] Get beta testers to try out the new version. Fix/adjust things as they get reported.
- [X] Release the new version generally.
Loading