mwbot-rs

**mwbot-rs**
Repository	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: https://gitlab.wikimedia.org/repos/mwbot-rs

Goals[edit]

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[edit]

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.
mwtimestamp: library for parsing and formatting MediaWiki timestamps
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[edit]

mwapi_errors: Typed errors for all kinds of issues encountered when working with the API and MediaWiki

contrib repository[edit]

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[edit]

June 19: Our Matrix bridge is back! Chat with us in #wikimedia-rust:matrix.org^{chat, logs}. See Tool:bridgebot for details about the new implementation.
June 13: multiple crate releases:
- mwbot 0.7.0-rc.2: Re-add support for older wikis using the Parsoid extension rest.php API, use rvlimit=max in the Revisions generator for better batching, and remove some deprecated functions.
- parsoid 0.10.0-rc.2: remove deprecated function
- wikipedia_prosesize 0.3.0-rc.2: improve Cargo.toml metadata
June 8: mwseaql released, with an update to the MediaWiki database layout and sea-query dependency.
June 6: mwbot 0.7.0-rc.1 released, with new page generators, helpers and dependency updates. The configuration file format has changed, the wiki's URL is now specified in only one place, e.g. wiki_url = "https://wiki.example.org/w/".
June 3: parsoid 0.10.0-rc.1 released, supporting core REST API, deprecating RESTBase support
June 2: many crate releases:
- mwtimestamp 0.1.1: fix serialization and add convenience Timestamp::now() function
- mwtitle 0.2.4: make namespace information public
- mwapi 0.7.0-rc.1: Upgrade reqwest to 0.12, allow using custom HTTP clients and handle HTTP 429 errors
- mwapi_responses 0.5.0-rc1: support list=recentchanges, prop=langlinks and prop=categoryinfo, upgrade to mwapi 0.7.

Older news

Compatibility policy[edit]

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).

MSRV Policy[edit]

This project will define the MSRV (Minimum Supported Rust Version) policy as "the latest rustc as long as the dependency requires it".

Contributing[edit]

Getting started[edit]

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 main 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[edit]

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.

Releases[edit]

New releases are made on an as-needed basis. See /Releasing for instructions on the process.

Contributors[edit]

Discussions[edit]

Project-level discussions can happen on the talk page, or if they're mostly technical, GitLab is fine too. Issue tracking happens on Phabricator. For real-time conversations, join #wikimedia-rust:matrix.org^{chat, logs} or on IRC, #wikimedia-rust ^connect.