Skip to content

Latest commit

 

History

History
141 lines (109 loc) · 11.7 KB

DEVELOPER.md

File metadata and controls

141 lines (109 loc) · 11.7 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, except IE 11. 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:Xiplus/

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 zh.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 /.