Skip to content

Latest commit

 

History

History
97 lines (61 loc) · 8.64 KB

CONTRIBUTING.md

File metadata and controls

97 lines (61 loc) · 8.64 KB
Raw

Contributing to Twinkle

🎉🎉 Thanks for taking the time to contribute! 🎉🎉

There are many ways to help out!

Bug reports and feature requests

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.

Reporting a bug

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.

Contributing a pull request

Getting started

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.

  • Download and install Node.js if you don't have it already (https://nodejs.org/en/download/).
  • Set up your code editor or IDE to work with JavaScript so that you get proper syntax highlightening and code completion.
  • Log in to GitHub, then fork this repository using the "Fork" button at the top right.
  • Clone your fork by typing this into the command line, changing YourGitHubUserName to the correct username: git clone https://github.com/YourGitHubUserName/twinkle.git
  • Create a new branch in git. This will make it easier to have multiple pull requests pending at the same time: git branch your-branch-name
  • Install eslint and other dependencies: npm install while inside Twinkle directory.

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 the changes are to the Morebits library, you can view the full docs at http://wikimedia-gadgets.github.io/twinkle or on the GitHub Wiki. 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.

Testing your code

Manually testing your patch (such as by running Twinkle on localhost using npm start, loading it in your testwiki common.js, then clicking around and testing the module that you modified) is required. Please do not submit untested code. Twinkle has 40,000 users, so it is important to keep bugs out of production.

Once you have made your changes, run npm start. This launches a webserver listening on http://127.0.0.1:5500. So, to load the local version of Twinkle on-wiki, you need to run mw.loader.load('http://127.0.0.1:5500') in your browser console. A more permanent solution would be to add that line in your common.js page, since code entered in the console does not persist on page navigation.

You can also test your code by simply pasting it into the browser console, but that's not recommended.

The Test Wiki is recommended for tests that cause actual edits. However, in some situations where the functionality relies on specific template code or certain wiki-preferences, it may be necessary to test on enwiki itself. You can use the sandboxes, but be aware that some things may not work properly outside the appropriate namespace.

Specifically, the following pages on enwiki may be helpful:

Some things to watch out for:

  • The twinkleconfig pseudo-module holds the code to save and determine user preferences, while twinkle.js holds the defaults.
  • There is some variety in how the individual modules are written, in particular among the friendly family as well as with twinkleconfig.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 worked on, through discussion at Wikipedia talk:Twinkle or a GitHub issue.

Submitting your pull request

When you are ready to submit, make sure you created a new branch, commit your changes, push your changes to your GitHub fork, then initiate a pull request (PR) by visiting one of the GitHub repos and clicking "Compare & pull request" in the message that appears at the top.

The title of your pull request should be the module you are proposing changes to, a colon and a space, 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/.

For quicker and easier reviewing, please consider splitting large pull requests into multiple smaller ones.

If your pull request should close an issue in the issue tracker, don't forget to add text such as Fixes #1682 to the body text of the pull request. This will tell GitHub to close that issue when the pull request is merged.

Style guideline

For consistency and to cut down on potential errors, we follow a 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.

  • Tabs, not spaces
  • Use single quotes for strings, such as: mw.config.get('wgUserName')
  • Spacing: if (condition) {

Expectations of Participants

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.