|
|
| (20 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| {{Plugins development}} | | {{Template:Migrated|newDocId=/general/community/plugincontribution/checklist}} |
| | |
| Before approaching the [https://moodle.org/plugins Moodle plugins directory] and submitting your plugin (or a new plugin version), you are encouraged to go through the checklists below and fix eventual issues with your plugin. Doing so will make the reviewer of your plugin happy :-) and may have impact on how long your plugin has to spend in the approval queue before it lands smoothly.
| |
| | |
| == Meta-data ==
| |
| | |
| === Plugin descriptions ===
| |
| | |
| * Have a meaningful description of your plugin prepared in English.
| |
| * You will need a short concise description (just a sentence or two) for the short description field, and another elaborated one for the full description field.
| |
| * It is encouraged to have the same info at the plugin record page and in its <tt>README</tt> file.
| |
| | |
| === Supported Moodle versions ===
| |
| | |
| * New plugins submitted into the plugins directory must support at least one of the currently maintained Moodle version.
| |
| * See [[Releases]] for the list of currently maintained Moodle versions (policy issue MDL-47579).
| |
| | |
| === Code repository name ===
| |
| | |
| * Provide a consistent experience for other Moodle developers and site administrators - follow the repository naming convention for Moodle plugins: <tt>moodle-{plugintype}_{pluginname}</tt>.
| |
| | |
| === Source control URL ===
| |
| | |
| * Facilitate sharing and further development of your open-source plugin - provide publicly accessible URL of your code repository.
| |
| * Github is a choice of most Moodle plugin developers.
| |
| | |
| === Bug tracker URL ===
| |
| | |
| * Encourage participation and have a place to report issues, bugs, make feature requests, or suggest other types of improvements.
| |
| * Both [[Tracker guide|Moodle tracker]] and [https://guides.github.com/features/issues/ Github issues] are common.
| |
| | |
| === Documentation URL ===
| |
| | |
| * Have a place where further documentation of your plugin will be located.
| |
| * [[Plugin documentation|Moodle docs]] is preferred location, [https://guides.github.com/features/wikis/ Github wikis] or your own website will work, too.
| |
| | |
| === Illustrative screenshots ===
| |
| | |
| * Capture some screenshots of your plugin to help folks get an idea of what it looks like when installed.
| |
| * We will use these screenshots at more places in the plugins directory in the future.
| |
| | |
| === Licensing ===
| |
| | |
| * All files that implement the interface between the Moodle core and the plugin must be licensed under GNU GPL v3 (or later).
| |
| * Additional files contained in the plugin ZIP package (such as third party libraries used by the plugin, or included media) may eventually use other license as long as it is [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses GPL compatible]. See [[Plugin files#thirdpartylibs.xml]] for how to do it.
| |
| * Note that binary files violate GPL unless the source code is also included or available (e.g. Java classes or Flash).
| |
| | |
| === Subscription needed ===
| |
| | |
| * If the plugin requires a third-party subscription based service, make sure the description states it very clearly.
| |
| * To allow the testing of the plugin functionality, prepare demo credentials (such as API keys etc) so that the approval team can use them to see the plugin in action.
| |
| | |
| == Usability ==
| |
| | |
| === Installation ===
| |
| | |
| * Make sure the plugin installs smoothly from the ZIP package using the in-build plugin installation interface.
| |
| * If any non-standard post-installation steps are needed, make sure they are clearly listed in both plugin description and the <tt>README</tt> file.
| |
| | |
| === Dependencies ===
| |
| | |
| * If the plugin depends on another additional plugin, make sure it is clearly stated in the description and in the <tt>README</tt> file.
| |
| * Also declare the dependency explicitly in the plugin's [[version.php]] file.
| |
| | |
| === Functionality ===
| |
| | |
| * Test the plugin functionality with full developer debugging enabled.
| |
| * Make sure the code does not throw unexpected PHP warnings, notices or even errors.
| |
| | |
| === Cross-DB compatibility ===
| |
| | |
| * Test the plugin with multiple database engines supported by Moodle.
| |
| * At very least, the plugin is supposed to work with MySQL and PostgreSQL unless reasons are clearly explained in the description and the <tt>README</tt> file (such as the plugin is a wrapper for third-party DB specific utility).
| |
| * [[Data manipulation API]] helps you to ensure cross-db compatibility.
| |
| | |
| == Coding ==
| |
| | |
| === Coding style ===
| |
| | |
| * It is encouraged to follow [[Coding style|Moodle coding style]] and other [[Coding|coding guidelines]].
| |
| * It's not always possible to achieve "all greens" in automated syntax checks (especially when third party libraries are involved) but you should aim to it.
| |
| * Consistent style helps others to read and understand your code (not only during the approval review).
| |
| | |
| === English ===
| |
| | |
| * Moodle is an international project. To facilitate sharing, reviews of and contributions to your code, all comments, variable names, function names etc. should be in English.
| |
| | |
| === Boilerplate ===
| |
| | |
| * All files should contain the common boilerplate at the beginning with explicit GPL license statement.
| |
| * See the section [[Coding_style#Files]] for the template.
| |
| | |
| === Copyrights ===
| |
| | |
| * All files should contain the <tt>@copyright</tt> tag with your name.
| |
| * If you are re-using someone else's file, keep the original copyrights reference to the previous author and add your name as a copyright holder.
| |
| * Both things should be clear: (1) that it is you to be blamed for the file code and (2) that your work is based on someone else's work.
| |
| | |
| === CSS styles ===
| |
| | |
| * Make sure to use properly namespaced selectors so that your style sheets can be safely concatenated with the ones provided by other plugins.
| |
| * Plugin specific CSS selectors are needed to make sure that your styling does not accidentally affect other parts of Moodle outside your plugin scope.
| |
| * For example, instead of the selector <tt>.contentarea</tt> it is better to use something like <tt>.path-mod-mymodule .contentarea</tt> as the .path-* classes are automatically added by the Moodle core renderers to the HTML <body> tag.
| |
| | |
| === Namespace collisions ===
| |
| | |
| * Check that all your DB tables, settings, functions, classes, constants and variables are named correctly.
| |
| * Do not define own classes, functions, variables or constants in the global PHP scope without the valid frankenstyle prefix.
| |
| * See [[Coding style#Functions and Methods]] for details.
| |
| | |
| === Settings storage ===
| |
| | |
| * Check that your settings are stored in the table <tt>config_plugins</tt> and not in the main <tt>config</tt> table.
| |
| * This helps to avoid <tt>$CFG</tt> bloat and potential collisions.
| |
| * Use <tt>get_config()</tt> to pull the settings data out of the <tt>config_plugins</tt> table.
| |
| * In the file <tt>settings.php</tt>, the setting names are supposed to be <tt>plugintype_pluginname/settingname</tt> (note the slash) and not <tt>plugintype_pluginname_settingname</tt> or even just <tt>settingname</tt>.
| |
| * If you eventually need to change the settings yourself, use <tt>set_config()</tt>.
| |
| | |
| === Strings ===
| |
| | |
| * Avoid hard-code texts in the code, always use <tt>get_string()</tt>.
| |
| * Just the English strings should ship with the plugin. All other translations are supposed to be submitted as contributions at [https://lang.moodle.org https://lang.moodle.org] once your plugin is approved - see [[Translating plugins]].
| |
| * Your code must not rely on trailing and leading whitespace in strings.
| |
| * The string file must be considered as pure data file with the syntax <tt>$string['id'] = 'value';</tt>. No other PHP syntax such as [http://php.net/manual/en/language.operators.string.php concatenation], [http://php.net/manual/en/language.types.string.php heredoc and nowdoc] is supported by the tools that we use when processing your strings (even if it may work in Moodle itself).
| |
| * The English language pack (lang/en/) in Moodle does not use "Capitalised Titles".
| |
| | |
| === Security ===
| |
| | |
| * Never trust the user input.
| |
| * Do not access superglobals like <tt>$_REQUEST</tt> directly, use wrappers like <tt>required_param()</tt> with correct type declared to sanitize input.
| |
| * Always use placeholders in custom SQL queries (<tt>?</tt> or <tt>:named</tt>).
| |
| * Always check for the <tt>sesskey</tt> before taking an action on submitted data.
| |
| * Check for <tt>require_login()</tt>.
| |
| * Always check that the user has appropriate capabilities before displaying the widgets ''and'' before taking the actual action.
| |
| * Avoid using malicious functions like <tt>call_user_func()</tt>, <tt>eval()</tt>, <tt>unserialize()</tt> and so on, especially when they would be called with user-supplied data.
| |
| | |
| == See also ==
| |
| | |
| * [https://moodle.org/mod/forum/discuss.php?d=263614 Some common issues in submitted plugins] post at the Plugins traffic forum at moodle.org
| |
