Extension:Produnto

**MediaWiki extensions manual**
Produnto; Release status: experimental
Implementation	Parser extension, MyWiki
Description	Package manager for Scribunto modules and gadgets.
Author(s)	Tim Starlingtalk
MediaWiki	>= 1.45.0
Database changes	Yes
Virtual domain	virtual-produnto
	Tables produnto_active_deployment; ; produnto_deployment; ; produnto_deployment_data; ; produnto_package_deployment; ; produnto_package_version; ; produnto_package; ; produnto_file; ; produnto_file_name; ; produnto_file_text;
	Parameters $wgProduntoPackagesTitle; $wgProduntoServers;
	Hooks used ContentHandlerDefaultModelFor; JsonValidateSave; LoadExtensionSchemaUpdates; PageSaveComplete;
Licence	GNU General Public License 2.0 or later
Download	Download extension ; Git [?]: Browse repository (GitHub); Gerrit code review; Git commit log; Download source tarball;
Help	Help:Extension:Produnto
Issues	Open tasks · Report a bug

The Produnto extension is a package manager for Scribunto and Gadgets extensions. It allows defining Lua modules whose code is stored in an external code repository (e.g. Git repository) that can be imported from other modules on the wiki. This allows for easier code sharing across multiple wikis of a wiki farm.

This extension is currently under heavy development and not all described features may be working as intended. See T421436 for the deployment tracking task.

Installation

Install the zip extension for PHP.
Download and place the file(s) in a directory called Produnto in your extensions/ folder.
Add the following code at the bottom of your LocalSettings.php file:
```
wfLoadExtension( 'Produnto' );
```
Run the update script which will automatically create the necessary database tables that this extension needs.
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

Produnto configuration settings
Parameter	Default	Comment
`$wgProduntoServers`	`[]`	An array of server configuration objects describing upstream package sources.
`$wgProduntoPackagesTitle`	`null`	The title to use for the deployed package list, or `null` for `MediaWiki:Packages.json`.

Server

Server configuration consists of objects with a required 'type' property, and the rest depending on the selected server type. The following server types are currently supported:

gitlab

GitLab

To have GitLab properly update packages in Produnto's tables, a webhook to {$wgRestPath}/produnto/v1/gitlab/tag must be set up on the repository.

GitLab server configuration properties
Property	Default	Comment
`'url'`	-	Required. The base URL of the GitLab installation.
`'projectPrefixes'`	-	An array of strings specifying allowable project path prefixes.
`'proxy'`	`null`	The HTTP proxy to use to contact GitLab.
`'maxFileSize'`	`10 * 1024 * 1024` (10 MiB)	The maximum size of each file in a package in bytes.

For example, this configuration allows any repository under lua-modules on Wikimedia's GitLab to be used for Produnto packages:

$wgProduntoServers = [
    [
        'type' => 'gitlab',
        'url' => 'https://gitlab.wikimedia.org',
        'projectPrefixes' => [ 'lua-modules' ],
    ],
];

Usage

Definition

Each Produnto package repository has to contain a produnto.json file in its root, which acts as a manifest for the package, akin to extension.json.

`produnto.json` properties
Property	Type	Description
`type`	`"scribunto"`	The type of the package.
`name`	Language code to name map	Localized package name.
`description`	Language code to description map	A short localized description of the package.
`author`	String, or array of strings	The package's authors.
`license`	String	SPDX identifier for the license under which the package is released.
`url`	String	Optional homepage for the package. Use `collab-url` and `doc-url` if there is no separate homepage.
`collab-url`	String	Optional human-readable entry point for source code contributions, such as a GitLab project page.
`doc-url`	String	URL to the package's documentation page.
`issue-url`	String	URL to the package's issue tracker.
`requires`	Package name to required version map	Versions of other Produnto packages that this package requires. Special keys `MediaWiki` and `Lua` can be used to define required versions of MediaWiki and Lua.
`modules`	Lua module name to file name map	Global Lua module name map to the defining file path, relative to the package root.

For example, a package manifest could look like:

{
    "type": "scribunto",
    "name": {
        "en": "yesno"
    },
    "description": {
        "en": "This module provides a consistent interface for processing boolean or boolean-style string input."
    },
    "author": [
        "ATDT",
        "Mr. Stradivarius"
    ],
    "license": "CC-BY-SA-3.0",
    "collab-url": "https://gitlab.wikimedia.org/lua-modules/yesno",
    "doc-url": "https://www.mediawiki.org/wiki/Yesno",
    "issue-url": "https://phabricator.wikimedia.org/project/view/1111/",
    "requires": {
        "MediaWiki": ">= 1.28",
        "dep1": "1.2.3"
    },
    "modules": {
        "yesno": "src/yesno.lua"
    }
}

A JSON schema of available properties is available at docs/package.schema.json.

Deployment

To deploy a package to an individual wiki, an interface admin has to edit the page defined by $wgProduntoPackagesTitle, or MediaWiki:Packages.json by default. The page consists of a JSON object mapping Produnto package names to versions.

For GitLab, the package name is the part of the Git repository URL after the project name, and the package version is the relevant Git tag name, starting with a number with an optional v prefix.

Fetching the packages from the external repository is not triggered by an edit to this page, but only by a repository webhook. A package deployment dashboard is planned (T412317).

Importing

Each Produnto package can register multiple Scribunto modules. After the Produnto package is deployed, the registered Scribunto modules can be imported using require("module name"). Similarly, registered JSON files can be imported using mw.loadJsonData. (T412181)

Sandbox

To preview work-in-progress changes to modules, the extension will provide REST endpoints that can be called from an IDE plugin to override particular package files for the current user. (T415631)