| Repository | .svg.png.webp){kind=icon} mwbot-rs/mwbot |
| Issue tracker | #mwbot-rs |
mwbot-rs is a framework for writing bots and tools in Rust. The aim is to provide the building blocks for people to write safe and concurrent applications that interact with and enhance MediaWiki. The project is still getting started, all contributions are welcome!
Source code and issues: https://gitlab.wikimedia.org/repos/mwbot-rs (move in progress from GitLab.com)
Goals
- Have fun. Seriously, Rust is a fun programming language to work in, and this project should be no exception
- Provide building blocks (independent crates) that let people do what they want
- Embrace and utilize Rust's key features like safety and fearless concurrency
- Encourage best practices by default
- Enable sustainable development of bots and tools
Crates
- mwbot: A framework to build MediaWiki bots with, overall umbrella project
- mwapi: Layer that takes care of interactions with the MediaWiki Action API, like tokens or uploads
- mwapi_responses: Macro to generated typed response structs for dynamic API queries
- mwseaql: MediaWiki SQL table definitions for use with SeaQL's SeaQuery builder.
- mwtitle: library for parsing, normalizing and formatting MediaWiki page titles
- parsoid: Wrapper around Parsoid HTML that provides convenient accessors for processing and manipulation
- toolforge: Small library for common tasks on Wikimedia Toolforge
- wikipedia_prosesize: Measure articles using Wikipedia's "prose size" metric
Obsolete
- mwapi_errors: Typed errors for all kinds of issues encountered when working with the API and MediaWiki
contrib repository
The "contrib" repository contains various bots and scripts that use the mwbot framework by using cargo workspaces. The advantage of adding and maintaining your bots in the contrib repository is to make it easier to follow best practices by having source code published and multiple maintainers with commit access. Of course, you retain full control over where your bot actually runs, and who has access to that. The only requirement is that code must be licensed under an OSI-approved license.
News
- June 24: mwbot 0.5.2 released, making the
generator()function public - May 6: mwbot 0.5.1 released, adding support for section editing
- April 19: mwbot 0.5.0 released
- April 2: mwapi 0.5.0, parsoid 0.8.0, wikipedia_prosesize 0.1.0 released
- March 19: mwapi_responses 0.3.3 released, adding
partialflag forlist=blocks. - March 11: mwapi_responses 0.3.2 released, with support for
list=blocks.
Compatibility policy
Like all other Rust crates, mwbot-rs follows semantic versioning.
The latest stable version will stay compatible with the oldest supported MediaWiki release. Any breaking changes on the MediaWiki side will be fixed in all versions released in the past 3 months, and in versions released within the past year upon request.
Until mwbot reaches a 1.0 stable release, all code in the contrib repository will be updated for you for any breaking changes any mwbot-rs crate. (After 1.0, this contrib policy will be re-evaluated to see if it was successful and should be continued).
Contributing
Getting started
Reach out to one of the project leads (see below) to get developer access to the repository, so you can push your work.
If you aren't already known in wiki communities, you might be asked to submit a few pull requests first before getting access.
We intend to adhere to the wiki way, so feel free to push directly to master like you'd edit a wiki page. If you want review ahead of time for larger changes or aren't sure about something, feel free to start a merge request. Contributors agree to follow the code of conduct for technical spaces.
The list of "good first task!" issues is a good place to get started.
Code guidelines
Code is formatted using whatever rustfmt dictates making it easy for everyone to not have to think about or remember specific styles. Just run cargo fmt before committing and you're good.
We use clippy for linting, run cargo clippy --all-features -- -D warnings and fix any warnings.
Add tests when appropriate, we strive for 90%+ test coverage. CI will automatically update the coverage report (TODO: update link) after each push. Run cargo test --all-features to run all the tests, or cargo test <name> to just run one test. Some tests related to saving pages will be skipped because it requires logging into an account. CI will run those tests for you or you can ask another contributor for the credentials to the mwbot-rs test account.
Breaking changes are inevitable, but try to discuss them first ahead of time so we're not constantly breaking everything.
Contributors
- Legoktm (project lead)
- Enterprisey
- Erutuon
- Subbu
- wctaiwan
- 0xDeadbeef
- MilkyDefer
- Count Count
- Arlolra
- XtexChooser
Discussions
Project-level discussions can happen on the talk page, or if they're mostly technical, GitLab is fine too. Issue tracking happens on GitLab. For real-time conversations, join #wikimedia-rust:libera.chat chat, logs via Matrix or IRC.