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
(removing non-existent links - anyone please add links as necessary)
(43 intermediate revisions by 9 users not shown)
Line 1: Line 1:
This page describes the various ways to share and work collaboratively on contributed code.
{{Plugins development}}
#Submit code in the [http://tracker.moodle.org/ Moodle Tracker] under [http://tracker.moodle.org/browse/CONTRIB CONTRIB].
#Work with submitted code in [http://cvs.moodle.org Moodle's CVS server]
#Document features and install instructions in [https://docs.moodle.org Moodle Docs]
#Share and distribute code in the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]
#Talk and support code in the [http://moodle.org/course/view.php?id=5 Using Moodle forums]
#Maintain and further develop code with the [http://tracker.moodle.org Moodle Tracker]


==The Frequently asked question==
This page describes how to contribute your code into the [[Plugins directory]] to share it with the Moodle community.
'''Question:''' I have written a new block, activity, patch or theme to share with the Moodle community. What is the process for contributing the code?


'''Answer:''' First, thank you for your generosity and desire to share your work with the rest of the Moodle community. Code contributions are highly valued and Moodle wants to encourage creativity and generosity in keeping with its constructivist tradition and pedagogical approach. To support this, there are several tools will support your contribution by allowing the code to be more easily found, tested, used, maintained, documented, and evaluated by fellow Moodlers and developers. Learning to use the various tools common among Moodle developers will help you to efficiently and effectively develop, share and maintain the contributed code.
== Why ==


