Skip to content

Latest commit

 

History

History
182 lines (141 loc) · 13.4 KB

DEVELOPER.md

File metadata and controls

182 lines (141 loc) · 13.4 KB
Raw

Helpful information for Twinkle devs

Reviewing and merging pull requests (WIP)

Collaborators are encouraged to thoroughly review and test each pull request, including their own. Unless urgent or obvious, it can be helpful to leave PRs open for folks to opine.

Things to watch out for:

  • Items and processes laid out in CONTRIBUTING.md are followed.
  • Twinkle is meant to run on the latest weekly version of MediaWiki as rolled out every Thursday on the English Wikipedia. Backwards compatibility is not guaranteed.
  • The goal is for Twinkle and Morebits to support the same browsers for which MediaWiki provides Grade A support. The Twinkle gadget on enwiki is configured so that we can use up to JavaScript version ES6. However, due to the MediaWiki minifier, we must not use keywords from ES2016 or later, such as async/await and RegEx /s flag. New functions from ES2016 or later, such as Array.includes() should be okay since these will not break the minifier.
  • Certain positional jQuery selectors like :first, :last, and :eq were deprecated in jQuery version 3.4.0 and should probably not be reintroduced. Instead, use methods like .first(), .last(), or .eq().

Updating scripts on Wikipedia

There are two ways to upload Twinkle scripts to Wikipedia or another destination. You can do it with a Perl script (recommended) or manually.

After the files are synced, ensure that MediaWiki:Gadgets-definition contains the gadget definition found in gadget.txt (sync.pl will report its status). In addition to the Twinkle definition, the gadget installs the morebits library as a hidden gadget, making it efficiently available for other tools to use. Twinkle-pagestyles is a hidden peer gadget of Twinkle. Before Twinkle has loaded, it adds space where the TW menu would go in the Vector skin, so that the top bar does not "jump".

select2 is also uploaded as a hidden gadget for better menus and to take advantage of the Resource Loader over the Toolforge CDN; it is done so under the MIT license. Loading via the ResourceLoader causes it to register as a nodejs/commonjs environment with module.exports, so a slight tweak has been made, eliminating that check. Ideally, this will be handled differently (see external libraries and T108655. As such, be careful when updating select2 from upstream.

Manual synchronization

Each Twinkle module and dependency lives on the wiki as a separate file. The list of modules and what pages they should be on are as follows:

Synchronization using sync.pl

There is a synchronization script called sync.pl, which can be used to deploy updates to on-wiki gadgets, or update the repository based on on-wiki changes. For full details, run perl sync.pl --help.

The program depends on a few Perl modules, namely MediaWiki::API, Git::Repository, File::Slurper, and Config::General. These can be installed easily using App::cpanminus:

cpanm install MediaWiki::API Git::Repository File::Slurper Config::General

You may prefer to install them through your operating system's packaing tool (e.g. apt-get install libconfig-general-perl) although you can install them through cpanm too.

When running the program, you can enter your credentials on the command line using the --username and --password parameters, but it is recommended to save them in a .twinklerc file, either in this directory or in your ~ home, using the following format (also the defaults):

username = username
password = password
mode     = deploy|push|pull
lang     = en
family   = wikipedia
url      =
base     = User:AzaToth/

username, password, and mode (one of deploy, push, or pull) are required, either through the command line or configuration file; lang and family default to en.wikipedia. Note that your working directory must be clean; if not, either stash or commit your changes. The script automatically handles the directory (e.g. modules/) from the file path when downloading/uploading. It can be run from any subdirectory of the repository.

Using the deploy mode, interface-admins can deploy Twinkle files live to their MediaWiki:Gadget locations. You will need to set up a bot password at Special:BotPasswords.

sync.pl --mode=deploy twinkle.js morebits.js ...

If no files are provided, it will just report the status of the gadget. You may also deploy all files via

sync.pl --mode=deploy --all

Note that for syncing to a non-Enwiki project, you will also need to specify the --lang and/or --family parameters. For instance, to sync the files with fr.wikiquote.org you should specify --lang=fr --family=wikiquote, such as

sync.pl --mode=deploy --lang=fr --family=wikiquote --all

When deploying or pushing, the script will attempt to parse the latest on-wiki edit summary for the commit of the last update, and will use that to create an edit summary using the changes committed since then. If it cannot find anything that looks like a commit hash, it will give you the most recent commits for each file and prompt you to enter an edit summary manually.

To pull user Foobar's changes (i.e. User:Foobar/morebits.js) down from the wiki, do:

sync.pl --base User:Foobar/ --mode=pull twinkle.js morebits.js ...

To push your changes to user Foobar's wiki page, do:

sync.pl --base User:Foobar/ --mode=push twinkle.js morebits.js ...

The --base flag operates as a prefix; note the presence of the trailing /.

Work instruction

If you are an interface admin on English Wikipedia and you want to deploy Twinkle's master branch, and you aren't interested in sync.pl's fancy options, here's a simple work instruction. Don't forget to change the username and password.

Microsoft Windows:

First time:
- download and install strawberry perl. https://strawberryperl.com/
- open powershell
- `cd` to your twinkle/scripts directory
- `cpanm install MediaWiki::API File::Slurper Config::General`
- `cpanm install Git::Repository --force`
- create a bot password at [[Special:BotPasswords]] with the following permissions: edit existing pages; edit the mediawiki namespace and sitewide/user json; edit sitewide and user css/js; create, edit and move pages
- create a file called .twinklerc in the root directory. populate it with the following data

username = yourUsernameHere (as provided by Special:BotPasswords, should have @ in it)
password = yourPasswordHere
mode     = deploy
lang     = en
family   = wikipedia
url      =
base     = MediaWiki:Gadget-

Every time:
- `cd` to your twinkle directory
- `git checkout master`
- In your browser, go to GitHub, go to your Twinkle fork, and check if it says it is out of date. If so, click "Sync fork"
- `git pull`
- `cd scripts`
- `perl sync.pl --mode=deploy --all`
- it'll ask yes/no. type y
- if it prompts you for any edit summaries, just hit enter to skip
- there will be lots of "Warning: unable to close filehandle" messages, and some other problems such as displaying ←[0m←[96m for line breaks. you can ignore these. shouldn't be a problem.

Dependencies

All the dependencies that Twinkle uses are JavaScript dev dependencies. They are not used at all on-wiki and are just used during development. Here's what they are and what they do.

  • eslint - Used by continuous integration for enforcing code linting rules.
  • jest - Used by continuous integration for unit testing.
  • jest-environment-jsdom - Needed for Jest to work.
  • mock-mediawiki - Used by continuous integration for unit testing.
  • mwn - Used when you run npm start. npm start is what enables localhost testing.

When updating dependencies, CI should take care of testing most of that. Manually testing npm start should be the only additional check needed.