Skip to content

Latest commit

 

History

History
136 lines (102 loc) · 10.4 KB

DEVELOPER.md

File metadata and controls

136 lines (102 loc) · 10.4 KB
Raw

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 that MediaWiki supports. In particular, collaborators should look out for unsupported additions from ES6 (aka ES2015); .includes and .find are among the most likely to show up, although the jQuery $.find() is fine.
  • 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 following lines:

* Twinkle[ResourceLoader|dependencies=mediawiki.notify,jquery.chosen,moment,ext.gadget.morebits|rights=autoconfirmed|type=general|peers=Twinkle-pagestyles]|Twinkle.js|twinkleprod.js|twinkleimage.js|twinklebatchundelete.js|twinklewarn.js|twinklespeedy.js|friendlyshared.js|twinklediff.js|twinkleunlink.js|friendlytag.js|twinkledeprod.js|friendlywelcome.js|twinklexfd.js|twinklebatchdelete.js|twinklebatchprotect.js|twinkleconfig.js|twinklefluff.js|twinkleprotect.js|twinklearv.js|twinkleblock.js|friendlytalkback.js|Twinkle.css
* morebits[ResourceLoader|dependencies=mediawiki.user,mediawiki.util,jquery.ui,jquery.tipsy|hidden]|morebits.js|morebits.css
* Twinkle-pagestyles[hidden|skins=vector]|Twinkle-pagestyles.css

This loads 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".

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 update on-wiki gadgets, or update the repository based on on-wiki changes.

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

cpanm --sudo install MediaWiki::API Git::Repository File::Slurper Getopt::Long::Descriptive

You may prefer to install them through your operating system's packaing tool (e.g. apt-get install libgetopt-long-descriptive-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 file called ~/.twinklerc using the following format:

username = username
password = password
lang     = en
family   = wikipedia
base     = User:Username

where base is the wiki path to prefix the files for pull and push. The script ignores the modules/ part of the file path when downloading/uploading.

Note that your working directory must be clean; if not, either stash or commit your changes.

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

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

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

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

Deploying to the sitewide gadget

There is also a deploy command for interface-admins to deploy Twinkle files live to their MediaWiki:Gadget locations. You will need to set up a bot password at Special:BotPasswords.

./sync.pl --deploy twinkle.js morebits.js ...

You may also deploy all files via

make deploy

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 test.wmflabs.org you should specify --lang=test --family=wmflabs. If you intend to use make deploy to deploy all the files at once, you may also need to pass the necessary parameters through the makefile to the sync script like this example:

make ARGS="--lang=test --family=wmflabs" deploy

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.