==How to submit code==
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.
You have created some code that you would like to contribute to the Moodle community. The first step is to create a login in [[Tracker]]. You should create a new issue as a "non- core contributed module" project and a "New Feature" issue type. Here is a link to tracker with [http://tracker.moodle.org/secure/CreateIssue!default.jspa?pid=10033 those fields filled in].  


Your issue will be a request that the code be evaluated and uploaded into CVS. Provide a clear description of what the code does and the functionality that it adds to Moodle. Attach the contributed code as a zip (or tar.gz) file to the tracker issue. At that point, the Contrib Coordinator will work directly with the code contributor to help evaluate the code, work on resolving any questions/issues found, etc.  
Having your plugin registered with the Plugins directory has several benefits.


*Contributors are encouraged to follow Moodle's coding guidelines [[Coding]].
* 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.
*A list of current tracker [http://tracker.moodle.org/secure/BrowseProject.jspa  contributed projects is here].
* 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|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.


==How to work with code in CVS==
== Before you start ==
Once the code has been added to the CONTRIB section of Moodle's [[CVS (developer)| CVS]], the contributor will request CVS write access via http://moodle.org/cvs/ and thus be able to make changes to the contributed code.


Contributors are encouraged to maintain a branch for each major Moodle release (i.e. 1.8, 1.9, etc.). The HEAD branch should be used as the development branch. Once CVS write access is approved, the maintainer will be able to make whatever changes are needed to maintain the code.  
Before submitting your work to the Plugins directory, you should make sure you have all required and recommended resources available.


That being said, contributors are encouraged to associate each change made to an issue in the tracker. This is accomplished automatically by beginning the CVS commit comment with the issue number. By doing so, the contributor helps to document the reason for the change in the code back to the issue requesting for a change. More information on working with CVS is available at: [[CVS (developer)]].  
* '''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.
* '''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.


:''Tip:'' '''Eclipse''' is an example of an Integrated Development Environment (IDE) that integrates and facilitates many of the common CVS tasks involved in working with Moodle CVS. Instructions for setting up and using Eclipse are available at: [[Eclipse]]. Experienced developers are free to use the tools they are most comfortable/productive with.
== Sharing code in the Plugins directory ==


: Another IDE with CVS support is [[Setting_up_Netbeans|NetBeans]].
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:


==How to provide documentation==
<div class="container">
Having great code available to the community is wonderful. It is also important to educate users about how to use the code with documentation in [[Main Page|Moodle Docs]]. See [[MoodleDocs:Guidelines for contributors|guidelines for contributors]] for more help.
[[Image:plugin-contribution-workflow.png|640px]]


A documentation page for a contributed module should have some basic elements.  A brief introduction of what the code does, a "Features" heading, perhaps a "Installation", "Tips and tricks" and "See also" headings, all with content of course.  Sometimes a screenshot is worth 1000 words. In the "See also" put a link to the Modules and Plug database, with a note that this is the place to download versions, and the forum where questions can be answered at moodle.org.
''Workflow of contributing a plugin into the Moodle plugins directory ([[Media:plugin-contribution-workflow.svg|SVG version]])''
</div>


Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. We suggest placing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.
# 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].
# 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 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.
# 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.


==Share code with modules and plugins database==
=== Repository ===
Now you have a place for users to get your code, how will they know it exists? Moodle users can easily find information about contributed code in the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]. When you add an entry to this database, remember that it is searchable by any field. Every field is not required, but providing as much information as possible will help people who would like to find, read about, and then install your contribution.  In particular, the name of the module and the description of its function are important.  Screen shots are helpful (but please, not larger than 350px wide!). Links to discussion (on Moodle.org or other forum) and documentation (link to your page in the [https://docs.moodle.org Moodle docs] or another location) should be included if possible. 


If you are maintaining your code using Moodle's CVS server, a zip file of your code is automatically created and stored on Moodle's download server ([http://download.moodle.org/ http://download.moodle.org]). Therefore, the download link for most contributed code will be a link to [http://download.moodle.org/ Moodle's download server]. If you host your code on a site other than [http://download.moodle.org/ Moodle's download server], please ensure that the download link goes directly to the file and that the file is in a standard archive format (i.e. preferably a zip file). This makes it easier for users to locate the file quickly and helps to standardize installation of the code.  
* 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.
* [https://github.com/ 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.


Users may leave comments on your entry, so please check it periodically for questions and bug reports.  If you include contact information or a link to a discussion, your users may be able to contact you more directly.  The comments are not emailed automatically.
=== Tracker ===


Keep in mind that entries added to the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database] require approval by a moderator before they will be visible to other Moodle users.
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.


==Support code and get feedback with forums==
There are several options. You can decide to use the [[Tracker guide|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.
As users become familiar with the contributed code, discussions about the code are likely to emerge. We strongly urge you to place links to at least one forum at moodle.org in your Modules and Plugins entry as well as in MoodleDocs.  


It is important to respond to users who have questions about how to use the code, suggestions for how to make it better, etc. If it looks like there is sufficient need for some contributed code to have its own forum, please create a request via the tracker in the MDL-SITE section. Moodle has included many contributed code projects and ideas into its core.  
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>].


*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum.  Maybe create a thread "New Mousetrap module".
==Tutorial==
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects.
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.  
*[http://moodle.org/course/ A list of] other language forums and special areas in Moodle
 
==Maintain and refine code with Tracker==
 
In order to facilitate keeping track of feature requests, bugs, and other code issues, the contributor may request that a component be created in the CONTRIB section of the Moodle tracker. (This is the section where you initially made the request to have code included in CVS.moodle.org.)
 
The contributor can be added to the group of CONTRIB developers in the tracker to manage the issues assigned to them and better coordinate with other developers. Users of the contributed code can then add issues which can be assigned directly to the maintainer. The tracker helps to manage the work flow involved in fixing bugs, working through feature requests, and maintaining the code. When committing changes, maintainers are strongly encouraged to begin the commit comment with a tracker number.
 
We strongly encourage users to involve themselves in the process of creating a useful issue in tracker.  For the developer and code contributor,  describing the fix can help clarify the need for the code change. Further, it helps to establish good documentation about how the code developed. Others will be able to identify the issues addressed and understand why a particular decision was made.
 
==Summary==
 
It is hoped that following this procedure, will help guide contributors of code in the process of learning the tools and skills used by the Moodle developers. Learning to submit code by using the tracker, work the code with CVS, support the code by providing documentation, share code in Modules and Plugins, maintain the code by using the tracker, and evolve the code by using the Moodle.org forums will assist you in successfully contributing to the Moodle community and working with Moodle's developers.
 
Throughout this process, the CONTRIB Coordinator is here to encourage and support those contributing code to the Moodle community and fostering the development of tomorrow's Moodle developers.
 
Eventually, the community may wish for the code to become part of the Moodle core. By following the steps above, the developers will be able to evaluate the merit of the contributed code, understand how users have used the code, see the issues that have emerged and thus have more information to make an informed decision about whether or not to incorporate the contributed code into core.
 
==Most common recommendations for contributed code==
 
There are several small issues that the CONTRIB Coordinator will typically check for when reviewing the code prior to committing to the CVS server. These issues help to ensure consistency and quality of code. Any suggestions made by the CONTRIB Coordinator should be considered recommendations aimed to help folks new to the Moodle community collaborate in a way consistent with standard practices within the Moodle community. The suggestions are meant to help avoid potential issues and facilitate the acceptance of your code.
 
# '''Does the file structure conform to Moodle standards?''' - Generally speaking, each file should have an appropriate extension (i.e. php, html, css, txt, etc.). To avoid issues with case sensitivity, folders and files are normally lower case; however, there are exceptions to this. Another common recommendation is to place the lang folder within the block or module rather than asking the user to copy files into the main lang folder. Changes made in the get_string function for Moodle 1.9 and onward make it possible to do this which goes a long way in keeping things modular.
# '''Does the code work without any obvious errors?''' - The CONTRIB Coordinator will try to install the block or module on a fresh Moodle installation and report back any errors. This testing is done with Debugging set to show All PHP notices and errors (not developer mode). The most common notices have to do with attempting to use a variable that has not been initialized or checked for existence.
# '''Does the code use the config_plugins table?''' - Contributed blocks and modules are encouraged to make use of the config_plugins table rather than the config table. Maintainers are encouraged to read the documentation provided for the [http://xref.moodle.org/lib/moodlelib.php.html#get_config get_config()] and [http://xref.moodle.org/lib/moodlelib.php.html#set_config set_config()]] functions in the /lib/moodlelib.php file to help ensure that the footprint for the global $CFG variable does not become bloated.
# D'''oes the code follow the [[Coding|Coding Guidelines]]?''' - The CONTRIB Coordinator will look at the code for general readability and point out any obvious deviations from the [[Coding|Coding Guidelines]]. While not all code needs to conform with each and every guideline, maintainers are encouraged to follow those guidelines as closely as possible.


==See also==
==See also==


*[[contrib]] CONTRIB is an area in the Moodle CVS
* [[Moodle icons]]
*[[Translation]] for information on the translation of contributed code
* [[Overview]] of Moodle development
*[[Overview]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion
* [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]].
* [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:Plugin documentation]]

Revision as of 16:03, 2 January 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 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.

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. Request component for your plugin.

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