mwbot-rs

From mediawiki.org
Jump to navigation Jump to search

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.com/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_errors: Typed errors for all kinds of issues encountered when working with the API and MediaWiki
  • mwapi_responses: Macro to generated typed response structs for dynamic API queries
  • mwtitle: library for parsing, normalizing and formatting MediaWiki page titles
  • parsoid: Wrapper around Parsoid HTML that provides convenient accessors for processing and manipulation

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 6: mwtitle 0.2.0-alpha.1, mwapi_errors 0.2.0-alpha.2, mwbot 0.4.0-alpha.2 released
  • January 4: mwapi_errors 0.2.0-alpha.1, mwapi_responses 0.3.0-alpha.2, mwapi 0.4.0-alpha.2, parsoid 0.7.0-alpha.3 released


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

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 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[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. Add tests when appropriate, we strive for 90%+ test coverage. CI will automatically update the coverage report after each push.

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 GitLab. For real-time conversations, join #wikimedia-rust:libera.chat chat, logs via Matrix or IRC.