XTools/Development

Thanks for contributing to XTools! This guide gives a high-level walkthrough of everything you need to contribute to XTools in a local environment.

Prerequisites

 * PHP 7.4 along with the extensions specified in composer.json (you will be notified of which extensions during the installation process)
 * Composer
 * Node with the version specified by the .nvmrc file
 * A Wikimedia developer account
 * Access to Toolforge (this is so that you can connect to the Toolforge wiki replicas)

Running a development server

 * Clone the repository:
 * Run  and answer all the prompts. See /Configuration for documentation on each config parameter.
 * If you're working on JavaScript or CSS, compile assets with
 * Before submitting your pull request, be sure to use  instead of   and without the watch flag.
 * Launch Symfony's built-in server:
 * Assuming the configuration was done correctly and as desired, you should be up and running at http://localhost:8000

The Simple Counter is the simplest tool and should work as soon as you set up XTools. Test it by going to http://localhost:8000/sc and put in  as the Username and   as the wiki. After submitting you should quickly get results.

The development server does not cache application or session data; any changes you make are visible after refreshing the page. However when you modify things in  or otherwise aren't seeing changes you're making, you may need to clear the cache with.

Assets are generated with Symfony Encore.

The logs are in. If things are acting up unexpectedly, you might try clearing the cache or restarting the server.

Developing against Toolforge replicas
First make sure you have a Wikimedia developer account and access to Toolforge. Then you can set up the necessary tunnels and a shell session with: Replace  with your Toolforge Unix shell username. Note our tunnel has to connect to each database slice. The ports used here should match up with the corresponding options in your, like so: Change the   bits to your own values, which you can find in your   file in the home directory of your account on Toolforge.

Caching
XTools should probably take advantage of Doctrine's built-in caching mechanism, but it doesn't. Instead it is done in a somewhat manual fashion. This is only done in  classes, using this pattern: The cache key can be anything, so long as it is unique to the specific method. A third parameter can be passed to  to set the TTL, using the same syntax from the DateInterval class (e.g.   is one day,   is one hour).

The above methods are just wrappers around a PSR-6 implementation, intended to reduce the repetition of similar lines of code.

Style guidelines

 * It's called "XTools", with two capital letters.
 * XTools conforms to PSR2 and Slevomat coding standards; use  to check your code.
 * HTML routes must begin with the tool name, i.e., while API routes begin with either Project, User, or Page.
 * Version numbers follow Semantic Versioning guidelines.

Tests
Tests are located in the  directory, and match the   directory structure. They are built with PHPUnit. Repositories only handle fetching data and do not need to be tested. Controllers also interact with the database, and while tests are most welcomed for these, they will not run on the CI server (GitHub Actions or Scrutinizer) due to limitations. Instead, put all things that query the replicas behind a  check (example).

There are also tests for linting, phpDoc blocks, and file permissions.

Use  to run the full suite, or   to run just the unit tests.

Releases
Releases are made by tagging commits in the master branch. Before tagging a new release:


 * Update the version number in
 * Check the copyright year in
 * Update  with any notable new information for the end user.

Then tag the release (follow the Semantic Versioning guidelines, and annotate the tag with the above release notes) and push it to GitHub.

Lastly, update the  and   parameters at XTools.

Additional help

 * Email:  @
 * IRC: #wikimedia-xtools (Direct link – Requires an IRC client)
 * MediaWiki talk page: Talk:XTools