Help:Gadget-Cat-a-lot/Developing
This page describes how to edit, test, and deploy changes to the Cat-a-lot gadget on Wikimedia Commons. There is also separate guide on howto develop code locally and in Beta Commons:
General documentation
Source code
- MediaWiki:Gadget-Cat-a-lot (description)
- MediaWiki:Gadget-Cat-a-lot.js (main JavaScript code)
- MediaWiki:Gadget-Cat-a-lot.css (CSS styles)
- Dependencies
- MediaWiki:Gadget-libAPI.js (Handles parallel editing and throttling)
- MediaWiki:Gadget-SettingsManager.js (settings management)
- MediaWiki:Gadget-SettingsUI.js (settings user interface)
Files and categories suitable for testing
Wikimedia Commons test images. These are test images. Images can also be used for testing actions like moving, deleting etc. License may but does not have to apply. Images in this category may be deleted, moved or other images loaded on top of them.
Under the test images are also Cat-a-lot specific test files
It is also safe to add or remove following categories from files uploaded by FinnaUploadBot if you need to test mass editing. Categories itself are redundant for FinnaUploadBot this currently handled by code.
Setting up the onwiki development environment
Before starting development:
- Disable the production Cat-a-lot gadget in your Wikimedia Commons preferences to prevent conflicts with your development version.
- Create a sandbox copy of the gadget:
- Copy latest
MediaWiki:Gadget-Cat-a-lot.jsto your user pageSpecial:Mypage/cat-a-lot.js- Sample: User:Zache/cat-a-lot.js (Warning: Do not copy this. Please use the latest version as sample version is outdated.)
- Copy latest
MediaWiki:Gadget-Cat-a-lot.cssto your user pageSpecial:Mypage/cat-a-lot.css- Sample: User:Zache/cat-a-lot.css (Warning: Do not copy this. Please use the latest version as sample version is outdated.)
- Modify Cat-a-lot to use your local Cat-a-lot.css page. (example modification)
- Add the loading code to your
common.jsfile (e.g.,Special:Mypage/common.js- Sample: User:Zache/common.js
- Copy latest
Editing the code
Creating a task
- Create a Phabricator ticket using the gadget-cat-a-lot tag to the Cat-a-lot workboard
- Example task phab:T386783
Development best practices
- Make incremental changes to your sandbox version
- Use
console.logfor debugging - Add comprehensive code comments
Testing requirements
- Ensure no console errors or warnings appear
- Verify functionality works as expected
- Cross-browser testing:
- Google Chrome
- Mozilla Firefox
- Safari
- Microsoft Edge
Deploying the changes
Code preparation
- Consolidate changes into clean, focused edits
- Remove all debug messages and temporary notes
- Ensure code is well-commented
- Example: User:Zache/cat-a-lot-edit-libAPI.20241008.js
- Verify final version works as intended
Community review
- Post a message on MediaWiki talk:Gadget-Cat-a-lot.js
- Describe your changes
- Request testing from other users
- Example message: Special:MediaSearch support discussion
- If you need place for drafting message you can use Commons:Sandbox
- Wikicode syntax cheatsheet
Deployment steps
- After testing submit a protected page edit request
- Example request: Cat-a-lot libAPI update request
- For simple changes, you can submit the edit request directly
- Example request: Disable HotCat on Commons in Tabular data namespace
Post-deployment
- Test that new version is working when it is merged to gadget code. There can be differences on how gadgets and user scripts are working because race conditions, security validations etc.
- Monitor for any issues
- Once stable, close the Phabricator ticket as resolved
- Update documentation if necessary