Skip to content
Snippets Groups Projects
MusikAnimal's avatar
MusikAnimal authored
Also ensure the project list is expanded if there's a value for the
"It's something else" field.

A FIXME is left to figure how to do a proper sleep() in the code. We
don't seem to be able to do this with the standard wdio packages that
we're currently using.
b3db5a57

Wishlist Intake

A gadget for intake and editing of Wishlist proposals.

Contributing

For Node dependencies, you can use:

  • Fresh docker container (recommended)
    • Using Fresh will ensure your Node and NPM dependencies are the same as the CI environment and other contributors.
    • However, the local server and deploy scripts currently can't be used inside of Fresh (yet).
  • Node of the version specified by .nvmrc

MediaWiki requirements

To fully test the Community Wishlist experience on a local MediaWiki installation, you'll need the following extensions installed:

You'll also want to enable InstantCommons by adding $wgUseInstantCommons = true; to your LocalSettings.php.

Quickstart

  1. npm install to install dependencies
  2. npm run setup to deploy the gadget and survey templates on the configured wiki (see the Deployment section below for more)
    • If you want to start with a clean slate, you can run npm run setup:nuke to delete all the pages created by the setup script.
    • You can use npm run setup:demo to deploy dummy data for testing.
    • Run npm run setup:user-group-css to deploy the user group CSS (the normal setup script will complain if this needs to run).
    • The setup script will tell you if you need to update the MediaWiki:Gadgets-definition page.
  3. npm run server to start a development server (can't be used in Fresh)
  4. npm run watch to watch for changes and rebuild

On-wiki tasks (only need to be done once):

Next we need to load the dev build from the wiki. For development, it's recommended to use your local MediaWiki installation. This way you can create proposals without needing to have the test pages deleted by volunteer admins.

On your local wiki, add the following to Special:MyPage/common.js:

// Use the gadget if it's enabled, otherwise load the development build.
if ( mw.loader.getState( 'ext.gadget.WishlistIntake' ) !== 'loaded' ) {
	mw.loader.load( 'http://localhost:5501/dist/WishlistIntake.js' );
	mw.loader.load( 'http://localhost:5501/dist/WishlistManager.js' );
}

The user entrypoint is at Community_Wishlist which serves as the dashboard. The intake form can be found at Community_Wishlist/Intake, and existing wishes can be edited using the "Edit with form" tab.

Before committing, be sure to run npm run build to create a production build.

Testing

  • npm test to run linting and unit tests
  • npm run fix to automatically fix linting issues and re-run tests
  • npm run selenium-test to run Selenium tests (see below).

Selenium tests

To run the Selenium tests, you'll need credentials for an admin account on a local MediaWiki installation. See mediawiki.org for general information on running Selenium tests against MediaWiki.

The credentials for this repo's Selenium tests can be passed in with the same MW_ and MEDIAWIKI_ environment variables you use for local wiki, or in an object called test in config/credentials.json:

{

	"test": {
		"server": "http://localhost:8080",
		"scriptPath": "/w",
		"username": "my admin username",
		"password": "my admin password"
	}
}

The Selenium test will create actual pages on the wiki, so you should only run this on a local MediaWiki installation. username should be an admin account. Note that the username and password for test are not BotPasswords like they are for other credentials in this file.

Once you have credentials, run the Selenium tests with npm run selenium-test. Any pages created should be deleted after the tests are run.

Localization

While this remains a gadget, and Message Bundles are still in development, we use a system of a translatable wikitext-based JSON page to utilize the Translate extension.

To add a new message:

  • Add the message to messages block in config/config.json
  • Run npm run setup:i18n to update the message page in the code repository.
  • Run npm run deploy again to update the message page on the wiki.

Other messages such as the localized project names (i.e. "Wikipedia"), we use existing messages from the WikimediaMessages extension. These are specified in config/config.json in the importedMessages block.

Deployment

You must have interface-admin and sysop rights to use the deployment script.

  1. On your local, login as an admin and add "Interface administrator" for your account at Special:UserRights.

  2. Visit Special:BotPasswords to create a bot password with the following grants:

    For all environments:

    • "High-volume (bot) access"
    • "Edit existing pages"
    • "Edit protected pages"
    • "Edit the MediaWiki namespace and sitewide/user JSON"
    • "Edit sitewide and user CSS/JS"
    • "Create, edit, and move pages"

    For local and testing credentials only:

    • "Delete pages, revisions, and log entries"
  3. After obtaining the credentials, run cp config/credentials.json.dist config/credentials.json and change the details accordingly:

{
	"local": {
		"apiUrl": "http://localhost:8080/w/api.php",
		"username": "Exampleuser@somedescription",
		"password": "mybotpassword1234567890123456789"
	},
	"test": {

	}
}

local is just an arbitrary name given to this set of credentials. You can add more credentials, for example staging for a staging wiki, and use --credentials=staging to deploy to that wiki as with npm run deploy -- --credentials=staging. If the --credentials flag is not provided, it defaults to the first set of credentials.

test is a special set of credentials used by the Selenium tests. See the Selenium tests section for more. If you're not running the Selenium tests (which are only ran loclaly), you can ignore or remove the test credentials.

For production deployments, you may want to provide a custom edit summary, as with npm run deploy -- "[edit summary]". The edit summary is transformed to include the version number and git SHA, e.g. "v5.5.5 at abcd1234: [edit summary]". If an edit summary isn't provided, the latest commit message is used.

The deployment script may have further instructions if the gadget has not yet been fully installed on the wiki or other actions are needed.

Index page updates

A bot is responsible for looping through all wishes and maintaining the index pages. It runs on Node.js and shares code with the gadget.

Use npm run update-indexes to run the bot. In production, it will run as a scheduled job on Toolforge.

Templates and page structure

Static templates

The gadget uses a system of templates and modules which are responsible for presentation of data. These only augment the data given to them, and do not fetch data themselves.

Bot-maintained templates

These are updated with each run of npm run update-indexes and are transcluded in other pages as well as i18n messages.

Page structure

These pages can be created with npm run setup, and npm run setup:demo for dummy data.