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 [[Development: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==

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

[[Category:Developer|Guidelines for contributors]]

Development 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

Development talk:Process

2010-12-26T01:20:41Z

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

Development talk:Process

2010-12-16T17:28:37Z

Aborrow:

Development 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

Development 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

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

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

Some details of how to re-design image CSS for plugin code ar in the main themes documentation: [[Development: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: [[Development: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

[[Category:Developer]]

Development: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

[[Category:Developer]]

Development:Guidelines for contributed code

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 [[Development: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 [[Development: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==

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

[[Category:Developer|Guidelines for contributors]]

Development:Guidelines for contributed code

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 [[Development: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 [[Development: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==

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

[[Category:Developer|Guidelines for contributors]]

Development talk:Modules and plugins improvements

2010-06-15T12:18:23Z

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

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

==See also==

* CONTRIB-1988

[[Category:Developer]]

Development talk:Languages/AMOS

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

2009-07-04T02:18:06Z

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

Please add your comments for the page about [[Development: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: [[Development: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

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 -