MoodleDocs - User contributions [en]

Plugin validation

2015-01-19T00:36:23Z

Aborrow: /* Manual checks */

Before a plugin can be made available via the [http://moodle.org/plugins/ 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 [http://moodle.org/mod/forum/discuss.php?d=192083#p837517 manual checks are only done for the initial release]. The aim is to complete manual checks within three working days of first submission, but sometimes based on timing and/or allocation of resources, it can take longer than that, so please be patient.

==The process==
Plugin submission --> Waiting for approval --> Approved.
* Waiting for approval --> Needs more work --> Waiting for approval
** Click 'Schedule this plugin for re-approval' under 'Admin block' > '{your plugin}' > 'Schedule this plugin for re-approval' when ready to go back into the approval queue.

Note: Plugin approvers are always get notified on all plugins that aren't approved. Feel free to leave us messages in the plugin comments during this phase.

==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.
* The subfolder should contain a file called README.txt or README.md. (the validator can automatically rename other extensions to .txt) with details about the current release of the plugin.

===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 [https://moodle.org/plugins/browse.php?list=category&id=38 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. These checks are completed by [https://moodle.org/user/view.php?id=1601&course=5 David Mudrak] (Plugins Liaison, Moodle HQ) and [https://moodle.org/user/view.php?id=51473&course=5 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 the [https://moodle.org/mod/page/view.php?id=7080 Moodle.org site policy] too)
* It does not duplicate an already uploaded plugin (or functionality available in core)
* It mentions GPL license (if not a boilerplate atop every file then somewhere in the downloadable zip). (or be [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| completely GPL compatible])
** On what the copyright should be, refer to https://moodle.org/mod/forum/discuss.php?d=213610#p1117434
* 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.
* Links that facilitate sharing (source control, issue tracker, documentation, discussion) are in the 'Useful links' section where possible.
* Conventions are followed where possible. ( eg: https://docs.moodle.org/dev/Guidelines_for_contributed_code#How_to_submit_code)
* Table config_plugin (not config) is used to store settings particular to a plugin.

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

===Recommended URLs===
We usually request for the following data to be entered along with the plugin entry in order to facilitate easier sharing of information and feedback. So, in order of recommendation, they are :
# [https://docs.moodle.org/dev/Guidelines_for_contributed_code#How_to_submit_code| Code repository], this could be any publicly accessible code repository. The suggested naming convention of the repository is [https://docs.moodle.org/dev/Guidelines_for_contributed_code#How_to_submit_code| moodle-{plugintype}_{pluginname}].
#*Moodle development [https://docs.moodle.org/dev/Process#Develop_the_code_using_Git| uses git] almost 100% of the time as such lots of developers choose to have git repositories for their plugins too. There are popular public repositories, noteably github.com has some support on plugins directory for uploading of versions via a github repository plugin.
# Issue/Bug tracker. This is to enable users and other a quick link to easily report issues they encounter with your plugin.
#*You can choose to have a new component created in [https://tracker.moodle.org/browse/CONTRIB/| Tracker]. You can also choose to have it elsewhere as long as it is publicly accessible. (See [https://moodle.org/mod/forum/discuss.php?d=213419&mode=3| related discussion])
# Documentation. This could be at docs.moodle.org or anywhere publicly accessible.
# Website. This could be to demo, further describe or simply to link to one relevant page.

===Other recommendations===
* Long and short descriptions are populated to allow for easy search/indexing of your plugin.

==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 [https://moodle.org/user/view.php?id=1146834&course=5 Aparup] or [http://moodle.org/user/view.php?id=51473&course=5 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 tools|admin tool]] plugin, so consider if that is applicable in your case.

Here is the full [https://docs.moodle.org/dev/Plugins 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 [https://moodle.org/mod/forum/discuss.php?d=224231 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
* Continuous integration with [https://docs.moodle.org/dev/Travis#Moodle_plugins Travis-ci].

[[Category:Plugins]]

Plugin validation

2015-01-19T00:27:21Z

Aborrow: /* Manual checks */

Before a plugin can be made available via the [http://moodle.org/plugins/ 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 [http://moodle.org/mod/forum/discuss.php?d=192083#p837517 manual checks are only done for the initial release]. The aim is to complete manual checks within three working days of first submission, but sometimes based on timing and/or allocation of resources, it can take longer than that, so please be patient.

==The process==
Plugin submission --> Waiting for approval --> Approved.
* Waiting for approval --> Needs more work --> Waiting for approval
** Click 'Schedule this plugin for re-approval' under 'Admin block' > '{your plugin}' > 'Schedule this plugin for re-approval' when ready to go back into the approval queue.

Note: Plugin approvers are always get notified on all plugins that aren't approved. Feel free to leave us messages in the plugin comments during this phase.

==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.
* The subfolder should contain a file called README.txt or README.md. (the validator can automatically rename other extensions to .txt) with details about the current release of the plugin.

===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 [https://moodle.org/plugins/browse.php?list=category&id=38 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. These checks are completed by [https://moodle.org/user/view.php?id=1601&course=5 David Mudrak] (Plugins Liaison, Moodle HQ) and [https://moodle.org/user/view.php?id=51473&course=5 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 the [https://moodle.org/mod/page/view.php?id=7080 Moodle.org site policy] too)
* It does not duplicate an already uploaded plugin (or functionality already available in core)
* It mentions GPL license (if not a boilerplate atop every file then somewhere in the downloadable zip). (or be [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| completely GPL compatible])
** On what the copyright should be, refer to https://moodle.org/mod/forum/discuss.php?d=213610#p1117434
* 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.
* Links that facilitate sharing (source control, issue tracker, documentation, discussion) are in the 'Useful links' section where possible.
* Conventions are followed where possible. ( eg: https://docs.moodle.org/dev/Guidelines_for_contributed_code#How_to_submit_code)
* Table config_plugin (not config) is used to store settings particular to a plugin.

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

===Recommended URLs===
We usually request for the following data to be entered along with the plugin entry in order to facilitate easier sharing of information and feedback. So, in order of recommendation, they are :
# [https://docs.moodle.org/dev/Guidelines_for_contributed_code#How_to_submit_code| Code repository], this could be any publicly accessible code repository. The suggested naming convention of the repository is [https://docs.moodle.org/dev/Guidelines_for_contributed_code#How_to_submit_code| moodle-{plugintype}_{pluginname}].
#*Moodle development [https://docs.moodle.org/dev/Process#Develop_the_code_using_Git| uses git] almost 100% of the time as such lots of developers choose to have git repositories for their plugins too. There are popular public repositories, noteably github.com has some support on plugins directory for uploading of versions via a github repository plugin.
# Issue/Bug tracker. This is to enable users and other a quick link to easily report issues they encounter with your plugin.
#*You can choose to have a new component created in [https://tracker.moodle.org/browse/CONTRIB/| Tracker]. You can also choose to have it elsewhere as long as it is publicly accessible. (See [https://moodle.org/mod/forum/discuss.php?d=213419&mode=3| related discussion])
# Documentation. This could be at docs.moodle.org or anywhere publicly accessible.
# Website. This could be to demo, further describe or simply to link to one relevant page.

===Other recommendations===
* Long and short descriptions are populated to allow for easy search/indexing of your plugin.

==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 [https://moodle.org/user/view.php?id=1146834&course=5 Aparup] or [http://moodle.org/user/view.php?id=51473&course=5 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 tools|admin tool]] plugin, so consider if that is applicable in your case.

Here is the full [https://docs.moodle.org/dev/Plugins 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 [https://moodle.org/mod/forum/discuss.php?d=224231 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
* Continuous integration with [https://docs.moodle.org/dev/Travis#Moodle_plugins Travis-ci].

[[Category:Plugins]]

version.php

2013-03-28T23:58:50Z

Aborrow: adding subpackage and author options to comments

This file is included in the main directory of plugin. It is compulsory for most plugin types. Even when not compulsory it is highly recommended.

It contains a number of fields, which are used during the install / upgrade process to make sure the plugin is compatible with the current Moodle install, as well as spotting whether an upgrade is needed.

The file is a standard PHP file, starting with an opening '<?php' tag and defining the following variables:

'''Note! For Activity modules replace $plugin-> with $module-> in the following example!'''

* $plugin->version = 2011051000;
** Required - the version number of your plugin in the form YYYYMMDDxx, so this example is 10th May 2011 (with 00 indicating this is the first version for that day)
* $plugin->requires = 2010112400;
** Optional - minimum version number of Moodle that this plugin requires (Moodle 1.9 = 2007101509; Moodle 2.0 = 2010112400; Moodle 2.1 = 2011070100; Moodle 2.2 = 2011120500; Moodle 2.3 = 2012062500). See [[Releases]] for a full list.
* $plugin->cron = 0;
** Optional - time interval (in seconds) between calls to the plugin's 'cron' function; set to 0 to disable the cron function calls.
** Cron support is not yet implemented for all plugins.
* $plugin->component = 'plugintype_pluginname';
** Optional - ''frankenstyle'' plugin name, strongly recommended. It is used for installation and upgrade diagnostics.
* $plugin->maturity = MATURITY_STABLE;
** Optional - how stable the plugin is: MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC, MATURITY_STABLE (Moodle 2.0 and above)
* $plugin->release = '2.x (Build: 2011051000)';
** Optional - Human-readable version name
* $plugin->dependencies = array('mod_forum' => ANY_VERSION, 'mod_data' => 2010020300);
** Optional - list of other plugins that are required for this plugin to work (Moodle 2.2 and above)
** In this example, the plugin requires any version of the forum activity and version '20100020300' (or above) of the database activity

Here is a template to copy and paste:
<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* TODO
*
* @package TODO_FRANKENSTYLE
* @subpackage TODO_SUBPACKAGE
* @author TODO_AUTHOR
* @copyright TODO_COPYRIGHT
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die();

$plugin->version = TODO;
$plugin->requires = TODO; // See https://docs.moodle.org/dev/Moodle_Versions
$plugin->cron = 0;
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = array(
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
);
</code>

==See also==

* [[Moodle versions]]

[[Category:Plugins]]

How to create a patch

2011-08-01T12:57:14Z

Aborrow: /* See Also */

If you have made some changes to the code that you would like to share with the community, particularly if you want to send them to one of the core developers for possible inclusion in Moodle Core, it is very helpful if you can provide them as a [[Patch|patch file]]. Sometimes also called a diff file.

This page explains how you can make a patch file. Patch is a standard format, and there are many options for how to create one. Pick the one that is easiest for you.
'''
One of the most critical aspects of patch usage is identifying for your audience the location for the patch file for application relative to the -p flag! When you create patches note your location and provide that when you share patches. '''

''Note, I have not been able to test most of these instructions. They are about right, but I am hoping that as people use them, they will fill in any gaps, correct any details, and so on.[[User:Tim Hunt|Tim Hunt]] 08:40, 25 June 2007 (CDT)''

==Creating a patch using diff==

diff is the a linux command line program, and is where patch files originated. It requires that you have two copies of the code, one with your changes, and one without. Suppose these two copies are in folders called 'standard_moodle' and 'my_moodle' which are subdirectories of the current folder. Then to create the patch, type:

diff -Naur standard_moodle my_moodle > patch.txt

==Creating a patch using CVS (command line)==

It is easier if you are using CVS to manage your development, because you don't need to keep the copy of 'standard_moodle'. CVS takes care of that for you. In your workspace (sandbox) type:

cvs diff -uN > patch.txt

If you have unversioned files to include in your patch, you will notice that the above command simply adds the file's name to the top of your patch, prefixed with a question mark. This is because your new file is not tagged for adding to the repository. Just do

cvs add newfile

Then

cvs diff -uNa > patch.txt

This should add the correct code to the patch, so that someone applying the patch to their working copy will have a new file created at the right place (hopefully!).

If your patch, for some reason, contains a lot of white space changes in many files, you might want to add -Bbw to the diff call. Make sure these changes are really not significant (like adding or removing a space at the end of a line - editors like Eclipse sometimes do this automatically). This can make a patch a lot smaller, and thus easier to review. The complete call would then be

cvs diff -uNawbB > patch.txt

==Creating a patch using Tortoise CVS==

[http://www.tortoisecvs.org/ Tortoise CVS] is a Windows GUI front end for CVS. To create a patch, right-click on a folder in CVS, and choose '''CVS -> Make patch ...''' from the context menu.

==Creating a patch using Eclipse==

See [[Setting_up_Eclipse#Creating_a_patch]]. Eclipse makes creating patches really easy, once you have got it set up correctly.

==Creating a patch using WinMerge==

[http://winmerge.org/ WinMerge] is a nice windows GUI for comparing folders. In this sense it is like the original command-line 'diff' program. You need a copy of 'standard_moodle' and 'my_moodle'. Use '''File -> Open...''' to open the two versions for comparison. This will give you a nice view of what you have changed. Then do '''Tools -> Generate patch ...'''. In the dialogue box, make sure you select Style: Unified in the Format box.

==Creating a patch using Git==

Creating a patch if you're using Git for version control is similar to CVS, and similarly you don't need an unchanged copy of moodle to diff against.
The easiest way to create a patch for the last commit is

git show > patch.txt

or if you want to create a patch between 2 specific commits you can use git diff

git diff ''commitid1'' ''commitid2'' > patch.txt

There's also a tool, format-patch, for formatting a patch to send as an e-mail. You can create patches for the last ''n'' revisions like this:

git format-patch -''n''

which will create the patch in the current directory. The -o parameter allows you to specify a different output directory.

==See Also==
* [http://drupal.org/node/1054616 Detailed instructions for creating patches using Git]: [http://moodle.org/mod/forum/discuss.php?d=181953#p792050 shared by Frank Ralf]
* [[How_to_apply_a_patch]]
* [[Patch]]

Releases

2011-06-18T22:28:21Z

Aborrow: adding Roadmap to See also section

UNDER RE-CONSTRUCTION!

Derived from:
* https://docs.moodle.org/20/en/Latest_release_notes
* https://docs.moodle.org/20/en/Moodle_version_history

==Moodle 1.0==
*Moodle 1.0 - 20 August 2002
*Moodle 1.0.1 - 26 August 2002
*Moodle 1.0.2 - 2 September 2002
*Moodle 1.0.3 - 5 September 2002
*Moodle 1.0.4 - 10 September 2002
*Moodle 1.0.5 - 27 September 2002
*Moodle 1.0.6 - 26 October 2002
:: 1.0.6.1 - 6 Nov
:: 1.0.6.2 - 11 Nov
:: 1.0.6.3 - 14 Nov
:: 1.0.6.4 - 25 Nov
*Moodle 1.0.7 - 9 December 2002
*Moodle 1.0.8 - 7 January 2003
*Moodle 1.0.9 - 30 May 2003

==Moodle 1.1==
*Moodle 1.1 - 29 August 2003
*Moodle 1.1.1 - 11 September 2003

==Moodle 1.2==
*Moodle 1.2 - 20 March 2004
*Moodle 1.2.1 - 25 March 2004

==Moodle 1.3==
*Moodle 1.3 - 25 May 2004
*Moodle 1.3.1 - 4 June 2004
*Moodle 1.3.2 - 9 July 2004
*Moodle 1.3.3 - 16 July 2004
*Moodle 1.3.4 - 11 August 2004

==Moodle 1.4==
*Moodle 1.4 - 31 August 2004
*Moodle 1.4.1 - 12 September 2004
*Moodle 1.4.2 - 5 November 2004
*Moodle 1.4.3 - 21 December 2004
*Moodle 1.4.4 - 7 March 2005
*[[Moodle 1.4.5 release notes|Moodle 1.4.5]] - 7 May 2005

==Moodle 1.5==
*[[Moodle 1.5 release notes|Moodle 1.5]] - 5 June 2005
*[[Moodle 1.5.1 release notes|Moodle 1.5.1]] - 8 July 2005
*[[Moodle 1.5.2 release notes|Moodle 1.5.2]] - 16 July 2005
*[[Moodle 1.5.3 release notes|Moodle 1.5.3]] - 11 November 2005
*[[Moodle 1.5.4 release notes|Moodle 1.5.4]] - 21 May 2006

==Moodle 1.6==
*[[Moodle 1.6 release notes|Moodle 1.6]] - 20 June 2006
*[[Moodle 1.6.1 release notes|Moodle 1.6.1]] - 20 July 2006
*[[Moodle 1.6.2 release notes|Moodle 1.6.2]] - 12 September 2006
*[[Moodle 1.6.3 release notes|Moodle 1.6.3]] - 10 October 2006
*[[Moodle 1.6.4 release notes|Moodle 1.6.4]] - 17 January 2007
*[[Moodle 1.6.5 release notes|Moodle 1.6.5]] - 30 March 2007
*Moodle 1.6.6 - 11 January 2008
*Moodle 1.6.7 - 11 July 2008
*[[Moodle 1.6.8 release notes|Moodle 1.6.8]] - 15 October 2008
*[[Moodle 1.6.9 release notes|Moodle 1.6.9]] - 28 January 2009

==Moodle 1.7==
*[[Moodle 1.7 release notes|Moodle 1.7]] - 7 November 2006
*[[Moodle 1.7.1 release notes|Moodle 1.7.1]] - 17 January 2007
*[[Moodle 1.7.2 release notes|Moodle 1.7.2]] - 30 March 2007
*[[Moodle 1.7.3 release notes|Moodle 1.7.3]] - 11 October 2007
*[[Moodle 1.7.4 release notes|Moodle 1.7.4]] - 11 January 2008
*[[Moodle 1.7.5 release notes|Moodle 1.7.5]] - 11 July 2008
*[[Moodle 1.7.6 release notes|Moodle 1.7.6]] - 15 October 2008
*[[Moodle 1.7.7 release notes|Moodle 1.7.7]] - 28 January 2009

==Moodle 1.8==
*[[Moodle 1.8 release notes|Moodle 1.8]] - 30 March 2007
*[[Moodle 1.8.1 release notes|Moodle 1.8.1]] - 14 June 2007
*[[Moodle 1.8.2 release notes|Moodle 1.8.2]] - 8 July 2007
*[[Moodle 1.8.3 release notes|Moodle 1.8.3]] - 11 October 2007
*[[Moodle 1.8.4 release notes|Moodle 1.8.4]] - 11 January 2008
*[[Moodle 1.8.5 release notes|Moodle 1.8.5]] - 8 April 2008
*[[Moodle 1.8.6 release notes|Moodle 1.8.6]] - 11 July 2008
*[[Moodle 1.8.7 release notes|Moodle 1.8.7]] - 15 October 2008
*[[Moodle 1.8.8 release notes|Moodle 1.8.8]] - 28 January 2009
*[[Moodle 1.8.9 release notes|Moodle 1.8.9]] - 15 May 2009
*[[Moodle 1.8.10 release notes|Moodle 1.8.10]] - 26 October 2009
*[[Moodle 1.8.11 release notes|Moodle 1.8.11]] - 25 November 2009
*[[Moodle 1.8.12 release notes|Moodle 1.8.12]] - 27 March 2010
*[[Moodle 1.8.13 release notes|Moodle 1.8.13]] - 8 June 2010
*[[Moodle 1.8.14 release notes|Moodle 1.8.14]] - 3 December 2010

==Moodle 1.9==
*[[Moodle 1.9 release notes|Moodle 1.9]] - 3 March 2008
*[[Moodle 1.9.1 release notes|Moodle 1.9.1]] - 15 May 2008
*[[Moodle 1.9.2 release notes|Moodle 1.9.2]] - 11 July 2008
*[[Moodle 1.9.3 release notes|Moodle 1.9.3]] - 15 October 2008
*[[Moodle 1.9.4 release notes|Moodle 1.9.4]] - 28 January 2009
*[[Moodle 1.9.5 release notes|Moodle 1.9.5]] - 13 May 2009
*[[Moodle 1.9.6 release notes|Moodle 1.9.6]] - 21 October 2009
*[[Moodle 1.9.7 release notes|Moodle 1.9.7]] - 25 November 2009
*[[Moodle 1.9.8 release notes|Moodle 1.9.8]] - 25 March 2010
*[[Moodle 1.9.9 release notes|Moodle 1.9.9]] - 8 June 2010
*[[Moodle 1.9.10 release notes|Moodle 1.9.10]] - 25 October 2010
*[[Moodle 1.9.11 release notes|Moodle 1.9.11]] - 21 February 2011

==Moodle 2.0==
*[[Moodle 2.0 release notes|Moodle 2.0]] - 24 November 2010
*[[Moodle 2.0.1 release notes|Moodle 2.0.1]] - 25 December 2010
*[[Moodle 2.0.2 release notes|Moodle 2.0.2]] - 21 February 2011
*[[Moodle 2.0.3 release notes|Moodle 2.0.3]] - 5 May 2011

==See also==

*[https://docs.moodle.org/20/en/Roadmap Roadmap]
*[https://docs.moodle.org/20/en/Updates Updates]

[[Category:Release notes]]

[[fr:Historique des versions]]
[[es:Historia de las versiones]]
[[de:Versionshistorie]]

Releases

2011-06-18T22:26:25Z

Aborrow: adding See also to Updates page

UNDER RE-CONSTRUCTION!

Derived from:
* https://docs.moodle.org/20/en/Latest_release_notes
* https://docs.moodle.org/20/en/Moodle_version_history

==Moodle 1.0==
*Moodle 1.0 - 20 August 2002
*Moodle 1.0.1 - 26 August 2002
*Moodle 1.0.2 - 2 September 2002
*Moodle 1.0.3 - 5 September 2002
*Moodle 1.0.4 - 10 September 2002
*Moodle 1.0.5 - 27 September 2002
*Moodle 1.0.6 - 26 October 2002
:: 1.0.6.1 - 6 Nov
:: 1.0.6.2 - 11 Nov
:: 1.0.6.3 - 14 Nov
:: 1.0.6.4 - 25 Nov
*Moodle 1.0.7 - 9 December 2002
*Moodle 1.0.8 - 7 January 2003
*Moodle 1.0.9 - 30 May 2003

==Moodle 1.1==
*Moodle 1.1 - 29 August 2003
*Moodle 1.1.1 - 11 September 2003

==Moodle 1.2==
*Moodle 1.2 - 20 March 2004
*Moodle 1.2.1 - 25 March 2004

==Moodle 1.3==
*Moodle 1.3 - 25 May 2004
*Moodle 1.3.1 - 4 June 2004
*Moodle 1.3.2 - 9 July 2004
*Moodle 1.3.3 - 16 July 2004
*Moodle 1.3.4 - 11 August 2004

==Moodle 1.4==
*Moodle 1.4 - 31 August 2004
*Moodle 1.4.1 - 12 September 2004
*Moodle 1.4.2 - 5 November 2004
*Moodle 1.4.3 - 21 December 2004
*Moodle 1.4.4 - 7 March 2005
*[[Moodle 1.4.5 release notes|Moodle 1.4.5]] - 7 May 2005

==Moodle 1.5==
*[[Moodle 1.5 release notes|Moodle 1.5]] - 5 June 2005
*[[Moodle 1.5.1 release notes|Moodle 1.5.1]] - 8 July 2005
*[[Moodle 1.5.2 release notes|Moodle 1.5.2]] - 16 July 2005
*[[Moodle 1.5.3 release notes|Moodle 1.5.3]] - 11 November 2005
*[[Moodle 1.5.4 release notes|Moodle 1.5.4]] - 21 May 2006

==Moodle 1.6==
*[[Moodle 1.6 release notes|Moodle 1.6]] - 20 June 2006
*[[Moodle 1.6.1 release notes|Moodle 1.6.1]] - 20 July 2006
*[[Moodle 1.6.2 release notes|Moodle 1.6.2]] - 12 September 2006
*[[Moodle 1.6.3 release notes|Moodle 1.6.3]] - 10 October 2006
*[[Moodle 1.6.4 release notes|Moodle 1.6.4]] - 17 January 2007
*[[Moodle 1.6.5 release notes|Moodle 1.6.5]] - 30 March 2007
*Moodle 1.6.6 - 11 January 2008
*Moodle 1.6.7 - 11 July 2008
*[[Moodle 1.6.8 release notes|Moodle 1.6.8]] - 15 October 2008
*[[Moodle 1.6.9 release notes|Moodle 1.6.9]] - 28 January 2009

==Moodle 1.7==
*[[Moodle 1.7 release notes|Moodle 1.7]] - 7 November 2006
*[[Moodle 1.7.1 release notes|Moodle 1.7.1]] - 17 January 2007
*[[Moodle 1.7.2 release notes|Moodle 1.7.2]] - 30 March 2007
*[[Moodle 1.7.3 release notes|Moodle 1.7.3]] - 11 October 2007
*[[Moodle 1.7.4 release notes|Moodle 1.7.4]] - 11 January 2008
*[[Moodle 1.7.5 release notes|Moodle 1.7.5]] - 11 July 2008
*[[Moodle 1.7.6 release notes|Moodle 1.7.6]] - 15 October 2008
*[[Moodle 1.7.7 release notes|Moodle 1.7.7]] - 28 January 2009

==Moodle 1.8==
*[[Moodle 1.8 release notes|Moodle 1.8]] - 30 March 2007
*[[Moodle 1.8.1 release notes|Moodle 1.8.1]] - 14 June 2007
*[[Moodle 1.8.2 release notes|Moodle 1.8.2]] - 8 July 2007
*[[Moodle 1.8.3 release notes|Moodle 1.8.3]] - 11 October 2007
*[[Moodle 1.8.4 release notes|Moodle 1.8.4]] - 11 January 2008
*[[Moodle 1.8.5 release notes|Moodle 1.8.5]] - 8 April 2008
*[[Moodle 1.8.6 release notes|Moodle 1.8.6]] - 11 July 2008
*[[Moodle 1.8.7 release notes|Moodle 1.8.7]] - 15 October 2008
*[[Moodle 1.8.8 release notes|Moodle 1.8.8]] - 28 January 2009
*[[Moodle 1.8.9 release notes|Moodle 1.8.9]] - 15 May 2009
*[[Moodle 1.8.10 release notes|Moodle 1.8.10]] - 26 October 2009
*[[Moodle 1.8.11 release notes|Moodle 1.8.11]] - 25 November 2009
*[[Moodle 1.8.12 release notes|Moodle 1.8.12]] - 27 March 2010
*[[Moodle 1.8.13 release notes|Moodle 1.8.13]] - 8 June 2010
*[[Moodle 1.8.14 release notes|Moodle 1.8.14]] - 3 December 2010

==Moodle 1.9==
*[[Moodle 1.9 release notes|Moodle 1.9]] - 3 March 2008
*[[Moodle 1.9.1 release notes|Moodle 1.9.1]] - 15 May 2008
*[[Moodle 1.9.2 release notes|Moodle 1.9.2]] - 11 July 2008
*[[Moodle 1.9.3 release notes|Moodle 1.9.3]] - 15 October 2008
*[[Moodle 1.9.4 release notes|Moodle 1.9.4]] - 28 January 2009
*[[Moodle 1.9.5 release notes|Moodle 1.9.5]] - 13 May 2009
*[[Moodle 1.9.6 release notes|Moodle 1.9.6]] - 21 October 2009
*[[Moodle 1.9.7 release notes|Moodle 1.9.7]] - 25 November 2009
*[[Moodle 1.9.8 release notes|Moodle 1.9.8]] - 25 March 2010
*[[Moodle 1.9.9 release notes|Moodle 1.9.9]] - 8 June 2010
*[[Moodle 1.9.10 release notes|Moodle 1.9.10]] - 25 October 2010
*[[Moodle 1.9.11 release notes|Moodle 1.9.11]] - 21 February 2011

==Moodle 2.0==
*[[Moodle 2.0 release notes|Moodle 2.0]] - 24 November 2010
*[[Moodle 2.0.1 release notes|Moodle 2.0.1]] - 25 December 2010
*[[Moodle 2.0.2 release notes|Moodle 2.0.2]] - 21 February 2011
*[[Moodle 2.0.3 release notes|Moodle 2.0.3]] - 5 May 2011

==See also==

*[https://docs.moodle.org/20/en/Updates Updates]

[[Category:Release notes]]

[[fr:Historique des versions]]
[[es:Historia de las versiones]]
[[de:Versionshistorie]]

Plugin contribution

2011-06-15T07:23:44Z

Aborrow: /* Does the code follow the Coding Guidelines? */

This page describes the various ways to share and work collaboratively on contributed code. In the past, Moodle CONTRIB code was often stored on the Moodle CVS server. As Moodle code transitions to [https://docs.moodle.org/en/Git Git], CONTRIB code will also be transitioning with a goal of having all code maintained via git repositories by August 2011. Don't worry if you have code on CVS and do not know Git as there are many people willing to help you with the transition especially [https://docs.moodle.org/en/User:Anthony_Borrow Anthony Borrow].

For those neither familiar with CVS nor Git, it is recommended that you [https://docs.moodle.org/en/Git#Books_and_tutorials learn Git basics]. The nice thing about using Git is that it will leave control of the code in the hands of contributor.

*'''Sharing code''' - Contributed code will be shared and maintained using a public Git repository (i.e. github.com, gitorious.org, etc.).
*'''Reviewing code''' - If you would like your code to be tested and reviewed, please create an issue in the [http://tracker.moodle.org/ Moodle Tracker] under [http://tracker.moodle.org/browse/CONTRIB CONTRIB].
*'''Documenting code''' - You can maintain helpful documentation of the features and installation instructions in [https://docs.moodle.org Moodle Docs]
*'''Distributing code''' - You can help others find your code by adding an entry to the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]
*'''Discussing the code''' - You can discuss the functionality and answer questions about how to use your code in the [http://moodle.org/course/view.php?id=5 Using Moodle forums]. Users can ask questions, discuss possible ideas for improvement, etc. Once the discussion matures to a point where you may want to take action, then you can create an issue in the [http://tracker.moodle.org/ Moodle Tracker].
*'''Maintaining code''' - You can further develop your code by fixing issues, adding features, and responding to other issues with the [http://tracker.moodle.org/ Moodle Tracker]. Each plugin or patch can have its own component in the CONTRIB project; however, you will need to request that the component be created in the CONTRIB project. Once created, users can easily create issues related to your contributed code. The primary maintainer of the code will be assigned as the component lead and have their tracker privileges bumped so that they can manage issues related to their contributed code. Those issues will automatically be assigned to the component lead/primary maintainer.

==The CONTRIB Frequently Asked Question (FAQ)==
'''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 [https://docs.moodle.org/en/Pedagogy Moodle's social constructionist pedagogy].

As mentioned, there are various tools to help you share and support your contribution. By using a consistent methodology, your Moodle related code will 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 your contributed code.

==How to submit code==
You have created some code that you would like to contribute to the Moodle community. The first step is to choose which Git code hosting site you want to use. Both [http://github.com/ github.com] and [http://gitorious.org/ gitorious.org] are popular. Follow the instructions for creating a public repository for your code. This will allow others to download your code as well as suggest possible patches. As you become more familiar with collaborating with others you can also control who else you want to be able to push changes into your repository (i.e. write access).

In order to facilitate a common naming convention of Moodle related repositories, it is suggested that you use the following format: 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.

==How to request that your code be tested/reviewed==

#If you do not already have an account on the [http://tracker.moodle.org] Moodle Tracker], create one and login.
#Create a new "Task" issue in the "Non-core contributed modules" project. Your issue will be a request that the code be tested and reviewed.
#Provide the link to the repository (i.e. https://github.com/arborrow/moodle-block_birthday)
#Provide a clear description of what the code does and the functionality that it adds to Moodle.
#Provide any other links to supporting documentation

The Contrib Coordinator will then work directly with the code contributor via the Tracker to help evaluate the code, work on resolving any questions/issues found, etc.

*Contributors are encouraged to follow Moodle's coding guidelines [[Coding]].

*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.

*Contributors are encouraged to associate each change made to an issue in the tracker. This practice is done by Moodle core developers and it is a good habit to get into so that you can go back and see why various changes were made to the code. Simple practices like these help to create good documentation of the code as it develops and matures. Commits should begin with the Moodle tracker issue number followed by a brief description of the change.

==How to provide documentation==
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.

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.

Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.

===Possible format for a contributed code Moodle Docs page===
You can copy and paste the below into your Moodle documentation page. Please add the URL links. '''This is only a suggestion'''.
Start with a 2-4 line introduction. The Plug In Name works with the activity module.
It makes the life of the teacher easier by ...
==Features==
* Add features list or overview description here <nowiki> </nowiki>
<nowiki> [[Image:Sample_screen_shot|thumb|500px|center|Title of screenshot]]</nowiki>
==Installation==
Place install instructions here
==Tips and tricks==
*Optional section, usually added by users later
==See also==
*[Place http_address_for_M&P_entry_here Name of Entry here] is a Modules and plugins database page that has download links and more information.
*Discussions: [Place http_address_for_moodle_forum_or_thread_here Name of forum]

When no thread or forum exists for discussion, put a link to the Contributed Code forum.
*Discussions: Please create or find a discussion topic in the <nowiki>[http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]</nowiki>

==Share code with modules and plugins database==
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.

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.

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.

==Support code and get feedback with forums==
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.

*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects.
*[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. Similarly, to respect the modular nature of Moodle if a block requires a library it is usually preferred to keep it as a subdirectory in the block's folder. This can be especially helpful if your code is dependent upon a particular version of an external library.

=== 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.

=== Does 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. One useful tool for Moodle 2.0 is the [http://moodle.org/mod/data/view.php?d=13&rid=4682|Code checker local plugin] which helps to identify many issues.

==See also==

*[[Migrating contrib code to 2.0]]
*[[contrib]] CONTRIB is an area in the Moodle CVS
*[[Translation]] for information on the translation of contributed code
*[[Overview]]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion

[[Category:Guidelines for contributors]]

Plugin contribution

2011-06-15T07:23:02Z

Aborrow: /* Does the code follow the Coding Guidelines? */

This page describes the various ways to share and work collaboratively on contributed code. In the past, Moodle CONTRIB code was often stored on the Moodle CVS server. As Moodle code transitions to [https://docs.moodle.org/en/Git Git], CONTRIB code will also be transitioning with a goal of having all code maintained via git repositories by August 2011. Don't worry if you have code on CVS and do not know Git as there are many people willing to help you with the transition especially [https://docs.moodle.org/en/User:Anthony_Borrow Anthony Borrow].

For those neither familiar with CVS nor Git, it is recommended that you [https://docs.moodle.org/en/Git#Books_and_tutorials learn Git basics]. The nice thing about using Git is that it will leave control of the code in the hands of contributor.

*'''Sharing code''' - Contributed code will be shared and maintained using a public Git repository (i.e. github.com, gitorious.org, etc.).
*'''Reviewing code''' - If you would like your code to be tested and reviewed, please create an issue in the [http://tracker.moodle.org/ Moodle Tracker] under [http://tracker.moodle.org/browse/CONTRIB CONTRIB].
*'''Documenting code''' - You can maintain helpful documentation of the features and installation instructions in [https://docs.moodle.org Moodle Docs]
*'''Distributing code''' - You can help others find your code by adding an entry to the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]
*'''Discussing the code''' - You can discuss the functionality and answer questions about how to use your code in the [http://moodle.org/course/view.php?id=5 Using Moodle forums]. Users can ask questions, discuss possible ideas for improvement, etc. Once the discussion matures to a point where you may want to take action, then you can create an issue in the [http://tracker.moodle.org/ Moodle Tracker].
*'''Maintaining code''' - You can further develop your code by fixing issues, adding features, and responding to other issues with the [http://tracker.moodle.org/ Moodle Tracker]. Each plugin or patch can have its own component in the CONTRIB project; however, you will need to request that the component be created in the CONTRIB project. Once created, users can easily create issues related to your contributed code. The primary maintainer of the code will be assigned as the component lead and have their tracker privileges bumped so that they can manage issues related to their contributed code. Those issues will automatically be assigned to the component lead/primary maintainer.

==The CONTRIB Frequently Asked Question (FAQ)==
'''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 [https://docs.moodle.org/en/Pedagogy Moodle's social constructionist pedagogy].

As mentioned, there are various tools to help you share and support your contribution. By using a consistent methodology, your Moodle related code will 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 your contributed code.

==How to submit code==
You have created some code that you would like to contribute to the Moodle community. The first step is to choose which Git code hosting site you want to use. Both [http://github.com/ github.com] and [http://gitorious.org/ gitorious.org] are popular. Follow the instructions for creating a public repository for your code. This will allow others to download your code as well as suggest possible patches. As you become more familiar with collaborating with others you can also control who else you want to be able to push changes into your repository (i.e. write access).

In order to facilitate a common naming convention of Moodle related repositories, it is suggested that you use the following format: 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.

==How to request that your code be tested/reviewed==

#If you do not already have an account on the [http://tracker.moodle.org] Moodle Tracker], create one and login.
#Create a new "Task" issue in the "Non-core contributed modules" project. Your issue will be a request that the code be tested and reviewed.
#Provide the link to the repository (i.e. https://github.com/arborrow/moodle-block_birthday)
#Provide a clear description of what the code does and the functionality that it adds to Moodle.
#Provide any other links to supporting documentation

The Contrib Coordinator will then work directly with the code contributor via the Tracker to help evaluate the code, work on resolving any questions/issues found, etc.

*Contributors are encouraged to follow Moodle's coding guidelines [[Coding]].

*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.

*Contributors are encouraged to associate each change made to an issue in the tracker. This practice is done by Moodle core developers and it is a good habit to get into so that you can go back and see why various changes were made to the code. Simple practices like these help to create good documentation of the code as it develops and matures. Commits should begin with the Moodle tracker issue number followed by a brief description of the change.

==How to provide documentation==
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.

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.

Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.

===Possible format for a contributed code Moodle Docs page===
You can copy and paste the below into your Moodle documentation page. Please add the URL links. '''This is only a suggestion'''.
Start with a 2-4 line introduction. The Plug In Name works with the activity module.
It makes the life of the teacher easier by ...
==Features==
* Add features list or overview description here <nowiki> </nowiki>
<nowiki> [[Image:Sample_screen_shot|thumb|500px|center|Title of screenshot]]</nowiki>
==Installation==
Place install instructions here
==Tips and tricks==
*Optional section, usually added by users later
==See also==
*[Place http_address_for_M&P_entry_here Name of Entry here] is a Modules and plugins database page that has download links and more information.
*Discussions: [Place http_address_for_moodle_forum_or_thread_here Name of forum]

When no thread or forum exists for discussion, put a link to the Contributed Code forum.
*Discussions: Please create or find a discussion topic in the <nowiki>[http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]</nowiki>

==Share code with modules and plugins database==
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.

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.

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.

==Support code and get feedback with forums==
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.

*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects.
*[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. Similarly, to respect the modular nature of Moodle if a block requires a library it is usually preferred to keep it as a subdirectory in the block's folder. This can be especially helpful if your code is dependent upon a particular version of an external library.

=== 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.

=== Does 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. One useful tool for Moodle 2.0 is the [[http://moodle.org/mod/data/view.php?d=13&rid=4682|Code checker local plugin]] which helps to identify many issues.

==See also==

*[[Migrating contrib code to 2.0]]
*[[contrib]] CONTRIB is an area in the Moodle CVS
*[[Translation]] for information on the translation of contributed code
*[[Overview]]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion

[[Category:Guidelines for contributors]]

Plugin contribution

2011-01-28T22:20:10Z

Aborrow:

This page describes the various ways to share and work collaboratively on contributed code. In the past, Moodle CONTRIB code was often stored on the Moodle CVS server. As Moodle code transitions to [https://docs.moodle.org/en/Git Git], CONTRIB code will also be transitioning with a goal of having all code maintained via git repositories by August 2011. Don't worry if you have code on CVS and do not know Git as there are many people willing to help you with the transition especially [https://docs.moodle.org/en/User:Anthony_Borrow Anthony Borrow].

For those neither familiar with CVS nor Git, it is recommended that you [https://docs.moodle.org/en/Git#Books_and_tutorials learn Git basics]. The nice thing about using Git is that it will leave control of the code in the hands of contributor.

*'''Sharing code''' - Contributed code will be shared and maintained using a public Git repository (i.e. github.com, gitorious.org, etc.).
*'''Reviewing code''' - If you would like your code to be tested and reviewed, please create an issue in the [http://tracker.moodle.org/ Moodle Tracker] under [http://tracker.moodle.org/browse/CONTRIB CONTRIB].
*'''Documenting code''' - You can maintain helpful documentation of the features and installation instructions in [https://docs.moodle.org Moodle Docs]
*'''Distributing code''' - You can help others find your code by adding an entry to the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]
*'''Discussing the code''' - You can discuss the functionality and answer questions about how to use your code in the [http://moodle.org/course/view.php?id=5 Using Moodle forums]. Users can ask questions, discuss possible ideas for improvement, etc. Once the discussion matures to a point where you may want to take action, then you can create an issue in the [http://tracker.moodle.org/ Moodle Tracker].
*'''Maintaining code''' - You can further develop your code by fixing issues, adding features, and responding to other issues with the [http://tracker.moodle.org/ Moodle Tracker]. Each plugin or patch can have its own component in the CONTRIB project; however, you will need to request that the component be created in the CONTRIB project. Once created, users can easily create issues related to your contributed code. The primary maintainer of the code will be assigned as the component lead and have their tracker privileges bumped so that they can manage issues related to their contributed code. Those issues will automatically be assigned to the component lead/primary maintainer.

==The CONTRIB Frequently Asked Question (FAQ)==
'''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 [https://docs.moodle.org/en/Pedagogy Moodle's social constructionist pedagogy].

As mentioned, there are various tools to help you share and support your contribution. By using a consistent methodology, your Moodle related code will 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 your contributed code.

==How to submit code==
You have created some code that you would like to contribute to the Moodle community. The first step is to choose which Git code hosting site you want to use. Both [http://github.com/ github.com] and [http://gitorious.org/ gitorious.org] are popular. Follow the instructions for creating a public repository for your code. This will allow others to download your code as well as suggest possible patches. As you become more familiar with collaborating with others you can also control who else you want to be able to push changes into your repository (i.e. write access).

In order to facilitate a common naming convention of Moodle related repositories, it is suggested that you use the following format: 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.

==How to request that your code be tested/reviewed==

#If you do not already have an account on the [http://tracker.moodle.org] Moodle Tracker], create one and login.
#Create a new "Task" issue in the "Non-core contributed modules" project. Your issue will be a request that the code be tested and reviewed.
#Provide the link to the repository (i.e. https://github.com/arborrow/moodle-block_birthday)
#Provide a clear description of what the code does and the functionality that it adds to Moodle.
#Provide any other links to supporting documentation

The Contrib Coordinator will then work directly with the code contributor via the Tracker to help evaluate the code, work on resolving any questions/issues found, etc.

*Contributors are encouraged to follow Moodle's coding guidelines [[Coding]].

*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.

*Contributors are encouraged to associate each change made to an issue in the tracker. This practice is done by Moodle core developers and it is a good habit to get into so that you can go back and see why various changes were made to the code. Simple practices like these help to create good documentation of the code as it develops and matures. Commits should begin with the Moodle tracker issue number followed by a brief description of the change.

==How to provide documentation==
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.

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.

Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.

===Possible format for a contributed code Moodle Docs page===
You can copy and paste the below into your Moodle documentation page. Please add the URL links. '''This is only a suggestion'''.
Start with a 2-4 line introduction. The Plug In Name works with the activity module.
It makes the life of the teacher easier by ...
==Features==
* Add features list or overview description here <nowiki> </nowiki>
<nowiki> [[Image:Sample_screen_shot|thumb|500px|center|Title of screenshot]]</nowiki>
==Installation==
Place install instructions here
==Tips and tricks==
*Optional section, usually added by users later
==See also==
*[Place http_address_for_M&P_entry_here Name of Entry here] is a Modules and plugins database page that has download links and more information.
*Discussions: [Place http_address_for_moodle_forum_or_thread_here Name of forum]

When no thread or forum exists for discussion, put a link to the Contributed Code forum.
*Discussions: Please create or find a discussion topic in the <nowiki>[http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]</nowiki>

==Share code with modules and plugins database==
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.

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.

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.

==Support code and get feedback with forums==
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.

*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects.
*[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. Similarly, to respect the modular nature of Moodle if a block requires a library it is usually preferred to keep it as a subdirectory in the block's folder. This can be especially helpful if your code is dependent upon a particular version of an external library.

=== 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.

=== Does 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==

*[[Migrating contrib code to 2.0]]
*[[contrib]] CONTRIB is an area in the Moodle CVS
*[[Translation]] for information on the translation of contributed code
*[[Overview]]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion

[[Category:Guidelines for contributors]]

Talk:Process

2011-01-02T18:05:08Z

Aborrow: /* External developers */ new section

I think 'User' should be described as both 'finding issues' and 'suggesting improvements' for Moodle, even if the detail of how things are implemented are left for the Product Owner. Just thinking that a good chunk of the things I add to the Tracker are suggestions for improvement rather than 'issues' as such and that we should promote this idea as a general rule - maybe :)

:I agree with Mark. Bug tracker should be used for actual bugs. Discussion about future roadmaps, enhcnements and improvements is a separate matter, and in actual fact it is hard to engage in this. I don't have an answer at the moment. Maybe a place to discuss, and notification of when discussions have heated up (like specs are being prepared and a new roadmap developed for a component) ie owners manage the discussion, but there is a clear place to go to engage, some indication of timelines etc. --[[User:Derek Chirnside|Derek Chirnside]] 19:39, 25 November 2010 (UTC)

Well, "issues" there was meant to cover "bugs" and "suggestions", as the tracker does both. I'll make it more explicit though. [[User:Martin Dougiamas|Martin Dougiamas]] 10:12, 30 November 2010 (UTC)

OK - I could live with this. But I still prefer this clearer distinction as suggested by Mark:

===User role===

# Uses Moodle
# Finds issues/bugs (report in tracker)
# Suggests improvements (report in tracker)

Question: is there a way in the tracker to keep issues in two lists: bugs and suggestions? Maybe even like Google: you can suggest anything, but at any given time there are a few suggestions up for vote? In Moodle, you can discuss anything, but someone is highlighting at any given time a few topics for focused discussions. On reflection the answer may be No - on this basis I am back to my original suggestion.

A bug is a bug - it is not working as we know it should. A suggestion for an enhancement is partly an invitation to dialogue, vote. Voting for bugs is silly - all bugs need fixing, and priorities are best (IMO) determined centrally. So:

#Uses Moodle
#Finds and reports bugs (use tracker)
#Suggests improvements (use tracker)
#Takes part in dialogue around suggested improvements

[[User:Derek Chirnside|Derek Chirnside]] 06:18, 4 December 2010 (UTC)

:Derek, thanks for your comments. Regarding a way in the tracker to keep issues in two lists: bugs and suggestions, when you create an issue you have a choice of issue types - bug, new feature, task and improvement. Thus, a search for all new features and improvements should generate a list of suggestions. --[[User:Helen Foster|Helen Foster]] 14:31, 4 December 2010 (UTC)

== Backlog naming ==

Regarding the latest change about naming backlog versions with "STABLEBACKLOG/DEVBACKLOG", I'd recommend to use instead something like: "1.9.x backlog/2.0.x backlog/2.1.x backlog" because:

# It saves us to move things when a new major release happens (so it won't be necessary to move all the DEVBACKLOG => STABLEBACKLOG".
# It supports '''multiple''' stable branches, like we have now (1.9.x, 2.0.x...)
# It respects the format used by both the Affected Branches and Fixed Branches custom fields that are really useful for a lot of filters.

Ciao, [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 23:33, 6 December 2010 (UTC) :-)

:Addenda: Finally it has been decided to go to 2 backlogs only (stable/dev). Fair enough so developer (team) will look to the real branches were solution needs to be implemented. [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 10:23, 9 December 2010 (UTC)

==This does not look like scrum to me at all==

I think we need a certified scrum master. This proposal IMHO seems to break nearly all the good Scrum practises described in books.

Ciao, [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 10:03, 9 December 2010 (UTC)

:Agree! some points (see point 3 especially, both in STABLE/DEV teams, break the thing. It's (scrum, by team) master responsibility to discuss with product owner, not team itself! Isolation is a MUST.

: Ciao, [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 10:12, 9 December 2010 (UTC)

----

== If the issue is a bug in the current stable version requiring database changes, assign "Fix version" to DEVBACKLOG ==

Hmm, maybe this should be governed up by bug severity too? You, sure, aren't going to say that every bug requiring DB update, however severe it is, should be left up to the next major release? --[[User:Oleg Sychev|Oleg Sychev]] 14:51, 9 December 2010 (UTC)

I understand the idea of pulling from the items with the highest priority; however, how are we going to determine that priority. We have issue severity which has traditionally been seen as a priority indicator but we also have the number of votes. I am curious when paper cuts will be taken care of. These smaller issues can impact the user experience. I suspect in an ideal world, all the major issues will be dealt with but occasionally some simple fixes come along with patches in the tracker and it would be good to get those applied. Peace - Anthony

: Well, in practice I expect people will choose items based on a cost/benefit analysis of fixing them - just like they always have in the past.--[[User:Tim Hunt|Tim Hunt]] 18:14, 16 December 2010 (UTC)

== Suggested changes for "External Developers" ==
I had a really good conversation with David (He posted a screenshot that maybe does a better job of explaining what is described below: http://picasaweb.google.com/david.mudrak/Moodle#5551427587739059122), and we discussed one possible suggested workflow external developers can use if they choose to use their own GIT repo. Here's how it would break down:

=== Creating repo ===
==== Branch off MOODLE_20_STABLE (ie: UCLA_TRUNK) ====
$ git --bare fetch git://git.moodle.org/moodle.git MOODLE_20_STABLE:MOODLE_20_STABLE
$ git checkout -b UCLA_TRUNK origin/MOODLE_20_STABLE

==== commit customizations into branch ====
$ ... (hack something, git add, git commit)
$ git push

=== Contributing back ===
==== Create another branch off MOODLE_20_STABLE (ie: COOL_NEW_FEATURE) ====
$ git --bare fetch git://git.moodle.org/moodle.git MOODLE_20_STABLE:MOODLE_20_STABLE
$ git checkout -b COOL_NEW_FEATURE origin/MOODLE_20_STABLE

==== git cherry-pick to selectively pick commits from UCLA_TRUNK to merge into COOL_NEW_FEATURE ====
$ git cherry-pick 7300a6130d9447e18a931e898b64eefedea19544

==== publish branch COOL_NEW_FEATURE ====
??

==== create pull request in tracker ====
http://tracker.moodle.org/browse/PULL-18

If accepted, it becomes part of core moodle

=== Updating to next version of Moodle ===
$ git pull

== Contrib Code - Development process ==

I think this may be a good time to give some thought to coming up with the process we want to implement and enforce for sharing CONTRIB code. What assumptions do we want to make from the beginning? Should shared code be in a git repository somewhere? We have folks that share everything from zip files of plugins, some use Google code, others may use git. My experience has been that many are not initially proficient at using CVS/GIT, etc. although this seems to be improving. In any case, I would love to see a clear diagram about what someone does when they create code that they want to share. It has worked well to initiate conversations in the tracker as I can them work them through the Guidelines for CONTRIB Code (https://docs.moodle.org/en/Development:Guidelines_for_contributed_code) but I think we need to update that now for how we want to handle things in the future. Perhaps the improved M&P database will be the point of first contact. In any case, I would love to see if we could create a page similar to the Development:Process called something like Development:CONTRIB process. Peace - Anthony

== External developers ==

I have a question about the historical integrity of providing patches via links. For external developers, we say "Suggest code via links in comments in Jira". What happens if those links no longer work? Perhaps this is a trivial issue and will in practice hardly ever happen but I was thinking about going back to an older issue that it may be helpful to see an approach that was attempted but rejected. If the external developer removes the branch, then it would seem to me that perhaps their rejected patch would no longer be available to be reviewed later. Am I understanding this properly and if so, might we consider what the approach might be for getting patches in the tracker so that they can stay there? Peace - Anthony

Talk:Process

2010-12-26T01:20:41Z

Aborrow: /* Contrib Code - Development process */ new section

Talk:Process

2010-12-16T17:28:37Z

Aborrow:

Talk:Overview of the Moodle question engine

2010-11-25T21:41:07Z

Aborrow: New page: Tim - Two areas that I keep in the back of mind are outcomes and tags. Can we tag certain questions as being related to a particular objective? Generally speaking, an activity provides a...

Tim -

Two areas that I keep in the back of mind are outcomes and tags. Can we tag certain questions as being related to a particular objective? Generally speaking, an activity provides a way for teacher to grade whether a student has demonstrated a particular outcome. I think it might be nice if the question engine could do some of outcome assessment automatically. For example, student able to multiple single digit numbers.

I am curious if you think that the question engine should connect specific questions to a particular outcome. I am thinking of how a student's correctly answering a particular quiz question could be used to demonstrate an outcome.

To the contrary, a good argument can be made about putting too much wait on a particular question. Instead of the question determining the outcome, it would be a series of questions whereby the student's performance on a quiz of questions determines the outcome score thus maintaining the current correlation between outcomes and a particular activity.

In any case, as I looked at the proposal for the new question engine outcomes and tags were a couple of areas where I might anticipate some questions. The question of tagging (courses, activities, questions, resources, etc.) is really a separate issue that I think best dealt with on its own. The more I think about outcomes, I think there is good justification for not trying to associate them with individual questions.

Peace - Anthony

Talk:Question Engine 2

2010-11-25T08:17:57Z

Aborrow: New page: Tim - Do you envision Question Engine 2 being able to lay a foundation for what is commonly referred to as computer adaptive testing? Peace - Anthony

Tim - Do you envision Question Engine 2 being able to lay a foundation for what is commonly referred to as computer adaptive testing? Peace - Anthony

Migrating contrib code to 2.0

2010-09-02T21:46:32Z

Aborrow:

{{Moodle 2.0}}

WARNING: Under construction RIGHT NOW!

The goal of this page is to provide a checklist of tasks to be considered to upgrade CONTRIB code to Moodle 2.0. Several significant changes have taken place including the File API, DB Layer, Navigation, Output renderer, etc. It would be good if we had a list that contributors could follow to help move them toward being able to migrate the code. Any help in building up this list is greatly appreciated.

''Please add useful links...''

* [[DB_layer_2.0_migration_docs]]
* [[Using the File API in Moodle forms]]
* [[Output_renderers]]
* [[Migrating_your_code_to_the_2.0_rendering_API]] (n.b., some info outdated and may need updating)
* [[Themes_2.0]]

Some details of how to re-design image CSS for plugin code ar in the main themes documentation: [[Themes_2.0_creating_your_first_theme#Using_images_within_CSS]]

Be aware that themes are now cached on the server and so emptying your browser cache will not refresh the CSS. This can only be done by going to the site administration->appearance->themes->theme selector page and clicking the 'invalidate theme caches' button.

Javascript is included in different ways now and will need to be migrated, see the PHPDoc comments in /lib/outputrequirements.lib and some (slightly outdated) advice here: [[JavaScript_guidelines]]

There are other coding changes such as:
* MDL-24063 which eliminates PARAM_CLEAN
* MDL-24058 about no longer using stripslashes or addslashes

Please feel free to add others that come to mind. CONTRIB maintainers should check their 2.0 versions for these and make sure that they are appropriately handled.

==See also==

* CONTRIB-1988
* http://cvs.moodle.org/moodle/blocks/upgrade.txt?view=markup
* http://cvs.moodle.org/moodle/mod/upgrade.txt?view=markup

Modules and plugins improvements

2010-07-03T01:02:35Z

Aborrow:

The Modules and Plugins database provides a convenient way for Moodle System Administrators to search for available plugins, patches, and tools to enhance their installation. While the basic structure has been reasonably helpful, there is much to be desired in order to help those administrators determine things like the quality of the code, the reliability of the code, and the popularity of the code. This page is to help identify the areas needed for improvement and to provide a path for implementing those improvements.

For example, I would like for there to be various code quality levels (perhaps with gold, silver and bronze medals). The first level (bronze) would be verifying that the code has been independently tested by a Moodle developer, Moodle Partner or PHM to verify that the program at least appears to do what it says by someone of some repute. To say that the code is verified means that the code appears to work without any obvious bugs, PHP warning/notices, etc.

The silver medal indicate that the code is "Moodle certified" which would mean that a Moodle developer or Moodle Partner has not only verified the functionality of the code but also the quality of the code. Certification would mean that the code conforms to Moodle's coding guidelines and basic security practices. Those wishing to have their code certified, could contact a Moodle Partner similar to how we handle the MCT. Code certification could be a service that Moodle Partners provide to allow developers in the community an opportunity to work with more experienced developers on how to improve their code. The goal would be to get the code certified; however, this would depend upon the complexity of the project as to how many hours of time a developer would have to work with them. Code certified by a Moodle Partner would indicate that the quality of the code has been reviewed by an experienced developer and that it is production ready. By certifying the code, the Moodle Partner is making a statement that they would feel comfortable running the code on their production servers (not that they would have to).

Perhaps we could also develop a Moodle Certified Developer (MCD) which would mean that they have completed the Moodle Developer Course under the tutelage of a Moodle Partner and demonstrated the ability to code well according to Moodle coding guidelines. Those reviewing code may need to have some specialized training from Petr to ensure that basic security protocols are being followed.

The gold medal would indicate that the code has been tested, reviewed, and that a special evaluation of the code's security has shown it to meet the same high standards of security as Moodle core. Secured code has been verified, certified, and also given a review by a security specialist (most likely Petr) to ensure that the code is unlikely to have any known security vulnerabilities. Here, I envision a Moodle Partner requesting that Petr review the code or training someone on their team to specifically identify potential security issues. A gold medal would indicate that the code would be ready to move directly into core (again, not that it would but the quality of the code is such that it could).

In addition to the code status indicator which serves as a type of quality assurance, it would be good to have popularity ratings. These should incorporate not only the number of downloads (from http://download.moodle.org/stats.php) but also the ratings that users give them. I would like to see some type of algorithm that would adjust the popularity based not merely on the average rating but also on the number of ratings such that the more popular plugins would outrank the less popular but highly rated ones.

Personally, I would like to receive an email with information about any new M&P entries. I would like to be able to filter the entries by various criteria and be able to do things like send a bulk message to all of those whose code is not on the Moodle CVS server (i.e. the download link does not contain http://download.moodle.org/download.php). As an aside, I am trying to ensure that I start adding the M&P entry URL to the component description to facilitate moving between the tracker and the M&P entry to discussions, Docs, etc.

Please continue to add ideas, hopes, etc. as to how the Modules and Plugins database can become a more useful tool not only for those who maintain it but also for those who make use of it, either here or in the [[Development_talk:Modules_and_plugins_improvements | page comments]]

Part of what makes a plugin reputable is how quickly issues are responded to. I would want to be able to assess someone how actively the code is being maintained. We have a number of possible pieces of data but I do not know how we could calculate things in a meaningful way. The average time difference between when an issue is created and resolved might be helpful. Good code will not have many issues and thus not much activity; however, high activity indicates that it is actively being worked on. Drupal provides some of this information about its modules.

In summary, here are some of the features that I think we are hoping for:

* Popularity (number of download, number of views, number of installations) - I would like to see us gather more information from site registrations to learn what contrib code is actually installed. This would help if a major security issue is discovered in contrib that we could send an email just to those site admins without alarming the whole community.
* Ratings (should there be a distinction between ratings given by a typical user vs. a developer rating?)
* Comments (need to make clear that comments are not for reporting bugs, that is what the Tracker is for)
* Filtering - It needs to be easier to filter and sort contrib code by version, type, popularity)
* Quality assessment (functionality, coding guidelines, security, performance, UI)
* Status - Is the code being actively maintained? How can we assess this?

Demo sites - Stuart Mealor shared with me a site (http://www.elearning.school.nz/) he set up that can serve as a bit of a demo site for CONTRIB code. I like the idea of having a CONTRIB demo site which folks could use to experiment with different plugins. It would be also interesting to have a patch demo site; however, each one would have to be it's own installation but it should not be too difficult to setup some automation of that. Besides demo (which should use the latest stable code), it would be good to have something similar for HEAD as a test site that also pulls the latest code from CVS.

==See also==

* MDLSITE-571
* MDLSITE-406

Plugin contribution

2010-06-30T23:48:20Z

Aborrow: /* Does the file structure conform to Moodle standards? */

This page describes the various ways to share and work collaboratively on contributed code.
#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==
'''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.

==How to submit code==
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.

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

==How to work with code in CVS==
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.

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)]].

:''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.

: Another IDE with CVS support is [[Setting_up_Netbeans|NetBeans]].

==How to provide documentation==
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.

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.

Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.

==Share code with modules and plugins database==
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.

By way of example, if you have a CONTRIB plugin block called birthday, the preferred download link would be http://download.moodle.org/download.php/plugins/blocks/birthday.zip for the HEAD branch. For the MOODLE_19_STABLE branch, the URL would be http://download.moodle.org/download.php/plugins19/blocks/birthday.zip. Please note that the download.php is important as that is used to help produce the [http://download.moodle.org/stats.php download stats].

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.

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.

==Support code and get feedback with forums==
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.

*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects.
*[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. Similarly, to respect the modular nature of Moodle if a block requires a library it is usually preferred to keep it as a subdirectory in the block's folder. This can be especially helpful if your code is dependent upon a particular version of an external library.

=== 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.

=== Does 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==

*[[Migrating contrib code to 2.0]]
*[[contrib]] CONTRIB is an area in the Moodle CVS
*[[Translation]] for information on the translation of contributed code
*[[Overview]]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion

[[Category:Guidelines for contributors]]

Plugin contribution

2010-06-30T23:42:40Z

Aborrow: /* Does the file structure conform to Moodle standards? */

This page describes the various ways to share and work collaboratively on contributed code.
#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==
'''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.

==How to submit code==
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.

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

==How to work with code in CVS==
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.

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)]].

:''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.

: Another IDE with CVS support is [[Setting_up_Netbeans|NetBeans]].

==How to provide documentation==
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.

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.

Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.

==Share code with modules and plugins database==
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.

By way of example, if you have a CONTRIB plugin block called birthday, the preferred download link would be http://download.moodle.org/download.php/plugins/blocks/birthday.zip for the HEAD branch. For the MOODLE_19_STABLE branch, the URL would be http://download.moodle.org/download.php/plugins19/blocks/birthday.zip. Please note that the download.php is important as that is used to help produce the [http://download.moodle.org/stats.php download stats].

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.

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.

==Support code and get feedback with forums==
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.

*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects.
*[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. Similarly, to respect the modular nature of Moodle if a block requires a library it is usually preferred to keep it as a subdirectory in the block's folder.

=== 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.

=== Does 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==

*[[Migrating contrib code to 2.0]]
*[[contrib]] CONTRIB is an area in the Moodle CVS
*[[Translation]] for information on the translation of contributed code
*[[Overview]]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion

[[Category:Guidelines for contributors]]

Talk:Modules and plugins improvements

2010-06-15T12:18:23Z

Aborrow: /* Tags */ new section

Anthony: I agree that this would be very helpful. Three suggestions:
* We should look at how other GNU web applications which have high rates of community contributions work, for example Drupal, MediaWiki, and WordPress. Perhaps a page (or section) of "Lesson's learned" from these projects would be useful for this discussion.
* I think it would be a good idea to expand the list of possible reviewers so that it does not focus too much only only the employees of Moodle.com (and I suspect that most of them would agree as well). Perhaps a way to do this is to have greater weight be given to those who have either contributed already certified code (that could include partners,HQ staff, or other contributors), or who have given effective reviews of a number of other modules, etc. To not discourage new-comers in the process, perhaps an review may need three net positive votes, where a new-comer can give one vote, but a pre-certified individual could give two or three votes, etc.
* Obviously, we need to keep it simple and not make the certification process too difficult. One way to do that may be to have a Wiki page on each contribution, and people could use the page comments to offer their reviews. Those wanting their contribution to be certified could solicit review. Before certification was given, they would need a certain amount of positive feedback, and all concerns raised in the feedback would need to be addressed (either with a fix or with a discussion that attempted to reach a consensus on any issues raised).--[[User:Gary Anderson|Gary Anderson]] 17:33, 26 April 2009 (UTC)

== Many thanks Gary for your feedback and ideas. ==

* I will be attending the http://sf2010.drupal.org/conference/unconference so that I can meet with some of the Drupal folks. I am trying to get feedback from other open source projects and will create a lessons learned section or what I'm hearing from others.
* Your ideas here make me wonder if we need to have a Moodle Certified Code Reviewer similar to the MCT program. The challenge here is what is understood by code review and keeping it very specific and measurable. One argument I would anticipate hearing back would be just because someone shares code or has written code does not mean that they are writing good code. Since the purpose of code review is quality control, we need to be as clear as possible on the evaluation process and what the various ratings meeting.
* I like the idea of looking at the responsiveness of the contributor to issues but think expecting all issues to be addressed is probably not realistic. But it is important that contributors be responsive to user input by responding even if the decision is made to not fix or implement a suggestion.

== Tags ==

At the 2010 OKMoot the idea came up of adding tags so that it would be easier to see groups of plugins (for example question types). I believe the current system already has this somewhat but we may want to improve the UI. Peace - Anthony

Migrating contrib code to 2.0

2010-04-26T14:41:22Z

Aborrow:

Migrating contrib code to 2.0

2010-04-26T14:39:26Z

Aborrow:

Migrating contrib code to 2.0

2010-04-26T14:38:07Z

Aborrow:

Migrating contrib code to 2.0

2010-04-26T14:33:50Z

Aborrow:

Migrating contrib code to 2.0

2010-04-26T14:29:25Z

Aborrow:

Migrating contrib code to 2.0

2010-04-26T14:28:45Z

Aborrow:

{{stub}}{{Moodle 2.0}}

WARNING: Under construction RIGHT NOW!

The goal of this page is to provide a checklist of tasks to be considered to upgrade CONTRIB code to Moodle 2.0. Several significant changes have taken place including the File API, DB Layer, Navigation, Output renderer, etc. It would be good if we had a list that contributors could follow to help move them toward being able to migrate the code. Any help in building up this list is greatly appreciated.

''Please add useful links...''

* [[Using the File API in Moodle forms]]

==See also==

* CONTRIB-1988

Talk:Automated Manipulation of Strings 2.0

2010-04-10T20:59:18Z

Aborrow: /* Automatic translation of new strings into existing language packs */ new section

Nice spec David!

There should be some kind of administration page available:
* administer translators rights to edit a specific language pack
* create new language packs
--[[User:koen roggemans|koen roggemans]] 08:36, 19 February 2010 (UTC)

:: Thanks for these points, Koen. --[[User:David Mudrak|David Mudrak]] 18:41, 19 February 2010 (UTC)

== Automatic translation of new strings into existing language packs ==

I'm excited about the general direction that this heading in. I realize that automatic/computer-based translation of strings often lags or lacks quality; however, I thought it might be a nice feature to serve as a starting place for a translation by default. For example, I recently read an article about vast improvements made with the Google translator. My thinking is that this would at least provide a starting place for a translator to come in and then improve upon the auto-generated translation by offering a human translation. I'm thinking especially with CONTRIB this could be useful as someone in Brazil writing a module could have strings automatically translated into the existing language packs (or at least for which such automation might be practical). Then those strings could be cleaned up as needed. Peace - Anthony

Talk:Modules and plugins improvements

2010-03-27T13:43:40Z

Aborrow: /* Many thanks Gary for your feedback and ideas. */ new section

Plugin contribution

2010-03-03T16:57:54Z

Aborrow: /* Share code with modules and plugins database */

This page describes the various ways to share and work collaboratively on contributed code.
#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==
'''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.

==How to submit code==
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.

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

==How to work with code in CVS==
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.

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)]].

:''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.

: Another IDE with CVS support is [[Setting_up_Netbeans|NetBeans]].

==How to provide documentation==
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.

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.

Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.

==Share code with modules and plugins database==
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.

By way of example, if you have a CONTRIB plugin block called birthday, the preferred download link would be http://download.moodle.org/download.php/plugins/blocks/birthday.zip for the HEAD branch. For the MOODLE_19_STABLE branch, the URL would be http://download.moodle.org/download.php/plugins19/blocks/birthday.zip. Please note that the download.php is important as that is used to help produce the [http://download.moodle.org/stats.php download stats].

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.

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.

==Support code and get feedback with forums==
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.

*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects.
*[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.

=== Does 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==

*[[contrib]] CONTRIB is an area in the Moodle CVS
*[[Translation]] for information on the translation of contributed code
*[[Overview]]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion

[[Category:Guidelines for contributors]]

Plugin contribution

2010-03-03T16:56:38Z

Aborrow:

This page describes the various ways to share and work collaboratively on contributed code.
#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==
'''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.

==How to submit code==
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.

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

==How to work with code in CVS==
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.

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)]].

:''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.

: Another IDE with CVS support is [[Setting_up_Netbeans|NetBeans]].

==How to provide documentation==
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.

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.

Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.

==Share code with modules and plugins database==
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.

By way of example, if you have a CONTRIB plugin block called birthday, the preferred download link would be http://download.moodle.org/download.php/plugins/block/birthday.zip for the HEAD branch. For the MOODLE_19_STABLE branch, the URL would be http://download.moodle.org/download.php/plugins19/block/birthday.zip. Please note that the download.php is important as that is used to help produce the [http://download.moodle.org/stats.php download stats].

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.

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.

==Support code and get feedback with forums==
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.

*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects.
*[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.

=== Does 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==

*[[contrib]] CONTRIB is an area in the Moodle CVS
*[[Translation]] for information on the translation of contributed code
*[[Overview]]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion

[[Category:Guidelines for contributors]]

Setting up Eclipse

2009-12-22T22:16:57Z

Aborrow: /* Troubleshooting */

[http://www.eclipse.org/ Eclipse] is an IDE originally designed for Java, but now with plugins for many languages including PHP. It has lots of very powerful features, and it is the editor that some Moodle developers like to use. Other (more) popular choices are vim and emacs.

However, Eclipse is not the easiest program in the world to get started with, so I'm going to take you through it step by step. These instructions assume Eclipse 3.2, the current version at the time of writing. It should not change much between releases.

This article started off as a brain-dump by [[User:Tim Hunt|Tim Hunt]]. Since then, several other people have worked through it and made corrections, so the information here should be pretty accurate.

Since this page was written, Eclipse 3.3 and 3.4 have been released, along with a new PHP plugin called PDT, which is better, but uses more memory. You can download an all-in-one Eclipse+PDT from http://www.eclipse.org/pdt/downloads/. The following instructions, from the section [[#Setting_the_preferences_for_Moodle_development]] mostly still apply after you have done the install, but some of the details are a bit different.--[[User:Tim Hunt|Tim Hunt]] 07:30, 31 January 2009 (CST)

==Prerequisites==

Eclipse is written in Java, so I recommend getting the latest Java runtime environment from http://java.com/ for maximum speed and reliability.

Eclipse is quite big, so I recommend lots of memory in your computer. I have used it on Windows, MacOS X and Linux, in each case with 1GB of memory, and that is plenty.

==Installing Eclipse==

Go to http://www.eclipse.org/downloads/. Click on the link corresponding to your operating system where it says '''Eclipse Classic'''. Choose a Mirror, and wait for the ~100MB download.

You will notice that what you have got is a zip file (unless your system automatically decompresses it for you).

On Windows, unzip it into '''C:\Program Files''' (all the files go into an '''Eclipse''' folder there). Then look in the Eclipse folder and drag Eclipse.exe to the Start menu/Desktop/Quicklaunch bar to make a shortcut for starting it.

On MacOS, unzip and copy the Eclipse folder into Applications. Go into the Eclipse folder and drag the Eclipse app to the Dock for ease of launching.

On Linux, unzip somewhere suitable, and make an easy way to launch it.

==The first time you run Eclipse==

The first time you launch Eclipse it does a bit of setup stuff, for instance, it creates a '''workspace'''. This is where it stores the things you are working on. The default location is sensible on all platforms, so use that.

For some reason, every time you start Eclipse, it asks you which workspace you want to use. I have never seen the need to have more than one, so I recommend turning on the checkbox that says "Use this as the default and do not ask again".

Another thing that happens the first time you run Eclipse is that you arrive at a welcome screen. This has links to various bits of help, which you can read if you like, but you probably don't need to if you are following these instructions. So find the button on the welcome page that closes it and gets you to the main Eclipse screen.

==Installing the necessary plugins==

By default, Eclipse comes with the Java tools. For everything else you will need to install some plugins.

If you are sitting behind a web proxy, from the '''Window''' menu choose '''Preferences ...'''. Choose '''Install/Update''' from the tree view on the left, and enter the proxy information in the boxes on the right. If you aren't behind a proxy, ignore this step. (On Eclipse 3.4.0 on OSX this is in '''Eclipse > Preferences > General > Network Connections''')

From the '''Help''' menu choose '''Check for Updates'''.

On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click '''Next >'''.

The next screen is a list of upgrade sites to check. You need to add one to the list, so click the '''New Remote Site ...''' Button.

In the pop-up dialog, give the remote site a name like '''PHPeclipse Update Site'''; set the URL to http://update.phpeclipse.net/update/nightly; then click '''OK'''. Click '''Finish'''. Under '''PHPEclipse Nightly Builds''', check '''PHPeclipse'''. Click '''Finish'''. Wait while it downloads (this may take a few minutes). Click '''Install'''. You will be prompted to restart Eclipse, click '''Restart'''.

''Note, there is now also another PHP editor for Eclipse. The update URL ishttp://download.eclipse.org/tools/pdt/updates/. I am just trying it--[[User:Tim Hunt|Tim Hunt]] 11:39, 7 November 2007 (CST)''

Restart the wizard (from the '''Help''' menu choose '''Software Updates -> Find and Install''').

On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click '''Next >'''.

Select just two things in the box "Sites to include in search":
* Your newly created '''Phpeclipse Update Site'''; and
* the one called '''Europa Discovery Site''' (or possibly '''Callisto Discovery Site''').
Then click '''Finish'''.

It goes off and sees what updates are available at those sites. As it does so, it may occasionally pop up a dialog asking you to choose a mirror. Each time, select a sensible one.

Eventually, you get to a new wizard for selecting and installing the updates you want (Select the features to install). The ones you want (you may have to expand and search the tree structure) are: all the '''PHPEclipse Nightly Builds''' (from your newly created PHPEclipse Update Site) and the '''Web Standard Tools (WST)''' (usually under Callisto or Europa Discovery Site --> Web and J2EE Development).

Next, and very importantly, you must click the '''Select Required''' button which should resolve dependencies and remove the warning message you are probably worrying about. Then you can click the '''Next >''' button.

Read and agree to all the license agreements. Then click '''Next >'''.

Click '''Finish''', and wait for the plugins to download.

Once the downloads have finished, a warning will pop-up telling you that all the plugins you downloaded are not digitally signed. The Eclipse Foundation built digital signing of plugins into their architecture as a security measure, and then did not sign any of their own plugins! Anyway, click the '''Install All''' button.

Finally, a window will pop up asking you to restart Eclipse. Do so.

==Setting the preferences for Moodle development==

Now go to the '''Window''' menu, and choose '''Preferences ...''' ('''Eclipse''' menu on Mac OS X).

The Eclipse preferences are immense, with a tree view on the left, which selects which screen to display on the right. Don't panic, we'll guide you through it.

===General settings===

If you have strong feelings about fonts (I would hate to edit code an anything except Andale Mono), choose '''General -> Appearance -> Colors and Fonts''' from the tree on the left. Then on the right look under '''Basic''' and change '''Text Font'''. All the other editor font settings will inherit from this, so this is probably the only one you have to change.

Under '''General -> Content Types''', select PHP Source File, and add '''*.html''' to the box at the bottom.

Under '''General -> Editors -> File Associations''', if it is not already there, add '''*.php''' to the top box. With '''*.php''' selected in the top box, make sure '''PHP Editor''' is set to default in the bottom box (use the '''Default''' button - the default will appear at the top of the list).

With '''*.html''' selected in the top box, if it is not already there, add '''PHP Editor''' to the bottom box. Then select '''PHP Editor''' in the bottom box and click the '''Default''' button to change it, because in Moodle, most HTML files actually contain PHP code.

If you use a web proxy, enter the details under '''Network Connections'''. (Yes, I know you have entered them somewhere else before. Now you have to enter them again here. I don't know why. You just do.)

===PHP Settings===

Under '''General -> Editors -> Text Editors''', check '''Show line numbers''' to display line numbers in the left margin (optional). Click '''Apply'''. (When you are editing a PHP file, you could left-click in the left margin and tick the '''Show Line Numbers''' line in the contextual menu. However, this toggle only applies to plain text files, ''not'' to HTML or PHP files. The only place where you can toggle line numbers on/off for such files is in the PHP/Appearance menu.)

Under '''PHPeclipse -> Browser Preview Defaults''', turn off all checkboxes (if necessary). Click '''Apply'''.

Under '''PHPeclipse -> PHP''', on the '''Appearance''' tab, set '''Displayed tab width''' to 4 (if necessary). Click '''Apply'''.

Under '''PHPeclipse -> PHP''', on the '''Typing''' tab, turn off all the options except '''Pasting for correct indentation''', '''Insert spaces for tab''' and '''Close PHPdocs and comments'''. Click '''Apply'''.

Under '''PHPeclipse -> PHP -> Editor''', turn on '''Remove trailing spaces on editor save'''. Click '''Apply'''.

Under '''PHPeclipse -> PHP -> Formatter''', on the '''New Lines''' tab, turn on '''Clear all blank lines'''. Click '''Apply'''.

Under '''PHPeclipse -> PHP -> Formatter''', on the '''Style''' tab, turn off '''Indentation is represented by a tab'''. Click '''Apply'''.

Under '''PHPeclipse -> PHP -> Templates''', I like to define a new template to help with debugging:
;Name
:dump
;Description
:Dump a PHP variable
;Pattern
<pre>print_object(${word_selection}${cursor}); // DONOTCOMMIT</pre>
You can do other useful things with templates too. Here are two more I use:
<pre>debugging("'${word_selection}${cursor}'"); // DONOTCOMMIT</pre>
<pre>$$string['${word_selection}${cursor}'] = '.';</pre>
That is, a simple debug message with a stack trace, and a new language string.

There is a really stupid bug. Under '''PHPeclipse -> Project Defaults''', you would like to add "." to the '''Include Paths''', but you can't using the GUI. You will have to edit one of the Eclipse config files by hand. So
# Note down the path to your Eclipse profile. On Windows it will be something like '''C:/Documents and settings/XXXX/workspace''', and on Unixy systems something like '''~/workspace'''.
# Close Eclipse.
# Open the file '''net.sourceforge.phpeclipse.ui.prefs''' that is in the directory '''(your workspace)/.metadata/.plugins/org.eclipse.core.runtime/.settings''' in a text editor.
# Look for a line in the file that starts '''_php_include_paths=''' If it is not there, add it at the end.
# Change this line to say '''_php_include_paths=.'''
# Run Eclipse again.

===SSH2===
Information about generating SSH2 keys for the purpose of connecting to cvs.moodle.org can be found here at https://docs.moodle.org/en/Development:SSH_key , but please finish reading this section before reading that material.

The Eclipse installation has its own SSH client plugin so you do not have to use a separate ssh client in connection with your use of Eclipse (this is one reason you will be using extssh below, instead of just ext, however, if you wish you may alter the configuration to use an external client but please post news of your success and configuration). See, http://www.jcraft.com/eclipse-cvsssh2/ , for additional information on this plugin.

'' Since Eclipse 3.0M6 the CVSSSH plugin is incorporated into Eclipse, [http://www.jroller.com/prane/entry/eclipse_3_0_cvs_support as "extssh" instead of "extssh2"] - --[[User:Olli Savolainen|Olli Savolainen]] 07:54, 23 June 2008 (CDT)''

Please note that Eclipse is fully equipped to generate ssh2 rsa and dsa keys as well as import keys. You may encounter issues with passphrases that are too long (a bug reportedly fixed but which may still in fact be present) and some issues with using keypairs generated by other applications have been seen, so it may be best to generate a key pair with Eclipse. Additional details on how to do this will be added.

Sourceforge, at http://sourceforge.net/docs/F02/ , provides instructions on how to create a SSH key for it's CVS (remember, Moodle does not use sourceforge for its CVS now and you will need to generate keys for cvs.moodle.org, not sourceforge). This is mentioned by way of general explanation, not for the purposes of providing instructions on how to generate your keys for Eclipse. To make use of the public key, login to Moodle.org and add it via the Update My Developer Information tab under CVS Developers (http://moodle.org/cvs). Remember, public keys provided to Moodle must be in the Openssh format.

===CVS Settings===

These are almost all hidden under the '''Team''' bit of the tree.

Under '''General -> Network Connections -> SSH2 -> Key Management''', you can set up a public/private key pair. If you do this, you won't have to keep typing your password when doing CVS operations.

The rest of the ones in this section are personal preferences, but I recommend them because the default settings are very irritating.

Under '''Team''', set '''Perspectives''' to '''None'''.

Under '''Team -> CVS''', on the '''Files and Folders''' tab, set '''Default text mode''' to '''ASCII with keyword expansion (-kkv)'''.

Under '''Team -> CVS -> Annotate''' set '''Use Quick Diff annotate mode for local file annotations''' to '''Yes''', and '''Open perspective after a 'Show Annotations' operation''' to '''No'''.

Under '''Team -> CVS -> Label Decorations''', switch to the '''Icon Decorations''' tab and turn on all the settings, and then on the '''Text Decorations''' tab change both '''File Decoration''' and '''Folder Decoration''' to be just '''{name}'''.

===Web and XML settings===

For each XXX in CSS, HTML, Javascript, XML:

Under '''Web and XML -> XML Files -> Source''', choose '''Indent using spaces''' and '''indentation size''' 4.

==Checking out the Moodle code==

From the '''File''' menu, choose '''New -> Project ...'''.

In the wizard that pops up, choose '''CVS -> Projects from CVS''', then click '''Next >'''.

Select '''Create a new repository location''', then click '''Next >'''.

Fill in
<div style="float: right; border: 1px solid orange; padding: 0 1em;">
For anonymous CVS access use
;Host
:XX.cvs.moodle.org
where XX.cvs.moodle.org is one of [[CVS_for_Administrators#CVS_Servers|these mirrors]]
;Repository path
:/cvsroot/moodle
;User
:anonymous
;Password
:(leave blank)
;Connection type
:pserver
</div>
;Host
:cvs.moodle.org
;Repository path
:/cvsroot/moodle
;User
:(your Moodle CVS username)
;Password
:(if you set up the SSH2 key thing in preferences, leave this blank, otherwise, type in your Moodle CVS password.)
;Connection type
:extssh
(CVS experts, if you are confused by that last one, know it is an Eclipse-specific thing.) Then click '''Next >'''.

On the next screen of the Wizard, choose '''Use an existing module'''. Wait a moment, then select '''moodle''' from the list. Click '''Next >'''.

On the next screen, make sure the option '''Check out as a project configured using the New Project Wizard''' is selected, then click '''Next >'''.

Click '''Refresh Tags''', then choose the branch you want. For now leave it set to '''HEAD'''.

Click '''Finish'''.

Now you will find yourself back at the start of the '''New Project''' Wizard. This is because of the option you chose three paragraphs ago. This time you should select '''PHP -> PHP Project''', then click '''Next >'''.

Make up a project name. '''moodle''' would be sensible.

Click '''Finish''', and wait while all the moodle files are checked out of CVS.

Once it has finished, it will probably ask you if you want to switch to the PHP perspective. Answer '''Yes'''.

If you also need another branch (1.6, 1.7, 1.8, ...) repeat all the other steps with a few changes:
* This time you can choose '''Use an existing repository location''' instead of typing all the sourceforge CVS details again.
* Select the appropriate branch. If you don't see the branch you want, see [https://docs.moodle.org/en/Development:Setting_up_Eclipse#Resetting_the_branch_information this Troubleshooting tip].
* Use a different project name (e.g. moodle16, moodle17, etc.).

==Let your development web server know where your files are==

Either by editing you web server's config files, or using a symbolic link. Make sure your webserver can see your new working set of files at a sensible URL, so you can test the code you are working on.

==Quick tour of some cool features, and remaining configuration changes==

I find the default workbench setup is pretty good. Here is a quick guide to some of the bits.

===Navigator===

To the left is the '''Navigator'''. This is a tree view of all your files. If you double-click on a file, it opens in the editor in the middle. Try opening '''course/lib.php''' now. You will notice that it comes up nicely syntax-highlighted.

===Error highlighting===

In the middle of the file, just type any old text, for example "I like Eclipse". Obviously, this is not valid PHP syntax, and Eclipse will notice this, and put a red underline under it. Also, by the scrollbar is a ruler with a red mark in it to show the error.

You will see some yellow marks lower down the ruler. There are warnings. Click on one, and you will be taken to where that warning is in the file. Hover your mouse over the warning, and you will get a tooltip explaining what the problem might be.

Save the edited file. (Don't worry that it is broken, we'll clean up the mess later.) Notice that a red error marker is added to the file in the navigator, so you can see that there is a problem. Also, error markers are added to the course folder, and the whole project, so you could see there was an error even if the navigator tree was collapsed.

You will probably find lots of warnings that the config.php file can't be found. In the navigator, find the file '''config-dist.php'''. Do '''Copy''' then '''Paste''' and choose to call the new file '''config.php'''. Edit this new config.php as normal. You should find that most of the include file warnings have gone now.

Notice also that there is another marker on each file icon. A little yellow cylinder on most files, but a white-on-brown star on the one you have edited. This is telling you the CVS status of each file. The brown stars are changes you have made but not checked in yet.

===Outline===

Over to the right is the Outline view. This shows a list of functions and classes defined in this file. By default, they are listed in the same order as in the file, but if you click on the '''az''' toolbar button, they are sorted into alphabetical order.

Click on the function name '''add_course_module''' in the Outline. You will see that the editor scrolls to the definition of that function.

===Code navigation===

In that function, hover the mouse pointer over the function name '''insert_record'''. After a while, the documentation for that function will appear in a big tooltip.

Hold down CTRL, move the mouse pointer over the function name '''insert_record''', then click. Eclipse should load '''dmllib.php''', and scroll you to where this function is defined.

In the main Eclipse toolbar, there are forward and back arrows like in a web browser. Click back now to get back to '''course/lib.php'''.

===Open resource===

From the '''Navigate''' menu, choose '''Open Resource...'''. In the dialog that pops up, start typing a filename for instance type '''moodlel'''. In the box in the middle of the dialog, you will see it list all the files in the project whose names start that way. At the bottom is a box which lists the different folders that contain a file with that name. This can be a very quick way of opening files with fairly unique names like moodlelib.php, without having to click through the levels of the navigator tree. Of course, it is not so useful for an index.php file! Click OK now to open moodlelib.php. (It would actually work if you just did CTRL + Shift + R, moodlel, Enter.)

===Multi-file search===

Scroll down moodlelib a little bit, and double click on the name of the constant '''MOODLE_INTERNAL''' where it is defined, so that the text is selected. Then, from the '''Search''' menu, choose '''Search...'''. Notice that the '''Containing text''' box has already been filled in for you with the text you just selected. Of course you can just type text into this box without selecting it first. Notice that you can do regular expression searches, but leave that turned off for now. In the '''File name patterns''' box type '''*.css, *.html, *.inc, *.js, *.php, *.xml'''. (This is the most useful general setting for working on moodle. Eclipse will remember this setting, so you only have to enter it once.) Click '''Search'''.

The search results will appear in a new view underneath the editor. That view has a toolbar with yellow up and down arrows. Click the down arrow a few times and it will take you to the first few matches in the code, opening the relevant files as necessary.

===Synchronize view===

I think this is my favorite feature. From the '''Window''' menu, select '''Show View -> Other...'''. In the dialog that pops up, select '''Team -> Synchronize''', then click '''OK'''.

This opens the Synchronize view below the editor. The view has a toolbar. Click on the first toolbar button, which pops up the Synchronize wizard.

On the first screen, there will probably only be one option: '''CVS'''. Make sure that is selected, then click '''Next >'''.

Under '''Scope''', choose '''Workspace''', then click '''Finish'''.

Wait while it talks to the CVS server. After a while, you will see that the Synchronize view lists course/lib.php, and something called '''.project...''' That is, it is listing just the files you have edited, but not checked in yet.

'''.project''' is something that belongs to Eclipse that we don't care about. So select it and bring up the context menu, and choose '''Add to .cvsignore...'''. In the dialog that pops up, choose the top option, then click '''OK'''. Then you will find the Synchronize view shows you a '''.cvsignore''' file that you aren't interested in, so add that to .cvsignore too!

If you double-click on '''course/lib.php''' here, you will see that it opens the compare editor, which is a nice graphical display of the changes in this file.

If you select a file or files here, then bring up the context menu, you will see the option to '''Commit...''' the changes. (But don't do that now!). This is the easiest way to commit things in Eclipse.

However, our changes were rubbish, so we want to undo them. So open the context menu again, and choose '''Override and Update'''. This checks a clean copy of the file out of CVS, removing our changes.

Note that the easiest way to do an ordinary CVS Update is to select the top-level project-folder in the Navigator view on the left, open the context menu, and choose '''Team -> Update'''.

That's all of the really important features. I'm sure you can learn everything else on your own. And you can always read the built in help!

===Creating a patch===

In the synchronise view, right-click an item (file or folder) and choose '''Create Patch...'''. Or in the navigator, right-click an item and choose '''Team -> Create Patch...'''.

This brings up a two-page wizard. On the first page you can select where you want the patch made. For small patches it can be useful to create them on the clipboard, but normally you will want to save them in a file.

On the second page, you can set some options, but normally you don't need to change the defaults which are '''Unified''' diff format, and Patch root set to '''Workspace'''. Well, sometimes it is helpful to change the second one to '''Project''' but it is not important.

There is a corresponding apply patch wizard that you can use to apply a patch to a project.

===Switching to another branch or version===

Suppose you have been using a check-out of HEAD from CVS, and then as the 1.9 release approaches, the MOODLE_19_STABLE branch is created, and you want to start following that instead.
# Right click on the moodle project in the navigator view, and select '''Team -> Switch to Another Branch or Version ...'''.
# choose the second radio button: '''Select the tag from the following list'''.
# If the branch you want is not in the '''Matching tags''' box, see [[Setting_up_Eclipse#Resetting the branch information|Resetting the branch information]] below.
# Select the branch you want and click '''Finish'''.

==Troubleshooting==

Some tips on how to solve common problems that may crop up.

===Resetting the branch information===

Every now and then, Eclipse may lose information on the branch tags it knows about. Hitting refresh tags may fix it, but if not, try the following:

#Bring up the tag dialogue (example using "Team / Switch to Another Branch or Version").
#Click on Configure tags... (not Refresh tags).
#Select config-dist.php in the top left box (if this is a Moodle checkout).
#Click Add Checked tags.
#Click OK.
#Then you will have all tags.

(thanks to Tim Hunt)

This info saved my day to find all branches:
1. Window->Show View->Other. Select CVS->CVS Repositories.
2. Context Menu->New->Repository Location...
3. Fill in the location information identifying your repository and click Finish.
4. Expand the newly-created repository location.
5. Add the branch:
1. Right-click it and expand configure branches and versions.
2. Expand HEAD and select the project moodle.
3. Context Menu->Configure Branches and Versions...
4. In the "Browse files for tags" table, select one or more files
that contain tags you would like to see (for example scroll down
to find config.php).
5. On the right the existing tags will appear.
6. Select the tags: for example MOODLE_15_STABLE
7. Click "Add Selected Tags".
8. Click "OK".
6. Locate branches, MOODLE_19_STABLE, moodle MOODLE_19_STABLE.
7. Context Menu->Check Out As Project.
("stolen" from Joan Codina Filba
General developer forum -> Moodle floating "block"/toolbar released -> Re: Moodle floating "block--PATCH FOR GRADES & ASIGNMENT --PROBLEM)

===Error loading php files after Ubuntu 7.04 Install===

A java issue with Ubuntu 7.04 may cause an error when you attempt to load php pages. Refer to:
http://www.plog4u.org/index.php/Using_PHPEclipse_:_Installation_:_Installing_PHPEclipse for details about how to fix this in Ubuntu 7.04.

After upgrading from Ubuntu 7.04 to 7.10, I had to go in and re-edit the /etc/eclipse/java_home file in order to get the CVS functions to work and be able to open PHP files. When I tried to do a CVS update, I initially received an error about org.eclipse.team.internal.ccvs.ui.wizards.CheckoutWizard). Everything seemed to work again after reapplying the fix for the aforementioned 7.04 java issue.

===Strange mouse behavior in Eclipse with Ubuntu 9.10===

After upgrading to Ubuntu 9.10 I began have left mouse clicks that did not appear to be actually firing off the expected events. I stumbled across https://bugs.launchpad.net/ubuntu/+source/gtk+2.0/+bug/452938. Essentially what I did was modify /usr/bin/eclipse and added in the line: export GDK_NATIVE_WINDOWS=true so that it executes before starting Eclipse.

==Related Links==

There is an excellent series of articles published by IBM on using Eclipse for Drupal developement here : [http://www-128.ibm.com/developerworks/ibm/osource/index.html Using open source software to design, develop, and deploy a collaborative Web site Tools and techniques for getting relatively complicated Web sites up and running quickly].

[[Category:Eclipse]]
[[Category:Developer tools|Eclipse]]

[[fr:Développement:Eclipse]]

Checkbox

2009-07-25T15:28:03Z

Aborrow:

[[ Moodle User Interface Guidelines|Moodle User Interface Guidelines]] > '''Checkbox'''

{{Work in progress|forumurl=http://moodle.org/mod/forum/discuss.php?d=126884|info= '''This is a [[Moodle_User_Interface_Guidelines|Moodle Interface Guideline]]. Comments: [http://moodle.org/mod/forum/discuss.php?d=126884 developer forum thread] '''}}
== Problem ==
You want to know if a user wants to enable an option or not. In other words, you want an option with two choices
== Context ==
You are designing a form.

== Forces: factors that affect selection ==
* Radio buttons and dropdown menus are too verbose for a binary choice
* Dropdown menus hide the other choice

== Solution ==

For on/off choices where there are two options,

Create a checkbox with an id attribute. Add a <label for="id_of_checkbox"> element '''after''' the checkbox. As the text content of the label element, write the result of checking the box:

[] Show me the money

Determine a reasonable default for the value: checked, or unchecked. the reasonable default should be such that if a user does not notice the option, they probably do not mind leaving it to default. If no reasonable default can be determined, you may want to consider highlighting the checkbox in the form it is in, since it is impossible to make a checkbox a required field per se.

(Another use of the checkbox is to require users to always check a checkbox, i.e. "[ ] I have read and I accept the terms and conditions", but in this case it is not really an option at all.)

== Common mistakes ==

Do not express the option label as a question: "Do you want to see the money?"

Do not invert the option to negative voice: "Don't show me the money". Most times, only positive voice should be used.

Do not use radio buttons or dropdowns when there are only two choices.

TODO: Add further common mistakes from [http://moodle.org/mod/forum/discuss.php?d=126481]

== Examples and implementation ==

Some examples of good and bad implementation

Course settings (course/edit.php) - BAD: uses dropdown yes/no rather than checkbox, uses question (is this a metacourse?)
Updating or adding database module (course/modedit.php?update=19&return=1) - BAD: uses dropdown yes/no for ratings and comments. Also asks question Require approval?
In general, a review of each modules is needed as we have similar issues with assignment (prevent late submissions, etc.)

== Related guidelines ==

* Radio buttons
* [[Switch Button|Switch Button]]
* Sometimes extra options should be hidden with [[Progressive disclosure|Progressive disclosure]]

== Related issues in the tracker ==

MDL-19659 - Usability test: Proper display of configuration variables' default values

== Further information / Sources ==
[http://moodle.org/mod/forum/discuss.php?d=126481 Alternatives to yes/no dropdown menus?]

Checkbox

2009-07-25T12:58:28Z

Aborrow:

[[ Moodle User Interface Guidelines|Moodle User Interface Guidelines]] > '''Checkbox'''

{{Work in progress|forumurl=http://moodle.org/mod/forum/discuss.php?d=126884|info= '''This is a [[Moodle_User_Interface_Guidelines|Moodle Interface Guideline]]. Comments: [http://moodle.org/mod/forum/discuss.php?d=126884 developer forum thread] '''}}
== Problem ==
You want to know if a user wants to enable an option or not. In other words, you want an option with two choices
== Context ==
You are designing a form.

== Forces: factors that affect selection ==
* Radio buttons and dropdown menus are too verbose for a binary choice
* Dropdown menus hide the other choice

== Solution ==

For on/off choices where there are two options,

Create a checkbox with an id attribute. Add a <label for="id_of_checkbox"> element '''after''' the checkbox. As the text content of the label element, write the result of checking the box:

[] Show me the money

Determine a reasonable default for the value: checked, or unchecked. the reasonable default should be such that if a user does not notice the option, they probably do not mind leaving it to default. If no reasonable default can be determined, you may want to consider highlighting the checkbox in the form it is in, since it is impossible to make a checkbox a required field per se.

(Another use of the checkbox is to require users to always check a checkbox, i.e. "[ ] I have read and I accept the terms and conditions", but in this case it is not really an option at all.)

== Common mistakes ==

Do not express the option label as a question: "Do you want to see the money?"

Do not invert the option to negative voice: "Don't show me the money". Most times, only positive voice should be used.

Do not use radio buttons or dropdowns when there are only two choices.

TODO: Add further common mistakes from [http://moodle.org/mod/forum/discuss.php?d=126481]

== Examples and implementation ==

Some examples of good and bad implementation

Course settings (course/edit.php) - BAD: uses dropdown yes/no rather than checkbox, uses question (is this a metacourse?)
Updating or adding database module (course/modedit.php?update=19&return=1) - BAD: uses dropdown yes/no for ratings and comments. Also asks question Require approval?
In general, a review of each modules is needed as we have similar issues with assignment (prevent late submissions, etc.)

== Related guidelines ==

* Radio buttons
* [[Switch Button|Switch Button]]
* Sometimes extra options should be hidden with [[Progressive disclosure|Progressive disclosure]]

== Related issues in the tracker ==

== Further information / Sources ==
[http://moodle.org/mod/forum/discuss.php?d=126481 Alternatives to yes/no dropdown menus?]

Talk:Interface guidelines

2009-07-04T02:48:02Z

Aborrow: /* Language strings? */ new section

I want to contribute for the "Language Strings" title.

The prepositions in English usually does not correspond to meaningfull words in other languages. Say "'''3 of 10 is being displayed'''" string should be coded in the language file as is.

Wrong Approach:
----
Phrase 1: '''of'''

Phrase 2: '''is being displayed'''

Instead, the correct approach is:
----
Phrase: '''%s of %s is being displayed'''

Because the preposition may or may not exist in the translation as a word, therefore the translated string may also be shuffled, i.e. may not be starting with "3" for the specific example above.

I think, this problem can be avoided by setting a guideline for it like:

"Use whole sentences or sub-sentences as language strings, do not divide your sentence into words of prepositions to avoid dublication in translations. Because not all the languages have the same grammer and linguistics that English built on."

This way, the the translated UI would be much more understandable.

::Actually, this is already part of the coding guidelines - at least as I understand them - I have to say that [[Coding]] is not very clear on this point. Anyway, I think that Internationalisation should be a separate section of the coding guidelines, and we should keep Interface guidelines more focussed towards usability. I think I may take this discussion to the forums.--[[User:Tim Hunt|Tim Hunt]] 03:34, 5 April 2009 (UTC)

== Language strings? ==

While I appreciate the modularity of keeping the language strings separate, I am not convinced that should be a hard and fast rule. If a valid language string exists in the core code then I see no reason to duplicate it. I get the idea, I'm just find myself not convinced. Peace - Anthony

Talk:Progressive Disclosure

2009-07-04T02:18:06Z

Aborrow: /* Anthony's two cents */ new section

Please add your comments for the page about [[Progressive_Disclosure|Progressive disclosure]] here. --[[User:Olli Savolainen|Olli Savolainen]] 11:32, 2 June 2009 (UTC)

== Couple issues ==

Three problems with this:

=== Speed of use ===

There are two aspects to usability: '''ease''' of use (which this topic aids) and '''speed''' of use. (Speed could also be referred to as reducing frustration, making life easier, etc. It's not just about making things faster, it's about making you less likely to throw a brick through your computer monitor.)

When somebody doesn't know how to use software or a particular area of software, ease of use is critical. When they do know how to use it, speed of use is critical.

So clicking through to an 'Advanced' screen can be a big problem if it is an operation people need to use frequently. We have a team of experienced and busy administrators working here and anything that makes their life harder or more tedious is a bad thing.

=== Site policy ===

Depending on site policy, some facilities which might be 'advanced' for most sites could in fact be 'required' for others. For example, the grouping facility is turned off by default and is also marked as 'advanced'. However, we use groupings extensively and with our configuration it is an error not to select the correct grouping. Hiding a field which specifically requires consideration is obviously bad design.

So there might be some cases where a field/option which is 'advanced' for normal usage is in fact 'important' on a particular site.

My suggestions would be:

* Advanced features should not be moved to new separate pages unless we are sure there are no circumstances where people would want to use that feature on a regular basis.

* When advanced features are hidden within a page, and users choose to show these advanced features, they should 'stay shown' in future until the user chooses to hide them.

* The 'show/hide' decision should probably be remembered per screen/form/area not globally, as a user may be experienced in one area but not others.

* The 'show/hide advanced' feature should use a standard interface so that it behaves the same way everywhere and is obvious to users.

* site policy (my issue #2 above) might suggest that there should be a standard way to configure specific screens so that they always show their 'advanced' features (the 'show/hide' button disappears). In other words administrators can 'lock' the show/hide button. However I don't feel this is a critical feature provided that the standard show/hide is remembered per user between sessions.

[[User:sam marshall|sam marshall]] 12:15, 2 June 2009 (UTC)

: sam: show/hide advanced on moodle_forms is of course persisted via get/set_user_preference.--[[User:Tim Hunt|Tim Hunt]] 13:53, 2 June 2009 (UTC)

:: Just a reminder for [http://moodle.org/mod/forum/discuss.php?d=122545 Collapsible fieldsets for uncluttering editing pages] --[[User:Frank Ralf|Frank Ralf]] 11:25, 25 June 2009 (UTC)

==Data about user use==

Having just skimmed Pattern Language for Pattern Language, I am specifically thinking about the Lesson Module page in MoodleDocs, currently #7 on the long page list.
How do we know what people use and what they don't. How do we gather data and quantify it? My language in this is limited, so I will just ask questions.

What is the frequency of use for any specific activity, resource or block on Moodle sites? Categories of Moodle sites would be nice (K-8, 9-12, 13+, training, other). For example for each site, a matrix of activities, number of courses using it, number of teachers that use it and the overall count of each activities use would be interesting.

For example the Lesson Forum can not tell me but the SQL database can:
*Lesson module -how many sites use it, what is the average number of lessons per course, how many teachers per site use it? How does it relate to other activities on the site in terms of use?
**Dependency settings, how many lessons use them in a site? How many teachers and how many courses?
**Slide show settings, ditto
**Branch pages and Question pages, what is the ratio and average number per lesson
**Clusters, ditto
**Imports, I don't think there is SQL data on this.

Do we have a SQL query that someone voluntarily can run on their site which will give us these stats without violating confidential info?

Just a different kind of thought about useability. --[[User:chris collman|chris collman]] 12:45, 29 June 2009 (UTC)

:Using statistical data to aid making design decisions is indeed an important opportunity that would need to be grasped more efficiently. A problem indeed is privacy: how to get admins to give us that data. If they can trust that they are not giving anything sensitive away and do not have to do extra work to generate data and send it to us, this might indeed be possible.
:"The Importance of Analytics in User Experience - The next big innovation in analytics isn’t going to be about the technology. It’s going to be about the UI. Smart reporting tools that answer questions and directly aid decision making – that’s what the world needs. In the meantime, UX specialists have got to get a whole lot better at analytics. Why not get started by reading this presentation by Louis Rosenfeld?" http://www.90percentofeverything.com/2009/06/05/the-importance-of-analytics-in-user-experience/
:: See also: http://moodle.org/mod/forum/discuss.php?d=126856#p556299 --[[User:Olli Savolainen|Olli Savolainen]] 11:02, 30 June 2009 (UTC)

:::This is old stuff in the marketing department :) Realize some sites will not want to reveal any information, even how many students or teachers they have. In the US we have things like FERPA regulations. I was thinking that doing it from the SQL side would allow things like index numbers instead of names or even ids for privacy sake. For additional security, it could produce transparent data/report(s) that could be reviewed, then sent by the site administrator. These could be in a spreadsheet or CSV files. This optional report feature could be put in the Experimental part of Site Administration. Figuring out which data to collect and correlate is not going to be easy. I am sure team taught courses and meta courses add delightful wrinkles to what seems like simple questions.

:::Data is data. "A few" or "a lot" is meaningless without context. As an aside, I sort of wonder how much development in an open source community is driven by the squeaky wheel and special interests with resources. In private enterprise it is more about sales, that offers a slightly different spin on special interests and squeaky wheels :) --[[User:chris collman|chris collman]] 12:54, 30 June 2009 (UTC)

== Examples ==

I would like to see this page have clear, specific examples that show exactly how and where we do this in Moodle.

For example: in the form when adding/updating a quiz (and other activity modules), there are several options deemed advanced that are hidden behind a button. This happens because:
* the module implements a set of default defaults for which items are advanced
* the module has implemented a settings page that allows the admin to re-specify what is advanced if they want to, and also allows the admin to change the default values for the fields
* the module uses mform which uses the settings to flag what is advanced and what isn't
* mform will automatically create the interface based on these settings plus user preferences for "stickiness"

I'd be the first to argue that the actual interface generated by '''mform''' is not the most usable and could be improved, but the great thing is that if all developers implement progressive disclosure this way then it means that usability for this specific example of progressive disclosure CAN be fixed across Moodle simply by fixing mform.

-- [[User:Martin Dougiamas|Martin Dougiamas]] 08:46, 3 June 2009 (UTC)

: Thanks Martin. Actually, to keep the work maintainable, linking to examples of existing implementations should probably be the highest priority. Taking screenshots is pretty easy too (though it could be [http://moodle.org/mod/forum/discuss.php?d=124977#p547610 a lot easier], and then eventually implementation pages (example: [[Progressive_Disclosure_Implementation|progressive disclosure implementation]]) could be filled in with explanation or links to pages where implementing the elements is explained.--[[User:Olli Savolainen|Olli Savolainen]] 12:01, 4 June 2009 (UTC)

=== Forms inconsistencies ===
I've started collecting some [[User:Frank_Ralf/Moodle_forms1| examples of inconsistencies of Moodle forms ]] and took a first [[User:Frank_Ralf/Semantic_HTML5| peek under the hood of ''formslib'']] though this is very much still a work in progress. --[[User:Frank Ralf|Frank Ralf]] 11:32, 25 June 2009 (UTC)

=== MoodleDoc example===
An example (not a good one but). A MoodleRooms student made a comment about the MoodleDocs [[Backup]] page that seemed to be about terminology. First, I realized the intro made some huge assumptions about the user and context. Secondly, I thought the step by step section formatting was confusing. And of course I could not resist tweaking the language which did not seem to always follow demo.moodle. I am still not happy with the overall look of the page (I am sure either I or someone else will do something about it) but I think it is an improvement on usability.

In the step by step, I tried to indent various options. My thinking was the options are similar to "advanced" or "special" or "non-default" settings. Visually, I wanted the KISS steps to be clear for those who just want to click, click, click and do a manual backup. If they want to learn more, then their eyes can wander to the indents. Also there was no word reference to 3 screenshots in the step by step. These are common edits, which once made are generally tweaked but not reformatted by the community of editors.

In MoodleDocs, I think of this like having an advanced button on a form. Sometimes bullets or the ":" features are used the same way. A very common example is the use of <nowiki>:''Tip:''</nowiki> at the end of a section or below a paragraph of how to.

Finally, I am undecided about where the images go on this page. Should the step by step be broken down into 3 stub headings for each screen, with a mini picture in each one? Should we have quick step by steps section, then more detailed step by step section. Do the pictures work lined up on the right as they are. On a page with a template, lining up images on the right does not always work. Is variety OK ?

Olli there is one example and like most things a work in progress (WIP).--[[User:chris collman|chris collman]] 13:58, 4 June 2009 (UTC)

== Search and Advanced search of forums ==

Hi Olli,

I think what's really missing from the search forms is the possibility to '''limit one's search''' either to only the discussion or the subject (one of which should IMO be the default behavior for the search field anyway).

See MDLSITE-664 and MDLSITE-644 for further aspects of this topic.
--[[User:Frank Ralf|Frank Ralf]] 11:21, 25 June 2009 (UTC)

== Anthony's two cents ==

I found the Predictability section difficult to understand. I wonder how we might provide guidelines for form creation. It sounds like you are proposing that each form element should have an option for a default value and a method for indicating whether it is advanced or not. I believe you are documenting functionality that is currently available for developers and working it into a recommended procedure for future code. I wonder if we might want to start thinking about the next step which would be to allow site admins the ability to set default values and whether an option is advanced or not. Going further, being able to provide this level of control for a particular context could be interesting. For example, someone in the Math department of a school may find that a particular set of options are always needed; however, the English department does not need them. The challenge here will be that if we make Moodle so customizable it may be impossible to write any books. Even with this ability to customize, it would not change much for developers since they would have to establish the initial settings. One concern with such a finely controllable approach of course is performance as it introduces another level of complexity along the order of roles and capabilities. Peace - Anthony

Modules and plugins improvements

2009-06-19T11:54:55Z

Aborrow:

Opensis Integration

2009-06-02T16:32:25Z

Aborrow:

This document hopes to outline the goals of integrating OpenSIS with Moodle.

Major Milestones
#MySQL integration
#Transition to adodb
##Evaluate OpenSIS table structures
###https://docs.moodle.org/en/Development:XMLDB_defining_an_XML_structure#Conventions
##Transition to moodle/lib/dmllib.php calls
#Evaluate OpenSIS language strings (get terminology matching with Moodle)

#Evaluate OpenSIS permissions scheme and migrate toward Moodle user, role, capability, context schema
#Assessment OpenSIS security
##ensure md5 passwords

Desired functionality from integration
#Users - Single signon for teachers, students, administrators between both systems. The goal is to use Moodle's libraries and authentication types. We will need to create OpenSIS capabilities and perhaps some roles.
#Courses - Courses created in OpenSIS should automatically create a course in Moodle. By default, this should use the following Course category hierarchy (Marking period, subject (department), course).
#Enrollments - Teachers and students assigned to a course/period should be automatically enrolled in the Moodle course.
#Grades - In Moodle grade items are stored in the gradebook. There are various ways of calculating the grades in Moodle. We need to figure out how best to handle this. Perhaps it would just be best initially to have OpenSIS look up the final grade and not worry about assignments or possibly to create some Moodle grade reports and simply use the Moodle gradebook. The downside to this is that the goal as I understand it is to keep the two systems separated enough that each could be a standalone.

User:Anthony Borrow

2009-06-01T23:11:11Z

Aborrow:

* I'm the Moodle CONTRIB Coordinator. In that role I attempt to:
** Facilitate the sharing and management of contributed code (i.e. non-core, aka CONTRIB)
** Identify and encourage new developers in becoming involved with the Moodle community
** Encourage the maintenance and documentation of contributed code

If you have plugins, patches, themes, or other Moodle-related tools that you would like to share with the Moodle community, feel free to [http://moodle.org/user/view.php?id=51473&course=1 Send me a Moodle message] and to read [https://docs.moodle.org/en/Development:Guidelines_for_contributed_code Guidelines for Contributed Code] for more information.

Feel free to check out my personal website (very much outdated) but hopefully nevertheless entertaining at [http://arborrow.org/ http://arborrow.org/].

Community hub

2009-05-29T13:40:09Z

Aborrow:

{{Moodle 2.0}}

This page describes a functional spec for the "Moodle Community Hub" project, which consists of several new features in Moodle 2.0.

The tracker issue for this project is MDL-19309.

= Goals and rationale =

The main goals of the Community hub project are:

# to allow people to easily find courses around the world that they want to enrol in:
#* educators want to find '''communities of practice''' that are subject or region-oriented, so that they can associate with the peers on a long-term basis.
#* other learners want to find free and for-fee courses on various other subjects
# to make it easy for educators to find and download '''course templates''' from other people. This will help educators share and identify examples of '''best practice''' in online pedagogy and hopefully improve the average quality of online courses.

= Overview =

The "community hub" is not a product, it's a collection of different solutions that work together:

* directory.moodle.org: an open directory of registered courses that are '''downloadable''' or '''enrollable'''
* repository plugin in Moodle 2.0: to find downloadable course templates in the directory, download them from the original site and restore them
* community block in Moodle 2.0: to search the directory to find enrollable courses to join

[[Image:Community.png]]

Downloadable courses
* (A) Sites that want to publish certain courses and make them downloadable do so during registration time with the Moodle Directory.
* (B) Later, any Moodle user can connect to the Directory (via Repository API) to search for downloadable courses and choose one (receiving a URL).
* (C) When the Moodle user tries to download the course, it comes from the original site. The original site will send a Moodle archive as a .zip file (can be cached by the server).
* (D) The Moodle user receives the file and can now restore it normally.

Enrollable courses
* (1) Sites that want to publish certain courses for the public to enrol in can do so during registration time with the Moodle Directory
* (2) Later, any Moodle user can connect to the Directory (via Community block in their site) to search and find courses they want to join
* (3) They click on a link to be sent to the other site so that they can enrol there (with or without Mnet).

= Use Cases =

== New teacher creating a course ==

# New teacher needs some help with a new course for "Alligator farming 101"
# Teacher sees "Import/Export" block into the "Alligator farming 101" course page and presses "Import course"
# Teacher browses directory in the File picker (the data comes from directory.moodle.org by web services)
# Teacher searches for "Alligator"
# Teacher finds 4 courses that look good, and after reading reviews and ratings, chooses one.
# The course is downloaded and unpacked in Moodle.
# The teacher now has a good starter course they can keep developing.

== New teacher needs help ==

A teacher decides they need some help and wants to talk with others teaching Alligator farming.

# Teacher goes to his "Community" block and clicks "Find community".
# Moodle displays an search courses page (the data comes from directory.moodle.org by web services)
# Teacher searches courses for "educator" courses on "Alligators" in their country/language.
# Teacher finds two, selects one, and is returned to the page where is was before clicking on "Find community". The selected course is now permanently listed in the Community block.
# Teacher clicks on the link and is taken to the course, where he can enrol and interact/learn with peers over time, subscribe to forums etc.

== University consortium ==

== Course creation business ==

= Components =

There are three main parts to this project:
* Moodle.org directory (+ registration form on Moodle sites)
* Community membership
* Import/Export courses

==Moodle.org directory==

A new directory system (hosted at directory.moodle.org) will allow users to browse and search registered courses and hubs around the world. This data is collected from site admins when they register their Moodle site on an "opt-in" basis. Only courses that are marked as "publish" will be listed.

=== Data structure ===
this section concerns how the database tables will look on Moodle.org. This section is about listing all data that Moodle.org should store.

==== Sites ====

This information will be used for [http://moodle.org/stats general statistics], as well as the directory.

# Site name
# Site description
# URL
# Physical address
# Site manager (name, email, phone)
# Contact form yes/no?
# Mnet/WS information, enough to let a teacher authenticate to the site using Mnet 2.0 (optional)
# Tool usage stats (forums/quizzes/resources etc) Not for public viewing.

Stats fields:
* number of courses
* number of users
* number of enrolments
* number of posts
* number of resources
* number of questions

Field inherited from previous registry database:
* default site language
* Moodle version (2009050502)
* Moodle release (1.9.5+)
* Site ip address (need to be updated at every update)
* Secret answer
* Mail me the Moodle newsletter
* Can be contacted on the site
* Confirmed
* Time updated
* Time created
* Unreachable
* Time link checked

{| class="nicetable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| name
| varchar(255)
| not null
| Site Name
|-
| description
| text
| null
| site description
|-
| url
| varchar(255)
| not null
| site URL
|-
| Physical address
| varchar(255)
| null
| location of the company
|-
| manager name
| varchar(100)
| null
|
|-
| manager email
| varchar(100)
| null
|
|-
| manager phone
| varchar(20)
| null
|
|-
| statistic
| text
| null
| stats, text format
|-
| moodleversion
| varchar()
| null
| stats, text format
|}

==== Courses ====

All registered courses will be stored here. Some will be looking for students, some will be teacher and admin communities, and some will be downloadable course templates.

# Site
# Name
# Description
# URL
# Tags
## Standard (mathematics, physics, biology) Always displayed, translatable etc ([https://docs.moodle.org/en/Course_Standard_Tags Course Standard Tags ]) Do we need some special tags per country?
## User (stuff, openuni, jeromesstuff etc) Not displayed for browsing, but searchable
## Metadata standard Dublin Core
# Country code (AU, FR etc) lang/countries.php
# Region/state (based on list) ISO 3166-2 (XX-XXX)
# Language lang.php
# Availability (public/private)
# Cost (and currency) ISO 4217
# Download link: direct URL to Moodle download script or moodle.org cache or somewhere else
# Guest Access
# Accounts allowed (can we sign up)
# Screenshots no references into the "registered_courses" table, all screenshots will be saved into the "files" table and the references to the "registered" will be into this "files" table.
# Audience: Educators | Students | Admins
# Educational level being discussed (for educators audience only): Tertiary | Secondary | Primary | Government | Corporate
# Tool usage stats (number of forums/quizzes/resources etc All core modules - no participant number) Only available for downloadable content.

{| class="nicetable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| site id
| int(10)
| auto-incrementing
|
|-
| name
| varchar(255)
| not null
| Course Name
|-
| description
| text
| null
| Course description
|-
| url
| varchar(255)
| not null
| course URL
|-
| stdtags
| varchar(255)
| null
|
|-
| usertags
| varchar(255)
| null
|
|-
| metadata
| varchar(255)
| null
|
|-
| country
| varchar(2)
| null
|
|-
| region
| varchar(6)
| null
|
|-
| language
| varchar(30)
| null
|
|-
| currency
| varchar(3)
| null
|
|-
| cost
| varchar(10)
| null
|
|-
| availability
| varchar(20)
| private
|
|-
| downloadlink
| varchar(255)
| null
|
|-
| guestaccess
| boolean
| false
|
|-
| accountsallowed
| boolean
| false
|
|-
| audience
| varchar(20)
| null
|
|-
| educationallevel
| varchar(20)
| null
|
|-
| stats
| text
| null
|
|}

=== Web interface ===

A Moodle.org web interface, with a search form, displays clickable links to each course.

[[Image:Webinterface.png]]

From this web interface the users can:

* search by keyword and see a list of courses that match - hightlight key word
* browse a list of courses using the standard tag set (hierarchy, tree on the left)
* go directly to a course (if marked for public use)
* preview a course (if screenshots have been provided)
* download the course to desktop (only if an download url has been set)
* give a rating to the course
* write a comment for the course - use comment 2.0 API

When displaying courses, you can see and sort by:

* Title - ''Sortable''
* Description
* Tags - ''Sortable (first tag retrieved by the request is considered)''
* Screenshot(s)
* Cost (if any) - ''Sortable''
* Rating (10-point scale displayed as 5 stars, and only if you are logged in to moodle.org) - ''Sortable''
* Comments
* Moodle site name
* Date added to directory
* Date last updated in directory
* Date last checked (by a cron job)
* Audience (teachers, students, admins)
* Teacher name(s) - ''Sortable''

=== Web service interface ===

A REST-based web services interface will be provided for other systems (eg Moodle sites) to use directly.

Web services can search on:
* string search
* array language
* array cost
* array Moodle url
* Others?

== Registration on Moodle sites==

The existing Moodle registration form will be extended so that admins can choose to send in more info about their sites to the Moodle.org directory. All courses flagged "Register" are also sent with their full details.

A cron job will be added to Moodle so that each site can automatically inform directory.moodle.org later when course information is updated (if the admin allows it).

Moodle.org will perform a heartbeat ping every week to verify that the site is accessible. Sites that fail two or three in a row will be removed from the directory.

[[Image:Registrationform.png]]

== Community membership ==

The "Community" block allows people to find and subscribe to external courses that they want to be part of.

It can be added to any page for any user, and contains:

# A link to a search script, with a new capability to view it (default on for teachers, not students). If a user has not the capability, he will not see the "Community" block.
# A search script to browse/search the directory (using web services to call Moodle.org). Users can select joinable courses from the list and they will be added to the list of "subscribed" course links in the block contents (grouped by site).

If the course is on a site with mnet enabled in "open hub mode" then the link will take the user directly to the course and they will stay logged in. Otherwise the link will be just be an ordinary URL and the remote site will be responsible for authentication.

[[Image:Blocktemplate.png]]

== Import/Export courses ==

The Import/Export block will be available on course pages and contains buttons to:

* '''Export course''': publish entire course (as Moodle Backup minus userdata) as a course template to a Moodle Hub (Portfolio API plugin)
* '''Import course''': find/install a course template from a Hub or from another course on same site (Repository API plugin)
* '''Publish course''': to publish or update the description of the current course in the Moodle.org directory (admins only)

=== Export course ===

A standard export will do a normal backup (taking care to remove userdata by default), and at the end will call the portfolio API to push that file to a connected portfolio. These could include:
* downloading it to the local computer (if the portfolio plugin is activated)
* uploading it to any general purpose repository
* uploading it to a Moodle Hub site already set up with Mnet peering.

Pushing it to a Moodle Hub would trigger extra behaviours:
* More metadata would be required (including screenshots?)
* Permissions would be checked on the destination Moodle
* The course can be immediately restored on the external Moodle in a special "New" category as a hidden course
* Someone on the external Moodle can be alerted to approve/unhide the new course

=== Import course ===

The '''Import course''' button will pull up a normal file picker to browse repositories for files with a mimetype matching .mbkup.zip.

One special repository plugin called "Courses" allows the user to:

* search the moodle.org directory for downloadable courses (only)
* directly search any connected hubs for downloadable courses
* search other courses on the same server (replacing the existing import function we have)

Once the user has selected one of these courses, the user is passed to the standard restore process.

=== Publish course ===

The '''Publish''' button only exists if the current site has been registered on the Moodle directory already, and if the current user has the appropriate capabilities.

After clicking "Publish" the user will get taken to a script asking if you want to allow downloads of this course. He's also asked to upload screenshots if he'd like to.

If downloads are allowed, then you are redirected to the backup process to create and define the backup file, then returned to the script if successful. The backup file is cached in a standard place with a standard name. If downloads are not required then this step is skipped.

Now the script lists the metadata that this course will be published with on the moodle.org directory (this is also available in the course settings page). After checking/updating the metadata, the script will push the data to the Moodle.org directory. The Moodle directory will bounce back a confirmation which gets saved locally as the "Last publish date".

If the checkbox to allow download was checked, then the URL to a course download script is included with this metadata.

The course download script (eg /course/download.php?id=55&secret=XXXXX) will send the cached .zip file for the given course, or (if the the admin has specified that automatic updates are allowed and the course has also allowed it, then it might update the cache once a day or something).

[[Image:Publishtemplate.png]]

= Course settings page =
Some new settings will appear on this page:
* register on Moodle.org - a sub option is activated by default: publish (the site will be displayed in the search result on Moodle.org)
* cache on Moodle.org
* downloadable
* metadata
* screenshots

= Schedule =

Full schedule and progress is in the tracker: MDL-19309

# Moodle.org directory
# Web interface
# Web service interface
# Improve registration form
# Community block
# Publish courses
# Import courses
# Export courses

= See also =

* [[Community hub technotes]] - relating to MNet developments in Moodle 1.8
* MDL-18580 - Community Hub tracker issue

[[Category:MNET]]

[[ja:開発:コミュニティハブ]]

Opensis Integration

2009-05-12T16:13:00Z

Aborrow:

This document hopes to outline the goals of integrating OpenSIS with Moodle.

Major Milestones
#MySQL integration
#Transition to adodb
##Evaluate OpenSIS table structures
###https://docs.moodle.org/en/Development:XMLDB_defining_an_XML_structure#Conventions
##Transition to moodle/lib/dmllib.php calls
#Evaluate OpenSIS language strings (get terminology matching with Moodle)

#Evaluate OpenSIS permissions scheme and migrate toward Moodle user, role, capability, context schema
#Assessment OpenSIS security
##ensure md5 passwords

Desired functionality from integration
#Users - Single signon for teachers, students, administrators between both systems. The disadvantage to this is that an account will need to be created in OpenSIS for all Moodle users. Alternatively, OpenSIS could use Moodle for authentication which allows for authentication via LDAP and others.
#Courses - Courses created in OpenSIS should automatically create a course in Moodle. By default, this should use the following Course category hierarchy (Marking period, subject (department), course).
#Enrollments - Teachers and students assigned to a course/period should be automatically enrolled in the Moodle course.
#Grades - In Moodle grade items are stored in the gradebook. There are various ways of calculating the grades in Moodle. We need to figure out how best to handle this. Perhaps it would just be best initially to have OpenSIS look up the final grade and not worry about assignments or possibly to create some Moodle grade reports and simply use the Moodle gradebook. The downside to this is that the goal as I understand it is to keep the two systems separated enough that each could be a standalone.

Opensis Integration

2009-05-12T15:33:01Z

Aborrow:

This document hopes to outline the goals of integrating OpenSIS with Moodle.

Major Milestones
#MySQL integration
#Transition to adodb
##Transition to moodle/lib/dmllib.php calls
#Evaluate OpenSIS language strings (get terminology matching with Moodle)
#Evaluate OpenSIS table structures
#Evaluate OpenSIS permissions scheme and migrate toward Moodle user, role, capability, context schema
#Assessment OpenSIS security
##ensure md5 passwords

Desired functionality from integration
#Users - Single signon for teachers, students, administrators between both systems. The disadvantage to this is that an account will need to be created in OpenSIS for all Moodle users. Alternatively, OpenSIS could use Moodle for authentication which allows for authentication via LDAP and others.
#Courses - Courses created in OpenSIS should automatically create a course in Moodle. By default, this should use the following Course category hierarchy (Marking period, subject (department), course).
#Enrollments - Teachers and students assigned to a course/period should be automatically enrolled in the Moodle course.
#Grades -

Opensis Integration

2009-05-12T15:31:39Z

Aborrow:

This document hopes to outline the goals of integrating OpenSIS with Moodle.

Major Milestones
#MySQL integration
#Transition to adodb
##Transition to moodle/lib/dmllib.php calls
#Reevaluate OpenSIS language strings (get terminology matching with Moodle)
#Reevaluate OpenSIS table structures
#Assessment OpenSIS security
##ensure md5 passwords

Desired functionality from integration
#Users - Single signon for teachers, students, administrators between both systems. The disadvantage to this is that an account will need to be created in OpenSIS for all Moodle users. Alternatively, OpenSIS could use Moodle for authentication which allows for authentication via LDAP and others.
#Courses - Courses created in OpenSIS should automatically create a course in Moodle. By default, this should use the following Course category hierarchy (Marking period, subject (department), course).
#Enrollments - Teachers and students assigned to a course/period should be automatically enrolled in the Moodle course.
#Grades -

Opensis Integration

2009-05-12T15:23:17Z

Aborrow:

This document hopes to outline the goals of integrating OpenSIS with Moodle.

#Users - Single signon for teachers, students, administrators between both systems. The disadvantage to this is that an account will need to be created in OpenSIS for all Moodle users. Alternatively, OpenSIS could use Moodle for authentication which allows for authentication via LDAP and others.
#Courses - Courses created in OpenSIS should automatically create a course in Moodle. By default, this should use the following Course category hierarchy (Marking period, subject (department), course).
#Enrollments - Teachers and students assigned to a course/period should be automatically enrolled in the Moodle course.
#Grades -

Opensis Integration

2009-05-12T15:22:49Z

Aborrow: New page: This document hopes to outline the goals of integrating OpenSIS with Moodle. #Users - Single signon for teachers, students, administrators between both systems. The disadvantage to this i...

This document hopes to outline the goals of integrating OpenSIS with Moodle.

#Users - Single signon for teachers, students, administrators between both systems. The disadvantage to this is that an account will need to be created in OpenSIS for all Moodle users. Alternatively, OpenSIS could use Moodle for authentication which allows for authentication via LDAP and others.

#Courses - Courses created in OpenSIS should automatically create a course in Moodle. By default, this should use the following Course category hierarchy (Marking period, subject (department), course).

#Enrollments - Teachers and students assigned to a course/period should be automatically enrolled in the Moodle course.

#Grades -

Modules and plugins improvements

2009-04-26T07:48:24Z

Aborrow:

Modules and plugins improvements

2009-04-25T18:11:24Z

Aborrow: New page: The Modules and Plugins database provides a convenient way for Moodle System Administrators to search for available plugins, patches, and tools to enhance their installation. While the bas...

Talk:Usability/Improve Moodle User Experience Consistency

2009-04-09T04:18:53Z

Aborrow: New page: Olli - Under "Some potential things that require change, to be researched further" you mention Feedback being too technical and unhelpful feedback to normal users - could you cite an examp...

Olli - Under "Some potential things that require change, to be researched further" you mention Feedback being too technical and unhelpful feedback to normal users - could you cite an example or two to show what you mean? Thanks - Anthony

Interface guidelines

2009-03-15T23:35:49Z

Aborrow: /* Standard navigation tools */

{{Work in progress}}
This document is not authoritative, it is a collection of ideas and under construction.

==Keeping it simple==

Use the minimum interface required to get the job done.
Order the elements by contexts. Give the user a strong orientation where the places are to do several things.

==Standard pages==

===Activity modules===

*''index.php'' - lists all instances for that module in a course
*''view.php'' - displays a particular instance
*''config.html'' - configure an instance of the module

===Blocks===

*''config.html'' - configure an instance of the block

==One script per major function/page==

...

==Page layout==

# Print headings with print_heading, use the CSS hooks for IDs and Classes
# Print boxes around text using print_simple_box, use the CSS hooks for IDs and Classes

==Form layout==

# Show the more important settings at the top
# Each entry should have a label, and if necessary, a help file
# If there are more than 10 options, split them into required and optional/extra/advanced parameters

==Dealing with tables==

Use the print_table function whenever possible.

==Standard navigation tools==

# All pages should call print_header, and supply a standard navigation path to be displayed in it. Where possible, it should look like: COURSE >> INDEX >> INSTANCE >> SUBPAGES...
# Pages within activity modules should call navmenu() to generate the appropriate navigation menu.
# Links should include associated image (if available). For example, looking at an assignment in a course displays the assignment pic and then the assignment description as a single link; however, most of the blocks like the activity block exclude the image from the link. This is important as some folks are more graphically rather than text oriented and click on the picture and do not understand why it is not working. We need to be consistent (see MDL-6820).

==URLs==

# URLs should be as short as possible.
# No underscores in parameter names or files names
# Never use two words when one would do.

==Buttons vs links==

This is a hard one to define ...

The Google Web Accelerator issue definitely provides some pointers here:

# Actions which can modify the state of Moodle (data files, database, session information) should be performed through buttons
# At the very least, such actions which are implemented as links should forward to a confirmation page which *does* use buttons

==Language strings==

# Use your own language strings in a separate file. Don'tuse existing language files from moodle.php or other lang files. So translators can translate in the contexts in different ways as terms are used in the special learning culture.

==CSS naming==

* Don't add font, color or layout definitions in code. This belongs to CSS theme files.
* See [[Standards|theme standards]]

==Linking to help==

* Help buttons should be on the right of the thing (as an exception it can be left, if the thing is right-aligned)

==Related topics==

Robin Good's Latest News. "Interaction Design Meets Online Real Estate" 1 Mar. 2005 http://www.masternewmedia.org/news/2005/03/01/interaction_design_meets_online_real.htm

The article presents a view of virtual spaces with the focus on human actions. It reminded me of communicative approaches like Moodle. The interface serves as the handle of all the communication tools.

[[pt:Guia para interface]]
[[es:Manual de estilo de la interfaz]]
[[ja:インターフェースガイドライン]]

Interface guidelines

2009-03-15T22:22:09Z

Aborrow: /* Standard navigation tools */

{{Work in progress}}
This document is not authoritative, it is a collection of ideas and under construction.

==Keeping it simple==

Use the minimum interface required to get the job done.
Order the elements by contexts. Give the user a strong orientation where the places are to do several things.

==Standard pages==

===Activity modules===

*''index.php'' - lists all instances for that module in a course
*''view.php'' - displays a particular instance
*''config.html'' - configure an instance of the module

===Blocks===

*''config.html'' - configure an instance of the block

==One script per major function/page==

...

==Page layout==

# Print headings with print_heading, use the CSS hooks for IDs and Classes
# Print boxes around text using print_simple_box, use the CSS hooks for IDs and Classes

==Form layout==

# Show the more important settings at the top
# Each entry should have a label, and if necessary, a help file
# If there are more than 10 options, split them into required and optional/extra/advanced parameters

==Dealing with tables==

Use the print_table function whenever possible.

==Standard navigation tools==

# All pages should call print_header, and supply a standard navigation path to be displayed in it. Where possible, it should look like: COURSE >> INDEX >> INSTANCE >> SUBPAGES...
# Pages within activity modules should call navmenu() to generate the appropriate navigation menu.
# Links should include associated image (if available). For example, looking at an assignment in a course displays the assignment pic and then the assignment description as a single link; however, most of the blocks like the activity block exclude the image from the link. This is important as some folks are more graphically rather than text oriented and click on the picture and do not understand why it is not working. We need to be consistent.

==URLs==

# URLs should be as short as possible.
# No underscores in parameter names or files names
# Never use two words when one would do.

==Buttons vs links==

This is a hard one to define ...

The Google Web Accelerator issue definitely provides some pointers here:

# Actions which can modify the state of Moodle (data files, database, session information) should be performed through buttons
# At the very least, such actions which are implemented as links should forward to a confirmation page which *does* use buttons

==Language strings==

# Use your own language strings in a separate file. Don'tuse existing language files from moodle.php or other lang files. So translators can translate in the contexts in different ways as terms are used in the special learning culture.

==CSS naming==

* Don't add font, color or layout definitions in code. This belongs to CSS theme files.
* See [[Standards|theme standards]]

==Linking to help==

* Help buttons should be on the right of the thing (as an exception it can be left, if the thing is right-aligned)

==Related topics==

Robin Good's Latest News. "Interaction Design Meets Online Real Estate" 1 Mar. 2005 http://www.masternewmedia.org/news/2005/03/01/interaction_design_meets_online_real.htm

The article presents a view of virtual spaces with the focus on human actions. It reminded me of communicative approaches like Moodle. The interface serves as the handle of all the communication tools.

[[pt:Guia para interface]]
[[es:Manual de estilo de la interfaz]]
[[ja:インターフェースガイドライン]]

Talk:Filter enable/disable by context

2009-03-13T07:47:12Z

Aborrow: New page: Tim - Nice work! Overall, I really like the proposal and think that it would give the much needed flexibility to folks. Ultimately, admin still controls whether it is all on or all off (wi...

Tim - Nice work! Overall, I really like the proposal and think that it would give the much needed flexibility to folks. Ultimately, admin still controls whether it is all on or all off (with enable). Here are some notes that I made as I reviewed the proposal.

#With respect to active, you were asking for another term which I couldn't think of but I do think it should indicate that it is active site wide.
#On the filter admin screen, I think it might be nice for the admin to see a list of contexts which are explicitly enabled with an option for deleting an individual context.
#A small detail, when deleting a filter I would want to make sure that we remember to display the notice reminding the admin to remove the code from the server to prevent it from being re-installed like we do for blocks and mods - as much consistency we can develop between how modules, blocks, and filters (i.e. plugins) are handled the more intuitive I believe Moodle is for the users.
#Along the lines of consistency, do the proposed navigation changes for Moodle 2.0 include providing this type of customization for blocks and modules as well? If not, I think it would be good to be able to make a block only available for Math courses, or a particular modules like WebWorks only available in Math courses. I'm not sure what other issues this might raise but it seemed like some of these ideas might also be applied in a similar way to blocks/plugins. As part of this, I envision the page have a single settings button that could display multiple tabs for filters, blocks, mods, etc. Only the tabs that make sense at the particular context would be shown. For example, it does not make sense to provide a module with block or module options so just the filter tab would appear.
#You mention selecting the active, inactive, inherit would be from a drop down and then question if it would be better with radio buttons. I think for consistency it would be better to use radio buttons and make it look like the capabilities page. We may be at a point where we start to develop a particular look and feel for administrative options.
#For "problem pages" like the user profile page that may pull in information from various places or the My Moodle page, might it be possible to get a list of the used contexts on that page and use and concat together the list of active filters? As I understand it, these would be the exception cases where you want the text to be filtered based on context it belongs to rather than the particular page. Page could be the default but perhaps you could right the function to occasionally use the context.

These were the thoughts that came to mind when I read it this morning. I'm pretty tired now so I'm not sure how coherent this is but I did want to get you some feedback. Peace - Anthony

Plugin contribution

2009-02-26T19:36:55Z

Aborrow:

This page describes the various ways to share and work collaboratively on contributed code.
#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==
'''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.

==How to submit code==
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.

*Contributors are encouraged to follow Moodle's coding guidelines [[Coding]]).
*A list of current tracker [http://tracker.moodle.org/secure/BrowseProject.jspa contributed projects is here].

==How to work with code in CVS==
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.

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)]].

:''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.

==How to provide documentation==
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.

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.

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.

==Share code with modules and plugins database==
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.

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.

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.

==Support code and get feedback with forums==
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.

*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects.
*[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 get_config and set_config functions in the /lib/moodlelib.php file to help ensure that the footprint for the global $CFG variable does not become bloated.
# Does 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==

*[[contrib]] CONTRIB is an area in the Moodle CVS
*[[Translation]] for information on the translation of contributed code
*[[Overview]]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion

[[Category:Guidelines for contributors]]