Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Plugin validation

From MoodleDocs
Revision as of 06:12, 26 July 2013 by Aparup Banerjee (talk | contribs) (→‎Frequently asked questions: - added 'adding language to a plugin')

Before a plugin can be made available via the Moodle Plugins directory it has to pass both an automatic and a manual validation process. The automatic checks are repeated for each new version of the plugin that is added, however the manual checks are only done for the initial release. The aim is to complete manual checks within three working days of first submission, but it can sometimes take longer than that, so please be patient.

Automatic validation

General rules for all plugin types

  • Plugin name with Frankenstyle prefix must be unique in moodle.org/plugins. If there is another plugin with the same name you must either add new versions to this plugin (if it is yours) or rename your plugin if the names are accidentally the same. First in first served.
  • The plugin must be uploaded as a single zip file
  • The zip file must contain a single subfolder, named after your plugin (although the validator can also automatically rename subfolders generated by repos such as GitHub, which appear in the form 'username-moodle-pluginname-branchname')
  • The subfolder must be laid out in such a way that the uploaded file could be unzipped directly into the top-level folder for that plugin type (e.g. an activity plugin called 'myplugin' should install correctly when unzipped in the Moodle /mod folder, creating a subfolder /mod/myplugin with all the standard files within it).
  • The subfolder must contain a file called version.php. It should describe properties like 'version', 'requires', 'cron', 'component', 'maturity', 'release' and 'dependencies' . See exceptions below.
  • Language file must be present in lang/en/FULLNAME.php (for Moodle 2.0+) or lang/en_utf8/FULLNAME.php (for Moodle 1.9). FULLNAME is the plugin name with frankenstyle prefix. See exceptions below.
  • Language file must declare either $string['modulename'] (for activity modules) or $string['filtername'] (for Filters) or $string['pluginname'] (for all other plugin types). See exceptions below.
  • The names of all database tables should start with the full 'frankenstyle' plugin name. For example block_myblock, or auth_paypal. See exceptions below.
  • (Recommended) the subfolder should contain a file called README.txt (the validator can automatically rename other extensions to .txt) with details about the current release of the plugin.

Note: If you prefer using a readme.md file, please create a symbolic link from it to a README.txt file. This way users without any markdown reader can easily doubleclick to open and read the README.txt with their default text editor. See mklink command for Windows or ln command for Unix-like systems.

Exceptions

  • version.php is required for Moodle 2.5 and onwards. It isn't strictly required (but it is always recommended) for older moodle versions for the following plugin types:
    • Themes for Moodle 2.0 to 2.4
    • Course formats for Moodle 2.0 to 2.4
    • Blocks for Moodle 1.9
    • Auth for Moodle 1.9
  • language file is not required for plugins for Moodle 1.9 that are not activity modules
  • $string['pluginname'] is not required for plugins for Moodle 1.9 that are not activity modules
  • Question types for Moodle versions <= 2.1 instead of $string['pluginname'] should declare $string[NAME] (where NAME is the name of the plugin without frankenstyle prefix). Starting from 2.2 this was fixed and $string['pluginname'] shall be used.
  • database tables are allowed to skip mod_ prefix for activity modules
  • database tables are allowed to have question_ prefix instead of qtype_ for Question types. This is for historical reasons, all newly developed plugins are encouraged to have qtype_ prefix.

Additional checks for activity modules

  • $module->version defined in version.php
  • $module->requires defined in version.php
  • file lib.php exists
  • file lib.php contains “function xxxx_add_instance”
  • file lib.php contains “function xxxx_update_instance”
  • file view.php exists
  • file index.php exists
  • db/install.xml exists
  • db/upgrade.php exists
  • db/access.php exists

Checks for particular plugin types

  • Themes: file config.php exists
  • Blocks: file block_xxxx.php exists
  • Auth: file auth.php exists
  • Course formats: file format.php exists

The Other category in the plugins directory

If your plugin does not yet meet all the different standards, you are encouraged to add it to the Moodle Plugins Directory Other category. Plugins in this category will be excluded from any automated processes such as installations or updates. Then when the plugin is improved to meet the standards, it can be moved to an another category in the plugins directory.

Manual checks

Before the plugin is publicly viewable a trusted reviewer will look through the code to make sure it is a valid plugin. Currently, these checks are completed by Aparup Banerjee (who is also part of the integration team) and Anthony Borrow (on a volunteer basis), so please bear with us if this sometimes takes a little longer than you expect. These checks include:

  • The plugin installs cleanly
  • It does not contain any obviously harmful code
  • It is not a spam entry (This is somewhat along the lines of this policy too)
  • It is not a duplicate of an already uploaded plugin
  • It mentions GPL license (if not a boilerplate atop every file then somewhere in the downloadable zip). (or be completely GPL compatible)
  • It has documentation and referenced URLs in basic english.
  • It does not lead to unrelated sites which can simply be linked to in content nor have unnecessarily repeated links.

Comments made during the review can usually be removed prior to approval if requested.

Frequently asked questions

Q: My code contains several components, why can't I distribute it as a single package?

A: Moodle's architecture supposes that plugins are installed independently. However you can contact Aparup or Anthony and ask for your plugins to be made into a set.

For versions from Moodle 2.2 onwards you can specify that one plugin depends on another in your version.php file.

Q: I don't know which Moodle plugin type I should use. Can I just make a 'local' plugin and get it done?

A: Most of the time there will be an applicable plugin type that will fit your add-on plugin. Using an appropriate plugin type allows you to use the relevant API and provide users with a common user interface throughout Moodle. This minimises work for you. The plugin will also be more easily understood by administrators and more people will use it.

We have seen that quite often a local plugin could actually have been an admin tool plugin, so consider if that is applicable in your case.

Here is the full list of plugins to choose from. If you think there is a need for a new plugin type, we're happy to consider API improvements.

For more information about Local plugins, see this clarification.

Q: I've a plugin to share that requires closed (or non-GPL compatible) source software. Can i share this in the plugins directory?

A: Yes you can but there are several things you must do to share this properly. Paraphrasing Martin, this is OK to be approved IF (and only if):

1) We give users FULL information on the dependency and what they need to do, in the description of the plugin.
2) We make it explicit that the required code is closed source and that we cannot vouch for it. The risks are all theirs to judge from wherever they obtain the software.

You can use the 'Potential privacy issues' field when editing the plugin to help describe this clearly.

Note: Your plugin must still satisfy other validations, such as not breaking moodle (without the required non-GPL software).

Q: How to help with language support to any plugin in the plugins directory?

A: Read this post for the procedure - http://lang.moodle.org/mod/forum/discuss.php?d=2485

See also

  • Plugin documentation for information on providing documentation for your plugin right here in docs.moodle.org
  • Plugin reviews for information on how to volunteer to write plugin reviews