Note:

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

Plugin contribution: Difference between revisions

From MoodleDocs
(Added see also * [https://moodle.org/mod/forum/discuss.php?d=322196 Preparing plugins for Moodle 3.0] excelent summary in this forum thread.)
m (→‎Tracker: Encourage people to use a bug tracker closer to the actual code.)
(4 intermediate revisions by 3 users not shown)
Line 19: Line 19:
Before submitting your work to the Plugins directory, you should make sure you have all required and recommended resources available.
Before submitting your work to the Plugins directory, you should make sure you have all required and recommended resources available.


* '''Repository''' - In most cases, you are supposed to have the plugin code published and shared in a way that facilitates collaboration on further development. Ideally, you have the code available in a public [[Git]] repository. Most developers found [https://github.com Github] a good place to host their code on. The [[#Repository]] section below provides more details.
* '''Plugin type''' - Different [[Plugin types|plugin types]] are best suited for certain types of functionality. It is important to choose the appropriate plugin type to implement the desired features.
* '''Plugin name''' - See the [[Frankenstyle]] page for details.
* '''Repository''' - In most cases, you are supposed to have the plugin code published and shared in a way that facilitates collaboration on further development. Ideally, you have the code available in a public Git repository. Most developers found [https://github.com Github] a good place to host their code on. The [[#Repository]] section below provides more details.
* '''Tracker''' - You are expected to have a system where users can report issues, bugs and feature requests for the plugin. Again, many developers use [https://guides.github.com/features/issues/ Github issues] happily these days. You can also use the Moodle tracker if you prefer. See [[#Tracker]] section for more details.
* '''Tracker''' - You are expected to have a system where users can report issues, bugs and feature requests for the plugin. Again, many developers use [https://guides.github.com/features/issues/ Github issues] happily these days. You can also use the Moodle tracker if you prefer. See [[#Tracker]] section for more details.
* '''Documentation''' - The plugin should have a good documentation available. See [[Plugin documentation]] for options.
* '''Documentation''' - The plugin should have a good documentation available. See [[Plugin documentation]] for options.
* '''Screenshots''' - Prepare good screenshots that illustrate your plugin's essential features.  
* '''Screenshots''' - Prepare good screenshots that illustrate your plugin's essential features.


== Sharing code in the Plugins directory ==
== Sharing code in the Plugins directory ==
Line 36: Line 38:
# You upload the initial plugin version for approval. To help the approval review go smoothly, please feel encouraged to review the [[Plugin contribution checklist]] and follow all the guidelines there.
# You upload the initial plugin version for approval. To help the approval review go smoothly, please feel encouraged to review the [[Plugin contribution checklist]] and follow all the guidelines there.
# After you submit the plugin for approval, it is best to count with a week or two before you get initial review results. We generally try and provide the feedback sooner, but it is not always possible. The actual approval queue stats [https://moodle.org/plugins/queue.php are available].
# After you submit the plugin for approval, it is best to count with a week or two before you get initial review results. We generally try and provide the feedback sooner, but it is not always possible. The actual approval queue stats [https://moodle.org/plugins/queue.php are available].
# The plugin goes through the validation and approval process. See [[Plugin approval]] for details.
# The plugin goes through the validation and approval process.
# Almost all plugins are sent back as "needing more work" as a result of the initial review, and there is no reason to feel bad about that. It is natural part of the workflow. You may find particular issues reported into your [[Plugin tracker|tracker]] so you have an opportunity to demonstrate your ability to co-operate with the reporter to resolve them.
# Almost all plugins are sent back as "needing more work" as a result of the initial review, and there is no reason to feel bad about that. It is natural part of the workflow. You may find particular issues reported so you have an opportunity to demonstrate your ability to co-operate with the reporter to resolve them.
# Once the plugin is approved, its strings are registered with [[AMOS]] and can be translated. The plugin itself should ship with English strings only. The page [[Translating plugins]] has more details.
# Once the plugin is approved, its strings are registered with [[AMOS]] and can be translated. The plugin itself should ship with English strings only. The page [[Translating plugins]] has more details.
# We do not automatically pull from Github. You have to implicitly release new version via the Plugins directory. Still you are encouraged to use Git tags - releasing new version is easier then.
# We do not automatically pull from Github. You have to implicitly release new version via the Plugins directory. Still you are encouraged to use Git tags - releasing new version is easier then.
Line 53: Line 55:
You are expected to have a system where users can report feature requests, bugs, and other code issues. Following the open source best practise, these reports should be open and public and the associated procedures should be as transparent as possible.
You are expected to have a system where users can report feature requests, bugs, and other code issues. Following the open source best practise, these reports should be open and public and the associated procedures should be as transparent as possible.


There are several options. You can decide to use the [[Moodle Tracker]] as your plugin's issues tracker. Many (if not most) developers today prefer some other system such as Github. Other alternatives include BitBucket or some similar system. Generally it is suggested to use a system that your users are likely to be familiar with.
There are multiple options on where to host the issues tracker. Most plugin developers today prefer to have the issue tracker close to their source code management system - so they use the native issue tracker built into Github, BitBucket or some similar system. It is suggested to use a system that your users are likely to be familiar with.


If you decide to host your plugin's tracker on tracker.moodle.org, please let us know to create a new component in the CONTRIB project on that site. [https://tracker.moodle.org/secure/CreateIssueDetails!init.jspa?pid=10033&components=10142&issuetype=3&summary=Add+component+for+YOUR_PLUGIN_NAME&versions=14752&description=Provide+details+about+your+plugin <span class="btn">Request component for your plugin</span>].
==Tutorial==
There is a [[Tutorial]] to help you learn how to write plugins for Moodle from start to finish, while showing you how to navigate the most important developer documentation along the way.  


==See also==
==See also==
Line 64: Line 67:
* [http://aosabook.org/en/moodle.html Moodle] in The Architecture of Open Source Applications, by Tim Hunt - an overview of all aspects of how Moodle works, it focuses on those areas where Moodle's design is particularly interesting.
* [http://aosabook.org/en/moodle.html Moodle] in The Architecture of Open Source Applications, by Tim Hunt - an overview of all aspects of how Moodle works, it focuses on those areas where Moodle's design is particularly interesting.
* [http://www.examulator.com/er/ The Moodle 3.0 database schema] reverse engineered and [[Database schema introduction]].
* [http://www.examulator.com/er/ The Moodle 3.0 database schema] reverse engineered and [[Database schema introduction]].
* [https://moodle.org/mod/forum/discuss.php?d=322196 Preparing plugins for Moodle 3.0] excelent summary in this forum thread. Also applies for Moodle 3.1 and newer.
* [https://moodle.org/mod/forum/discuss.php?d=322196 Preparing plugins for Moodle 3.0] excellent summary in this forum thread. Also applies for Moodle 3.1 and newer.


[[Category:Guidelines for contributors]]
[[Category:Guidelines for contributors]]
[[Category:Plugins]]
[[Category:Plugins]]
[[Category:Plugin documentation]]
[[Category:Plugin documentation]]

Revision as of 08:51, 18 September 2018


This page describes how to contribute your code into the Plugins directory to share it with the Moodle community.

Why

You are encouraged to share your plugin with the community. But firstly, to be clear and honest, you do not necessarily need to submit your plugin into the Plugins directory. Maybe it is a custom plugin that solves one particular site's needs and you do not really want to share it with others. Remember you can always simply host your plugin on your own site and let users download it manually from there.

Having your plugin registered with the Plugins directory has several benefits.

  • Your plugin is easier to install. Plugins directory integrates with Moodle. Administrators can simply install your plugin from the plugins directory via the web interface.
  • Your plugin is easier to update. Whenever you release a new version of your plugin, all administrators having it installed are notified about the available update. They can easily upgrade to the new version from within the Moodle administration UI.
  • You reserve the component name (frankenstyle) of your plugin. Plugins directory is the official register of Moodle plugins. As with the internet domain names, there can't be two plugins having the same component name.
  • The plugin can be localised. Plugins in the Plugins directory are implicitly registered with AMOS and can be localised using the same tools that are used for localising the standard Moodle UI.
  • The plugin must be approved. Many institutions respect the approval review procedure and do not allow to install a plugin on their servers unless it has been approved in the plugins directory.

Before you start

Before submitting your work to the Plugins directory, you should make sure you have all required and recommended resources available.

  • Plugin type - Different plugin types are best suited for certain types of functionality. It is important to choose the appropriate plugin type to implement the desired features.
  • Plugin name - See the Frankenstyle page for details.
  • Repository - In most cases, you are supposed to have the plugin code published and shared in a way that facilitates collaboration on further development. Ideally, you have the code available in a public Git repository. Most developers found Github a good place to host their code on. The #Repository section below provides more details.
  • Tracker - You are expected to have a system where users can report issues, bugs and feature requests for the plugin. Again, many developers use Github issues happily these days. You can also use the Moodle tracker if you prefer. See #Tracker section for more details.
  • Documentation - The plugin should have a good documentation available. See Plugin documentation for options.
  • Screenshots - Prepare good screenshots that illustrate your plugin's essential features.

Sharing code in the Plugins directory

So you have written a new plugin and want to share it now in the Plugins directory? Great! Shortly, the workflow of publishing and maintaining your plugin in the Plugins directory looks like this:

plugin-contribution-workflow.png

Workflow of contributing a plugin into the Moodle plugins directory (SVG version)

  1. You upload the initial plugin version for approval. To help the approval review go smoothly, please feel encouraged to review the Plugin contribution checklist and follow all the guidelines there.
  2. After you submit the plugin for approval, it is best to count with a week or two before you get initial review results. We generally try and provide the feedback sooner, but it is not always possible. The actual approval queue stats are available.
  3. The plugin goes through the validation and approval process.
  4. Almost all plugins are sent back as "needing more work" as a result of the initial review, and there is no reason to feel bad about that. It is natural part of the workflow. You may find particular issues reported so you have an opportunity to demonstrate your ability to co-operate with the reporter to resolve them.
  5. Once the plugin is approved, its strings are registered with AMOS and can be translated. The plugin itself should ship with English strings only. The page Translating plugins has more details.
  6. We do not automatically pull from Github. You have to implicitly release new version via the Plugins directory. Still you are encouraged to use Git tags - releasing new version is easier then.

Repository

  • Git is de-facto standard source code management system for Moodle plugins.
  • You are supposed to publish and share your plugin code so that others can clone it easily and eventually contribute patches for it easily.
  • Github is a popular choice of many Moodle developers these days.
  • The layout should be that the root of the repository is the root of the plugin folder. In other words, in the root of your repository there should be files like version.php and folders like lang or classes. That way, your plugin can be directly cloned (checked out) into existing Moodle installation without conflicting with other contributed plugins of the same type, also obtained via Git.
  • It is suggested to follow the common naming convention of Moodle related repositories: moodle-{plugintype}_{pluginname}. For example, the birthday block has a repository name of moodle-block_birthday and is located at https://github.com/arborrow/moodle-block_birthday. Other developers can fork the code and work from their repositories.

Tracker

You are expected to have a system where users can report feature requests, bugs, and other code issues. Following the open source best practise, these reports should be open and public and the associated procedures should be as transparent as possible.

There are multiple options on where to host the issues tracker. Most plugin developers today prefer to have the issue tracker close to their source code management system - so they use the native issue tracker built into Github, BitBucket or some similar system. It is suggested to use a system that your users are likely to be familiar with.

Tutorial

There is a Tutorial to help you learn how to write plugins for Moodle from start to finish, while showing you how to navigate the most important developer documentation along the way.

See also