Toolhub

Toolhub community logo.svg

Toolhub is a community managed catalog of software tools used in the Wikimedia movement. Technical volunteers can use Toolhub to document the tools that they create or maintain. All Wikimedians can use Toolhub to search for tools to help with their workflows and to create lists of useful tools to share with others.

What is a "tool"?

In Toolhub, "tool" is an inclusive term for software applications which interact with the Wikimedia projects without being fully implemented by MediaWiki. This includes things like user scripts, gadgets, bots, templates, lua modules, web applications, and mobile apps. The catalog is intended to be inclusive rather than exclusive as long as the things it documents are useful for improving workflows and user experiences when interacting with the projects of the Wikimedia movement.

Content license

Toolinfo.json data and other structured data collected in Toolhub is licensed under the Creative Commons CC0 Dedication (CC0). Re-users are encouraged to provide attribution by linking back to Toolhub, but this is not required for license compliance. It is the responsibility of maintainers of externally hosted toolinfo.json data files to ensure that their contributors are aware of the CC0 licensing requirement. Toolinfo data copied from Wikimedia content wikis or other documentation under a non-CC0 license should restrict the copied description content to 50 words/250 characters to limit claims of potential copyright license obligations, like attribution. The word/character limit only applies to copied content, and original CC0 descriptions may be any length.

User accounts

Toolhub uses OAuth authentication to allow users to login to Toolhub using their Wikimedia wiki user account. No new accounts or passwords are needed.

Adding tools to the catalog

Tools can be added to the Toolhub catalog by either being read from a registered toolinfo.json file URL or by directly sending data to the Toolhub API.

Publish a toolinfo file and register it with Toolhub's web crawler

A toolinfo file is a JSON document conforming to the toolinfo schema. This standard is an extension of the toolinfo specification originally developed by Husky as part of his Hay's Directory tool.

  1. Create a JSON file conforming to the schema
  2. Publish that file on a website
  3. Register the URL of the file with Toolhub's web crawler

Toolhub will check each registered toolinfo URL approximately every 60 minutes and update the catalog with changes.

Use the Toolhub user interface to create and edit a toolinfo record

The Add or remove tools > Create a new tool screen in Toolhub can be used to create a new toolinfo record directly in Toolhub's catalog. Additional information not collected in the toolinfo creation form can be added via subsequent edits using the edit tool screen for the tool.

Use the Toolhub API to create and edit a toolinfo record

The POST /api/tools/ endpoint of Toolhub's API can be used to create a new toolinfo record directly in Toolhub's catalog. This API is used behind the scenes by the Toolhub user interface. See Toolhub's API documentation for detailed information about the expected inputs and outputs of this API endpoint.

Searching for tools

The search screen uses the Elasticsearch simple query string syntax:

  • + signifies AND operation
  • | signifies OR operation
  • - negates a single token
  • " wraps a number of tokens to signify a phrase for searching
  • * at the end of a term signifies a prefix query
  • ( and ) signify precedence
  • ~N after a word signifies edit distance (fuzziness)
  • ~N after a phrase signifies slop amount
  • Special characters (+, |, -, ", *, (, ), and ~) must be escaped with \ or in a quoted phrase to be searched for
  • Searches are case insensitive

Create and share lists of tools

The Your lists screen can be found from the link in the user menu available to logged in users. Click on the user icon in the top navigation bar next to the language selector to open the user menu. Here you can create and edit lists of tools and, when you are ready, mark them as public to share with others. Public lists can also be marked as featured lists by administrators which will allow them to be shown on the Toolhub landing page.

Lists can be shared by copying the URL of the list from your browser's URL bar or clicking the Copy link and share with others link on the list's detail screen.

The lists feature in Toolhub 1.0 is functional, but not yet as full featured as we would like. Look for new features for lists in the future like searching all public lists and viewing the revision history of a list.

User permission levels

Anonymous users

All read-only actions can be used without authenticating to Toolhub.

Users

Authenticated users can perform all read-only actions in the same way that anonymous users can. Additionally they can create new toolinfo records, edit toolinfo records that they have previously created, create new lists, and edit lists that they have previously created.

Bureaucrats

Bureaucrats can change permissions for other users, including themselves. This includes both granting and removing permissions.

Patrollers

Patrollers are able to review edits to any toolinfo records and either mark them as patrolled or leave them unpatrolled. There is currently no way for a patroller to reject an edit.

Oversighters

Oversighters are able to hide (oversight/suppress) any edit. Edits which have been previously hidden can be revealed. Oversighters are also able to edit toolinfo records and lists created by other users so that they can revert a change or make a new edit in order to remove problem content.

Administrators

Administrators have all of the abilities of bureaucrats, patrollers, and oversighters.

Patrolling changes

Patrollers and administrators can patrol changes. Patrolling rights are granted by bureaucrats or administrators.

When a change is made to a toolinfo record, it can be patrolled from two places:

  • From the page history: click on the option "Mark as patrolled" on the logged entry
  • From a link to the change itself: click the "Mark as patrolled" link in the change summary information at the top of the page.

Changes can only be accepted (patrolled) or left alone. They cannot be rejected or declined.

Changing user permissions

Administrators and bureaucrats can change permissions for themselves and other users. Permissions can be added or removed. Each individual addition or removal of permission will show in the audit logs. This means that if two permissions are changed there will be two audit log entries, one for each permission.

To add a permission

  • Go to the "Members" screen.
  • Select the user to modify. Use the search filters to find the user.
  • Click on the pencil icon after the user's name. A dialog will be displayed showing the current permissions of the user.
  • Choose the group to add from the dropdown list.
  • Click the "Add" button.
  • A notice will appear on the screen noting that the change has been successful.

To remove a permission

  • Go to the "Members" screen.
  • Select the user to modify. Use the search filters to find the user.
  • Click on the pencil icon after the user's name. A dialog will be displayed showing the current permissions of the user.
  • Identify the permission to be removed. Click on the red trash can button to remove the permission.
  • A notice will appear on the screen noting that the change has been successful.

Oversighting

Oversighting allows hiding an individual edit to a toolinfo record. This might be used for example when a user has mistakenly published their private information. Administrators and oversighters have the permissions needed to hide or reveal an edit.

Revisions that have been oversighted will have the date/time of the revision, the user's name, and the edit summary hidden in the toolinfo record's history view. All oversight actions are recorded in the audit log, including the name of the oversighter.

To hide a revision

  • Identify the content to be hidden.
  • Review the history to identify when that content was first added.
  • Ensure that the content to be hidden is no longer visible in the toolinfo record
    • If it is still visible, the toolinfo record owner, an administrator, or an oversighter can edit the toolinfo record to remove the problem content.
  • From the toolinfo record history, identify all changes that need to be oversighted.
  • Click the "hide" link to hide a revision.
  • Repeat as required to oversight all relevant edits.

To show a hidden revision

  • From the toolinfo record history, identify all changes that need to be revealed.
  • Click the "reveal" link to show a revision.
  • Repeat as required to reveal all relevant edits.