mwbot-rs

From mediawiki.org

mwbot-rs
Repository GitLab 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]

  • January 23: mwapi_responses 0.4.2 released, fixing deserialization of linterrors continue blocks.
  • December 21: mwapi_responses 0.4.1 released, fixing a bug with finding the mwtimestamp crate in the macro. 0.4.0 was yanked.
  • December 14-15: many crate releases:
    • mwapi 0.6.0: better error handling and reduction of dependencies
    • mwapi_responses 0.4.0: integration with mwapi crate, improved support for a number of API modules
    • mwtitle 0.2.3: provide default MediaWiki namespace constants, addressed clippy errors
    • parsoid 0.9.0: switch to maintained HTML parsing library fork and improve documentation
    • wikipedia_prosesize 0.2.0: add optional serde integration
    • mwbot 0.6.0: add significantly more page generators and improve related infrastructure

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.

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 connect via IRC. (The Matrix bridge is down for now, unfortunately.)