🎉🎉 Thanks for taking the time to contribute! 🎉🎉
There are many ways to help out!
If you think you've found a bug or have a great idea for a new feature, great! You can open a new GitHub issue here (GitHub account required) or report it at Wikipedia talk:Twinkle. Bigger changes or more complicated requests should be made on-wiki so other users can take part in the discussion of your feature proposal. If you're unsure if something is a bug, other editors may be able to help identify the issue. Be sure to search the talk page archives and GitHub issues to see if your request has already been discussed in the past.
Whatever the case, the more detailed your description the easier it will be to respond to your report or request.
A good bug report will include:
- A brief, descriptive title that mentions the module you were using (tag, CSD, xfd, etc.).
- The steps leading up to the issue so we can replicate it. This should include the page and revision you were on, the action you were performing, and the options you selected.
- Any errors or messages that Twinkle reported an error when it got stuck.
- What you think should have happened.
- Anything you can find in your browser's console window.
If you believe you have found a security issue, follow the guidelines in SECURITY.md.
If you'd like to help with Twinkle's development, wonderful! Anyone can contribute, and it's easy to get set up to do so.
First, familiarize yourself with the code; most likely, the changes you want are to one of the modules; you can also check out the individual Gadget pages onwiki. If you want to propose changes yourself, fork the repository to make sure you always have the latest versions. If you're new to GitHub or Git in general, you probably want to read Getting started with GitHub first.
Once you've got a local fork up and running, commit your changes!
Testing Twinkle can be tricky, but thankfully we've made it easy with a helper script, patch-test.js. Simply run npm run patchtest in your terminal, which will generate the patch-test-loader.js file. Then, run a localhost server (e.g. php -S 127.0.0.1:5500 or python -m SimpleHTTPServer 5500) and paste the contents of patch-test-loader.js in your browser's console window. You should be all set! If you put mw.loader.getScript('http://127.0.0.1:5500/dev/patch-test-loader.js'); in your common.js page, you won't even need to paste anything once you run the server! You can also test your code by simply pasting it into the browser console, although that's not recommended.
Some things to watch out for:
- If your tests have any chance of making actual edits, consider making them in a sandbox; be aware that some things may not work properly outside the appropriate namespace. An even better place to test is on the test wiki! Some parts of Twinkle rely on specific template code or on certain wiki-preferences, so testing certain things outside of enWiki may be difficlut (e.g., pending changes).
- The non-module scripts
morebits.jsandtwinkle.jscan be more complicated to test. - The
twinkleconfigpseudo-module holds the code to save and determine user preferences, whiletwinkle.jsholds the defaults. - There is some variety in how the individual modules are written, in particular among the
friendlyfamily as well as withtwinkleconfig.js.
As Twinkle is used many thousands of times a day, changes to how Twinkle works may be confusing or disruptive to editors. Significant or major changes to workflow, design, or functionality should gain some modicum of consensus before being proposed or suggested, either through discussion at Wikipedia talk:Twinkle or elsewhere.
When you are ready to submit, commit your changes on a new branch, then initiate a pull request (PR). The title of your pull request should be the module you are proposing changes to, followed by a brief but descriptive explanation of what the changes do, such as:
xfd: Prevent sysops from deleting the main page
The usual rule of thumb is that a good subject line will complete the sentence "If applied, this commit will..." The full commit message is a good place to explain further details, both for reviewers and anyone in the future, specifically focusing on why the changes are being made, not how. There are many guides to writing good commit messages, one particularly helpful one is by @cbeams: https://chris.beams.io/posts/git-commit/
If you made multiple commits while working on the same feature, it's a good idea to squash and rebase your commits before submitting your PR; a good policy is that every commit should be capable of replacing the live on-wiki Gadget file for all users. Separate ideas or enhancements should be different commits, and entirely separate concepts should be different pull requests. For example, if you made three commits while changing the pulldown options in twinkleprotect.js and twinklebatchprotect.js, those should be squashed into one commit, but if you also disabled loading twinklespeedy.js and twinklexfd.js on the mainpage, that should be a separate pull request. See also how to file a bug report or feature request.
For consistency and to cut down on potential errors, we've recently decided to utilize a more coherent style throughout the code. eslint can be used to check your code before submission and even repair many common issues. To install via npm, just run npm install from the main Twinkle directory in your terminal. You can then freely check your code by running npm run lint, and if you run npm run lint:fix then eslint will clean up some (but not all!) style differences. More information on specific style rules can be seen in issue #500 and in .eslintrc.json, but the best advice is to just follow the style of surrounding code! Some specific examples and deviations are elucidated below.
- Quotes: Single quotes should be used around strings, such as when using
mw.config.get('wgUserName') - Spacing:
if (condition) { - Each: The
array.forEach(function(item) {method is preferable to$.each(array, function(index, item) {
Everyone is welcome and encouraged to join in, regardless of experience. Anybody submitting issues, code, reviews, or comments to the repository is expected to do so while complying with the principles of Wikimedia's Code of Conduct for technical spaces.