API:Client code/Evaluations/MediaWiki-Butt

MediaWiki::Butt is a Ruby library for accessing the MediaWiki API. It provides a basic, powerful, feature-rich framework for querying and editing wiki content, as well as administration tasks like updating user rights.

= In-depth evaluation =

Easy to install
There are instructions in the project's README file which detail how to install the library locally through Gemfile as well as RubyGems.
 * Installation instructions are correct and easy to find


 * Library is packaged for installation through appropriate package library (rubygems)


 * Platinum standard: library is packaged for and made available through Linux distributions

Easy to understand
There are both high-level and low-level methods for users of different skill levels. Methods for most APIs are available, as well as a public  method in which the user can provide method parameters, headers, and set the return type of either JSON or raw HTTP response. Does not make any Wikibase functions available, even at the level of wrapping custom API calls. The methods provided can be used on the Wikidata API endpoint, however.
 * Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies
 * Platinum standard: makes the Wikidata API available
 * Well documented:
 * Code is commented and readable
 * YARD comments are present and useful. Different files are easily identifiable for different purposes.


 * Documentation is comprehensive, accurate, and easy to find
 * The RubyDoc is not the suggested documentation source, but is still linked to in the README. The GitHub Wiki is suggested in the README, but can be outdated/inaccurate at times.


 * Deprecated functions are clearly marked as such
 * n/a


 * Platinum standard: Documentation is understandable by a novice programmer
 * Documentation is very entry-level and often uses terms described in the actual MediaWiki API.


 * Code uses idioms appropriate to the language the library is written in

Easy to use
Project wiki has brief example code snippets for each method. This can be somewhat redundant and outdated.
 * Has functioning, simple, and well-written code samples for common tasks
 * Demonstrates edits
 * There are code samples to demonstrate the use of various methods that can be used to assist in editing, but there is no full guide for editing.


 * Handles API complications or idiosyncrasies so the user doesn't have to:
 * Login/logout


 * Cookies


 * Tokens


 * Query continuations


 * Requests via https, including certificate validation
 * Uses SSL by default, but users can choose to opt out of SSL usage in the initialization.


 * Courteous API usage is promoted through code samples and smart defaults


 * Examples show how to create and use a meaningful and unique user-agent header (as in https://meta.wikimedia.org/wiki/User-agent_policy)
 * User-Agents are configurable as of version 0.8.0. They default to "NotLoggedIn/MediaWiki::Butt", or, if logged in, that same agent with the username in place of "NotLoggedIn".


 * Platinum standard: generates a unique user-agent string given name/email address/repository location


 * Efficient usage of API calls
 * The overall structure of MediaWiki::Butt is an API wrapper with individually wrapped helper methods for common API calls. However, metainformation APIs are supported through more efficient API calls.


 * Uses JSON

Requires Ruby 2.1 or newer, promoting up-to-date language versions.
 * Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)

Easy to debug
There are unit tests for the util methods that do not access the API, but not for the most frequently modified and used functions, or the API wrapper methods.
 * Contains unit tests for the longest and most frequently modified functions in the library
 * Platinum standard: Unit tests for many code paths exist and are maintained

There are no hacks or extreme cleverness.
 * Terrible hacks/instances of extreme cleverness are clearly marked as such in comments
 * Documentation links to the relevant section/subpage of the API documentation

Easy to improve
MediaWiki::Butt is in semi-active development, so new features are likely to be added on request. Pull requests and bug reports are welcome.
 * Library maintainers are responsive and courteous, and foster a thoughtful and inclusive community of developers and users


 * Platinum standard: Project sets clear expectations for conduct for spaces where project-related interactions occur (mailing list, IRC, repository, issue tracker). It should:
 * State desired attitudes and behaviors
 * Provide examples of unwelcome and harassing behavior
 * Specify how these expectations will be enforced


 * Pull requests are either accepted or rejected with reason within 3 weeks (Platinum standard: 3 business days)


 * Issues/bugs are responded to in some manner within 3 weeks (Platinum standard: 3 business days) (but not necessarily fixed)

The library uses an actual wiki on Gamepedia as its sandbox for testing features and fixes, so the interface only supports versions of the API as new as Gamepedia supports.
 * The library is updated and a new version is released within 3 weeks (Platinum standard: 3 business days) when breaking changes are made to the API
 * Platinum standard: library maintainers contact MediaWiki API maintainers with feedback on the API's design and function


 * Library specifies the license it is released under

= Suggested TODOs =
 * Code-related
 * Allow for more efficient API calls, such as listing multiple titles with |.
 * Expand API support to various common extensions (in progress).
 * Use unit tests


 * Process-related
 * Creating guides for basic use cases.
 * Keep documentation up to date with the library.
 * Test with latest API versions.