MoodleDocs - User contributions [en]

W3C validation

2019-05-24T06:19:27Z

Damyon: Consolidating accessibility documentation

{{obsolete}}

This page has been replaced because the content was no longer applicable to the current version of Moodle.

Current documentation can be found here:

[https://docs.moodle.org/dev/Accessibility "Accessibility in Moodle"]

The previous version of this document can be seen [https://docs.moodle.org/dev/index.php?title=W3C_validation&oldid=29805 in the history]

Moodle Accessibility Specification

2019-05-24T04:55:54Z

Damyon: Consolidating accessibility documentation

Aria Guidelines

2019-05-24T04:54:57Z

Damyon:

Accessibility notes

2019-05-24T04:53:37Z

Damyon: Consolidating accessibility documentation

Atto

2019-05-24T04:04:27Z

Damyon: /* See Also */

{{Moodle 2.7}}

Atto is a javascript text editor built specifically for Moodle. Atto is the default text editor in Moodle from 2.7 onwards.

Atto is implemented as a standard Moodle text editor plugin ([[Editors]]). Most of the code is written in javascript as a standard Moodle YUI module.

Follow the development of ATTO here: https://tracker.moodle.org/browse/MDL-43996

==What does Atto mean?==

Really really small. (10^-18). It used to be :)

The name still ties in with some of the design concepts for Atto which is to be a simple, fast editor users.

==Where can I get Atto?==

GIT - and you can check here: https://moodle.org/plugins/view.php?plugin=editor_atto

==Atto Plugins==

All of the buttons/menus in Atto are implemented as true Moodle subplugins. This means that the subplugins can do anything a subplugin can do including, lang strings, db tables, yui modules.

There are a couple of extra functions/structure required for an Atto subplugin which are required in order to load a plugin on the toolbar.

==Structure of an Atto Plugin==

/lib.php
Optional. Only required if your plugin needs to implement one of the component callbacks listed below.

/settings.php
Optional. Only required if your plugin wants to support custom admin settings. See: [[Admin_settings#Individual_settings]] for more info on settings.

/version.php
Required. Moodle plugin version. See:[[version.php]] for more info on version files.

/lang/en/atto_pluginname.php
Required. Language file. This file is required and must at least define the language string 'pluginname'.

/yui/src/button/
Required. The plugin must implement a YUI module that will be included by the editor when the page loads. That YUI module must be named 'button' and must insert itself a class into the Y.M.<plugin name> namespace, with constructor that will be called to initialise the editor. It is recommended that you extend the EditorPlugin class as described below.
See: [[YUI/Modules]] for more information about YUI modules.

==Atto subplugin Php API==

Atto sub plugins can contain a lib.php file with 2 callbacks that will be looked for when the plugin is loaded.

The first is "XXX_strings_for_js" (example taken from atto_table plugin):

<pre>
/**
* Initialise the js strings required for this module.
*/
function atto_table_strings_for_js() {
global $PAGE;

$PAGE->requires->strings_for_js(array('createtable',
'accessibilityhint',
'headers',
'caption',
'columns',
'rows',
'numberofcolumns',
'numberofrows',
'both',
'edittable',
'addcolumnafter',
'addrowafter',
'movecolumnright',
'movecolumnleft',
'moverowdown',
'moverowup',
'deleterow',
'deletecolumn'),
'atto_table');
}

</pre>

The purpose of this callback is to allow the plugin to initialise the strings that it will use in it's user interface. Note: that the pluginname string for each plugin is automatically loaded, and if this is the only string your plugin requires, then it is not necessary to implement this callback in your plugin. See: [[JavaScript_guidelines#Getting_Moodle_to_load_your_JavaScript_files]] for more information on strings_for_js.

The second php callback that can be implemented in lib.php is: "XXX_params_for_js" (fictional example, not used in core):

<pre>
/**
* Return the js params required for this module.
* @return array of additional params to pass to javascript init function for this module.
*/
function atto_gambling_params_for_js() {
return array('bestodds' => '34 to 1', 'worstodds' => '5 to 1');
}

</pre>

If you are using this second callback, you need to specify these parameters in your JavaScript source file, passing it as an argument in the constructor:
<pre>
{
ATTRS: {
bestodds: {
value: '<defaultvalue>'
},
worstodds: {
value: '<defaultvalue>'
}
}
}
</pre>

==Atto subplugin Javascript API==
Atto subplugins must implement a yui module named "moodle-atto_pluginname-button".
This module will be automatically loaded when Atto is displayed on a page (and the subplugin is listed in the toolbar configuration).

The plugin:
* '''must''' register a class at Y.M.atto_PLUGINNAME.button;
* '''must''' provide a constructor; and
* '''''should''''' extend [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin.js Y.M.editor_atto.EditorPlugin].

It is up to the plugin author to decide how best to write their plugin, but it is highly advisable to extend EditorPlugin class, which provides a number of useful functions for dealing with the Editor, Toolbars, Keyboard Navigation, and other related areas.

Of particular interest are:

* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-buttons.js#L293 addBasicButton] - to add a basic button which directly uses document.execCommand with minimal effort;
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-buttons.js#L161] - to add a button giving you a greater degree of control via your own callback;
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-buttons.js#L337 addToolbarMenu] - to add a dropdown toolbar menu;
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin.js#L91 markUpdated] - should be called after making changes to the content area; and
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-dialogue.js#L54 getDialogue] - return a standard dialogue, creating one if it does not already exist.

=== Examples ===
You may also wish to take a look at some of the existing plugins for examples on how to create the different types:

* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/strike/yui/src/button/js/button.js A basic plugin];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/bold/yui/src/button/js/button.js A basic plugin which has a keyboard shortcuts];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/indent/yui/src/button/js/button.js A plugin with two buttons (one basic, one slightly more complex)];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/rtl/yui/src/button/js/button.js A plugin with multiple buttons which take arguments];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/title/yui/src/button/js/button.js A plugin which utilises a toolbar menu];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/image/yui/src/button/js/button.js A plugin with a dialogue]; and
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/charmap/yui/src/button/js/button.js A plugin which uses templates to build its dialogue].

== See Also ==

Atto makes accessibility tools available to content authors. See https://docs.moodle.org/dev/Accessibility#Authoring_features

Atto makes use of contenteditable regions, and the rich text editing API supported by modern browsers. See https://developer.mozilla.org/en/docs/Rich-Text_Editing_in_Mozilla for further reading.

See the comparision (pros, cons, technical notes, missing features, etc) of Atto versus other candidate editors for Moodle 2.7 in [https://docs.moodle.org/dev/Editor_2.7 https://docs.moodle.org/dev/Editor_2.7]

For opening dialogues it is recommended to use M.core.dialogue : https://github.com/moodle/moodle/blob/master/lib/yui/src/notification/js/dialogue.js

Atto

2019-05-24T04:03:59Z

Damyon: /* See Also */

{{Moodle 2.7}}

Atto is a javascript text editor built specifically for Moodle. Atto is the default text editor in Moodle from 2.7 onwards.

Atto is implemented as a standard Moodle text editor plugin ([[Editors]]). Most of the code is written in javascript as a standard Moodle YUI module.

Follow the development of ATTO here: https://tracker.moodle.org/browse/MDL-43996

==What does Atto mean?==

Really really small. (10^-18). It used to be :)

The name still ties in with some of the design concepts for Atto which is to be a simple, fast editor users.

==Where can I get Atto?==

GIT - and you can check here: https://moodle.org/plugins/view.php?plugin=editor_atto

==Atto Plugins==

All of the buttons/menus in Atto are implemented as true Moodle subplugins. This means that the subplugins can do anything a subplugin can do including, lang strings, db tables, yui modules.

There are a couple of extra functions/structure required for an Atto subplugin which are required in order to load a plugin on the toolbar.

==Structure of an Atto Plugin==

/lib.php
Optional. Only required if your plugin needs to implement one of the component callbacks listed below.

/settings.php
Optional. Only required if your plugin wants to support custom admin settings. See: [[Admin_settings#Individual_settings]] for more info on settings.

/version.php
Required. Moodle plugin version. See:[[version.php]] for more info on version files.

/lang/en/atto_pluginname.php
Required. Language file. This file is required and must at least define the language string 'pluginname'.

/yui/src/button/
Required. The plugin must implement a YUI module that will be included by the editor when the page loads. That YUI module must be named 'button' and must insert itself a class into the Y.M.<plugin name> namespace, with constructor that will be called to initialise the editor. It is recommended that you extend the EditorPlugin class as described below.
See: [[YUI/Modules]] for more information about YUI modules.

==Atto subplugin Php API==

Atto sub plugins can contain a lib.php file with 2 callbacks that will be looked for when the plugin is loaded.

The first is "XXX_strings_for_js" (example taken from atto_table plugin):

<pre>
/**
* Initialise the js strings required for this module.
*/
function atto_table_strings_for_js() {
global $PAGE;

$PAGE->requires->strings_for_js(array('createtable',
'accessibilityhint',
'headers',
'caption',
'columns',
'rows',
'numberofcolumns',
'numberofrows',
'both',
'edittable',
'addcolumnafter',
'addrowafter',
'movecolumnright',
'movecolumnleft',
'moverowdown',
'moverowup',
'deleterow',
'deletecolumn'),
'atto_table');
}

</pre>

The purpose of this callback is to allow the plugin to initialise the strings that it will use in it's user interface. Note: that the pluginname string for each plugin is automatically loaded, and if this is the only string your plugin requires, then it is not necessary to implement this callback in your plugin. See: [[JavaScript_guidelines#Getting_Moodle_to_load_your_JavaScript_files]] for more information on strings_for_js.

The second php callback that can be implemented in lib.php is: "XXX_params_for_js" (fictional example, not used in core):

<pre>
/**
* Return the js params required for this module.
* @return array of additional params to pass to javascript init function for this module.
*/
function atto_gambling_params_for_js() {
return array('bestodds' => '34 to 1', 'worstodds' => '5 to 1');
}

</pre>

If you are using this second callback, you need to specify these parameters in your JavaScript source file, passing it as an argument in the constructor:
<pre>
{
ATTRS: {
bestodds: {
value: '<defaultvalue>'
},
worstodds: {
value: '<defaultvalue>'
}
}
}
</pre>

==Atto subplugin Javascript API==
Atto subplugins must implement a yui module named "moodle-atto_pluginname-button".
This module will be automatically loaded when Atto is displayed on a page (and the subplugin is listed in the toolbar configuration).

The plugin:
* '''must''' register a class at Y.M.atto_PLUGINNAME.button;
* '''must''' provide a constructor; and
* '''''should''''' extend [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin.js Y.M.editor_atto.EditorPlugin].

It is up to the plugin author to decide how best to write their plugin, but it is highly advisable to extend EditorPlugin class, which provides a number of useful functions for dealing with the Editor, Toolbars, Keyboard Navigation, and other related areas.

Of particular interest are:

* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-buttons.js#L293 addBasicButton] - to add a basic button which directly uses document.execCommand with minimal effort;
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-buttons.js#L161] - to add a button giving you a greater degree of control via your own callback;
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-buttons.js#L337 addToolbarMenu] - to add a dropdown toolbar menu;
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin.js#L91 markUpdated] - should be called after making changes to the content area; and
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-dialogue.js#L54 getDialogue] - return a standard dialogue, creating one if it does not already exist.

=== Examples ===
You may also wish to take a look at some of the existing plugins for examples on how to create the different types:

* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/strike/yui/src/button/js/button.js A basic plugin];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/bold/yui/src/button/js/button.js A basic plugin which has a keyboard shortcuts];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/indent/yui/src/button/js/button.js A plugin with two buttons (one basic, one slightly more complex)];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/rtl/yui/src/button/js/button.js A plugin with multiple buttons which take arguments];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/title/yui/src/button/js/button.js A plugin which utilises a toolbar menu];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/image/yui/src/button/js/button.js A plugin with a dialogue]; and
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/charmap/yui/src/button/js/button.js A plugin which uses templates to build its dialogue].

== See Also ==

Atto makes accessibility tools available to content authors. See https://docs.moodle.org/dev/Accessibility

Atto makes use of contenteditable regions, and the rich text editing API supported by modern browsers. See https://developer.mozilla.org/en/docs/Rich-Text_Editing_in_Mozilla for further reading.

See the comparision (pros, cons, technical notes, missing features, etc) of Atto versus other candidate editors for Moodle 2.7 in [https://docs.moodle.org/dev/Editor_2.7 https://docs.moodle.org/dev/Editor_2.7]

For opening dialogues it is recommended to use M.core.dialogue : https://github.com/moodle/moodle/blob/master/lib/yui/src/notification/js/dialogue.js

Atto

2019-05-24T04:02:32Z

Damyon: /* Atto subplugin Javascript API */

{{Moodle 2.7}}

Atto is a javascript text editor built specifically for Moodle. Atto is the default text editor in Moodle from 2.7 onwards.

Atto is implemented as a standard Moodle text editor plugin ([[Editors]]). Most of the code is written in javascript as a standard Moodle YUI module.

Follow the development of ATTO here: https://tracker.moodle.org/browse/MDL-43996

==What does Atto mean?==

Really really small. (10^-18). It used to be :)

The name still ties in with some of the design concepts for Atto which is to be a simple, fast editor users.

==Where can I get Atto?==

GIT - and you can check here: https://moodle.org/plugins/view.php?plugin=editor_atto

==Atto Plugins==

All of the buttons/menus in Atto are implemented as true Moodle subplugins. This means that the subplugins can do anything a subplugin can do including, lang strings, db tables, yui modules.

There are a couple of extra functions/structure required for an Atto subplugin which are required in order to load a plugin on the toolbar.

==Structure of an Atto Plugin==

/lib.php
Optional. Only required if your plugin needs to implement one of the component callbacks listed below.

/settings.php
Optional. Only required if your plugin wants to support custom admin settings. See: [[Admin_settings#Individual_settings]] for more info on settings.

/version.php
Required. Moodle plugin version. See:[[version.php]] for more info on version files.

/lang/en/atto_pluginname.php
Required. Language file. This file is required and must at least define the language string 'pluginname'.

/yui/src/button/
Required. The plugin must implement a YUI module that will be included by the editor when the page loads. That YUI module must be named 'button' and must insert itself a class into the Y.M.<plugin name> namespace, with constructor that will be called to initialise the editor. It is recommended that you extend the EditorPlugin class as described below.
See: [[YUI/Modules]] for more information about YUI modules.

==Atto subplugin Php API==

Atto sub plugins can contain a lib.php file with 2 callbacks that will be looked for when the plugin is loaded.

The first is "XXX_strings_for_js" (example taken from atto_table plugin):

<pre>
/**
* Initialise the js strings required for this module.
*/
function atto_table_strings_for_js() {
global $PAGE;

$PAGE->requires->strings_for_js(array('createtable',
'accessibilityhint',
'headers',
'caption',
'columns',
'rows',
'numberofcolumns',
'numberofrows',
'both',
'edittable',
'addcolumnafter',
'addrowafter',
'movecolumnright',
'movecolumnleft',
'moverowdown',
'moverowup',
'deleterow',
'deletecolumn'),
'atto_table');
}

</pre>

The purpose of this callback is to allow the plugin to initialise the strings that it will use in it's user interface. Note: that the pluginname string for each plugin is automatically loaded, and if this is the only string your plugin requires, then it is not necessary to implement this callback in your plugin. See: [[JavaScript_guidelines#Getting_Moodle_to_load_your_JavaScript_files]] for more information on strings_for_js.

The second php callback that can be implemented in lib.php is: "XXX_params_for_js" (fictional example, not used in core):

<pre>
/**
* Return the js params required for this module.
* @return array of additional params to pass to javascript init function for this module.
*/
function atto_gambling_params_for_js() {
return array('bestodds' => '34 to 1', 'worstodds' => '5 to 1');
}

</pre>

If you are using this second callback, you need to specify these parameters in your JavaScript source file, passing it as an argument in the constructor:
<pre>
{
ATTRS: {
bestodds: {
value: '<defaultvalue>'
},
worstodds: {
value: '<defaultvalue>'
}
}
}
</pre>

==Atto subplugin Javascript API==
Atto subplugins must implement a yui module named "moodle-atto_pluginname-button".
This module will be automatically loaded when Atto is displayed on a page (and the subplugin is listed in the toolbar configuration).

The plugin:
* '''must''' register a class at Y.M.atto_PLUGINNAME.button;
* '''must''' provide a constructor; and
* '''''should''''' extend [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin.js Y.M.editor_atto.EditorPlugin].

It is up to the plugin author to decide how best to write their plugin, but it is highly advisable to extend EditorPlugin class, which provides a number of useful functions for dealing with the Editor, Toolbars, Keyboard Navigation, and other related areas.

Of particular interest are:

* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-buttons.js#L293 addBasicButton] - to add a basic button which directly uses document.execCommand with minimal effort;
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-buttons.js#L161] - to add a button giving you a greater degree of control via your own callback;
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-buttons.js#L337 addToolbarMenu] - to add a dropdown toolbar menu;
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin.js#L91 markUpdated] - should be called after making changes to the content area; and
* [https://github.com/moodle/moodle/blob/MOODLE_37_STABLE/lib/editor/atto/yui/src/editor/js/editor-plugin-dialogue.js#L54 getDialogue] - return a standard dialogue, creating one if it does not already exist.

=== Examples ===
You may also wish to take a look at some of the existing plugins for examples on how to create the different types:

* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/strike/yui/src/button/js/button.js A basic plugin];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/bold/yui/src/button/js/button.js A basic plugin which has a keyboard shortcuts];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/indent/yui/src/button/js/button.js A plugin with two buttons (one basic, one slightly more complex)];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/rtl/yui/src/button/js/button.js A plugin with multiple buttons which take arguments];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/title/yui/src/button/js/button.js A plugin which utilises a toolbar menu];
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/image/yui/src/button/js/button.js A plugin with a dialogue]; and
* [https://github.com/moodle/moodle/tree/master/lib/editor/atto/plugins/charmap/yui/src/button/js/button.js A plugin which uses templates to build its dialogue].

== See Also ==

Atto makes use of contenteditable regions, and the rich text editing API supported by modern browsers. See https://developer.mozilla.org/en/docs/Rich-Text_Editing_in_Mozilla for further reading.

See the comparision (pros, cons, technical notes, missing features, etc) of Atto versus other candidate editors for Moodle 2.7 in [https://docs.moodle.org/dev/Editor_2.7 https://docs.moodle.org/dev/Editor_2.7]

For opening dialogues it is recommended to use M.core.dialogue : https://github.com/moodle/moodle/blob/master/lib/yui/src/notification/js/dialogue.js

Accessibility

2019-05-24T02:26:36Z

Damyon: This change is intended as a major revision of https://docs.moodle.org/dev/Accessibility. Some considerations are: only link to standards documents (not opinions), examples link to an W3C Aria page, Moodle Accessibility Collaboration Group retained

Moodle is designed to provide equal functionality and information to all people. This means that there should be no barriers for people regardless of disabilities, assistive technologies that are used, different screen sizes and different input devices (e.g. mouse, keyboard and touchscreen).

== Moodle Accessibility Collaboration Group ==

To improve the accessibility and usability of Moodle, we have established this collaboration group to work together with Moodle developers, accessibility experts, administrators, IT professionals, and other interested entities and individuals. We welcome anyone who is interested in improving the accessibility of Moodle to join this group. You don’t need to be a technical guru or accessibility expert to join; however, it is expected that you are familiar with the basics of accessibility and are willing to dedicate a few hours each month to this collaboration effort.

This group meets once a month to discuss accessibility priorities, typically on the first Monday of each month.

Visit http://collaborate.athenpro.org/group/moodle to join the email list.

To review past meetings or to see upcoming meetings visit http://collaborate.athenpro.org/group/moodle/teleconferences/

== Authoring features ==

Moodle can be used by users to author content for other users. In some cases, accessibility features have been added to the authoring tools so that the content that is produced is as accessible as possible. An example is the “Atto text editor” which includes an “Accessibility checker” and an “Accessibility helper” which provide additional information for content authors on the accessibility of their content (like checks for sufficient contrast). The equations produced by the MathJax content filter have full accessibility enabled so they can be passed directly to the screen reader as maths content.

== Coding standards ==

All components in Moodle need to be available to use by all users. Accessibility needs to be part of the design of every new feature in Moodle.

For simple features with no requirement for an advanced user interface, simple adherence to standard HTML5 does provide an accessible feature. In this case, it is better to use no ARIA than it would be to use it incorrectly ([https://www.w3.org/TR/wai-aria-practices/#no_aria_better_bad_aria W3C no Aria]).

Bootstrap and Bootstrap components [https://getbootstrap.com/docs/4.0/getting-started/accessibility/#color-contrast do not support accessibility by default] and all features implemented with Bootstrap need to be checked and enhanced where necessary. The Boost theme contains an “aria” javascript module that does add accessibility to some default Bootstrap features (menus).

=== Colours ===

All text that is presented needs to be displayed in a colour with sufficient contrast to its background colour so that the text is legible for all users. The foreground and background colours should meet the [https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html WCAG requirement for contrast], which varies depending on the size of the text. This can be tested with the [https://wave.webaim.org/ WebAIM Web Accessibility Evaluation Tool].

Additionally, colour alone cannot be used to imply meaning. An example of a failure for this would be to display error messages in “red” with no other information to convey that this is an error message.

[https://www.w3.org/TR/WCAG21/#use-of-color WCAG use of colour]

=== Icons ===

Icons (Images) can be displayed in a variety of ways, and the correct use of icons will depend on the context in which they are used.

[https://www.w3.org/TR/WCAG21/#text-alternatives WCAG requirement for text alternatives]

==== Solitary Icons ====

Icons displayed on their own, as part of a link or as informative content must include accessible text to convey the meaning of the icon. For an image tag, this can be the “alt” attribute for the image tag. It can be valid to include both the “alt” attribute and the “title” attribute (shown when hovering with the mouse) so that all users can access the textual meaning of the icon.

==== Icons and Text ====

When an icon is displayed immediately before or after some text that also describes the meaning of the icon, it is redundant to repeat the same text twice. In this case, it is correct to hide the icon from screen readers by setting the “role” attribute to “presentation” or hiding it with the “aria-hidden” attribute set to “true”.

==== Multiple icons ====

When multiple icons are displayed in a row as links, it is important that each icon is large enough and has sufficient space around it so the icon can be easily clicked with the mouse.

The minimum valid size for a link target is 44 by 44 pixels.

[https://www.w3.org/TR/WCAG21/#target-size WCAG requirement for target size]

=== Keyboard Support ===

All components should be entirely operable through a keyboard-only interface.

[https://www.w3.org/TR/WCAG21/#keyboard-accessible WCAG requirement for keyboard accessibility]

Some important things to consider is that all components should be focusable with the keyboard (available in the tab sequence), and should allow the focus to be moved away using only the keyboard.

The element that currently has focus should have a visual focus indicator. [https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_focus_discernable_predictable ARIA focus management].

In some cases, a single component can contain many smaller components. In order to not pollute the page tab sequence, the parent element can exist in the tab sequence once and should maintain focus within its smaller components with arrow key navigation (roving tabindex or active descendant). [https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_general_within ARIA keyboard navigation inside components].

=== Forms ===

Moodle forms created with the standard forms library are designed to be accessible. Any custom (e.g. javascript) form or custom form elements must also be accessible.

* All form elements must have a label
* The form must be able to be completed entirely with the keyboard
* Invalid entries in the form fields should be indicated with the “aria-invalid” attribute set to “true”
* Warning messages for invalid form fields should be associated with the invalid field using the “aria-describedby” attribute.

[https://www.w3.org/TR/WCAG21/#error-identification WCAG error identification]

=== Presentation Only ===

Any component that contains no information or functionality that is not provided by other components on the page can be considered decorative only. Content that meets this description can be hidden from screen readers using a suitable technique (aria-hidden or presentation role).

[https://www.w3.org/TR/WCAG21/#dfn-pure-decoration WCAG pure decoration]

=== Landmark regions ===

The layout of each page of content should be separated into valid regions where each region has a unique label and the correct landmark role. This is typically done in the layout files of the theme.

[https://www.w3.org/TR/wai-aria-practices-1.1/#aria_landmark ARIA landmarks]

=== Page Titles ===

All pages should have a unique title that describes the current page.

[https://www.w3.org/TR/WCAG21/#page-titled WCAG page titled]

=== Advanced UX Widgets ===

When it is determined that an advanced interface is required (typically one that relies on javascript), a minimum set of principles need to be applied to make sure that the feature “provides equal functionality and information to all people”. Each use case is different, but a minimum set of things to be checked are:

* Does this component work entirely when accessed only via the keyboard?
* Does this component map to any widget from the [https://www.w3.org/TR/wai-aria-practices-1.1/ ARIA Authoring Practices] document and if so, does it implement all of the “Keyboard Interaction” and “WAI-ARIA Roles, States and Properties” listed for that widget?

== External Resources ==

* [https://www.w3.org/WAI/standards-guidelines/ W3C Accessibility Standards Overview]
* [https://www.w3.org/TR/wai-aria-1.1/ Accessible Rich Internet Applications (WAI-ARIA) 1.1]
* [https://www.w3.org/TR/wai-aria-practices/ WAI-ARIA Authoring Practices 1.1]
* [https://www.w3.org/TR/WCAG21/ Web Content Accessibility Guidelines (WCAG) 2.1]
* [https://www.w3.org/TR/ATAG20/ Authoring Tool Accessibility Guidelines (ATAG) 2.0]
* [https://www.w3.org/TR/UAAG20/ User Agent Accessibility Guidelines (UAAG) 2.0]

== Accessibility Tools ==

Moodle officially supports the following screen reader/browser configurations:

* Microsoft Edge, Jaws 15+ (Latest version recommended)
* Mozilla Firefox, NVDA 2014.1+ (Latest version recommended)

Screen readers:

* [https://www.nvaccess.org/ NVDA Screen Reader] (Windows)
* [http://www.freedomscientific.com/ JAWS Screen Reader] (Windows)
* [http://www.chromevox.com/ Chromevox Screen Reader ] (Linux, Chrome OS, Windows, Mac OS X)
* [https://help.gnome.org/users/orca/stable/ Orca Screen Reader] (Linux)

Accessibility tools:

* [https://wave.webaim.org/extension/ WebAIM Web Accessibility Evaluation Tool] (Chrome, Firefox)
* [https://developers.google.com/web/tools/chrome-devtools/accessibility/reference Chrome Accessibility Dev Tools] (Chrome)
* [http://www.w3.org/WAI/ER/tools/complete W3C Accessibility Tool Listing]

== International Legislation ==

=== USA ===

* [http://www.section508.gov/ Section 508]

=== UK ===

* [http://www.legislation.gov.uk/ukpga/2010/15/contents Equality Act 2010]
* [http://www.equalityhumanrights.com/advice-and-guidance/public-sector-equality-duty/ Public sector equality duty]
* [http://www.parliament.the-stationery-office.co.uk/pa/ld200001/ldbills/003/2001003.htm SENDA - Special Educational Needs and Disability Act/Bill]

=== Germany ===

* [http://www.einfach-fuer-alle.de/artikel/bitv/ Barrierefreie Informationstechnik-Verordnung - BITV]

=== France ===

* [https://references.modernisation.gouv.fr/rgaa-accessibilite/ Référentiel Général d’Accessibilité des Administrations - RGAA]

=== European Union ===

* [https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=COM:2015:0615:FIN European Accessibility Act]

MForm Modal

2019-04-01T03:13:47Z

Damyon: /* Step 2 - Add a new AMD module to show the modal */

== Advanced tutorial: MForm in a modal ==

{{Note| This tutorial is for advanced Moodle devs. You need to know a lot of APIs in order to understand all of this. See the list of related pages at the end of this tutorial for some of them. }}

This is a walkthrough of the steps required to convert an existing page in moodle with an mform - to an mform that displays in a popup and submits data via AJAX.

If you want to get all the code in this walkthrough - here is the link to the branch on github: https://github.com/damyon/moodle/tree/MFORM_AJAX

Lets get started - first lets pick a page (spins a wheel)..... "Create a group".

We will modify the "Create group" button on the groups page to open a modal with the create a group form, instead of directing you to a new page. Whether this is actually a useful improvement or not does not really matter for now - we are just trying to show how to do it.

=== Step 1 - Attach some javascript to the button ===

The first step is to add some javascript to the "Create group" button so that we can open a modal. The page we are modifying is group/index.php which we get by visiting the page and checking the url. If we read through that page, we can see it uses a renderable to generate the HTML for the page.

<code php>
$renderable = new \core_group\output\index_page($courseid, $groupoptions, $selectedname, $members, $disableaddedit, $disabledelete,
$preventgroupremoval);

$output = $PAGE->get_renderer('core_group');
echo $output->render($renderable);
</code>

The renderer is in group/classes/output/renderer.php and the renderable is in group/classes/output/index_page.php (see [[Automatic_class_loading]]) for how we worked that out.

Looking at the render_index_page function of the renderer (see https://docs.moodle.org/dev/Output_renderers) we can see that this renderer uses [[Templates]] to separate the HTML from the php (good).

<code php>
public function render_index_page(index_page $page) {
$data = $page->export_for_template($this);
return parent::render_from_template('core_group/index', $data);
}
</code>

The name of the template is "core_group/index". This maps to a mustache template located at group/templates/index.mustache.

Hooray - we found the HTML we want to modify to add our javascript.

This template already has a {{#js}} block we can use to add our custom javascript. We don't want to code all the javascript in a mustache template - we will just add the minimal code to call a new AMD module for creating a group.

<code javascript>
{{#js}}
require(['jquery', 'core/yui'], function($) {
$("#groups").change(function() {
M.core_group.membersCombo.refreshMembers();
});
M.core_group.init_index(Y, "{{wwwroot}}", {{courseid}});
var undeletableGroups = JSON.parse('{{{undeletablegroups}}}');
M.core_group.groupslist(Y, undeletableGroups);
});

// New code to create groups in a modal.
require(['core_group/newgroup'], function(NewGroup) {
NewGroup.init('[data-action=creategroupmodal]', {{contextid}});
});
{{/js}}
</code>

We added contextid to the template (We always need a contextid to use the fragments API) but it's not in the context for the template yet. We need to add it to the export_for_template function for the renderable group/classes/output/index_page.php

<code php>
$context = context_course::instance($this->courseid);
$data->contextid = $context->id;
</code>

We added that code at the end to call the core_group/newgroup AMD module. The argument we will pass to this new module is a "selector" which is a flexible way to allow this same module to be used on other pages with different markup. In this case for the selector, we are looking for a node with a data attribute. We also need to modify the create group button to contain this data-attribute. In general data-attributes are a great way to add hooks to the DOM that are used for Javascript, but should not affect the appearance (unlike classes which are just gross and disgusting).

<pre>
<input type="submit" name="act_showcreateorphangroupform" id="showcreateorphangroupform" data-action="creategroupmodal" value="{{#str}}creategroup, group{{/str}}" class="btn btn-default" />
</pre>

=== Step 2 - Add a new AMD module to show the modal ===

So we tried to load an AMD module "core_group/newgroup" but it doesn't exist yet. Time to create it.

Make a new folder at group/amd/src. "group" in this case is the directory for the core_group component, so amd modules for this component go in amd/src relative to that directory. When we run [[Grunt]] it will build the javascript to group/amd/build.

Make a new file in this group/amd/src folder named "newgroup.js". This will be our new javascript module. It exports a single function "init" which attaches event listeners to the elements that match the selector.

<code javascript>

/**
* Add a create new group modal to the page.
*
* @module core_group/newgroup
* @class NewGroup
* @package core_group
* @copyright 2017 Damyon Wiese <damyon@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
define(['jquery', 'core/str', 'core/modal_factory', 'core/modal_events', 'core/fragment', 'core/ajax', 'core/yui'],
function($, Str, ModalFactory, ModalEvents, Fragment, Ajax, Y) {

/**
* Constructor
*
* @param {String} selector used to find triggers for the new group modal.
* @param {int} contextid
*
* Each call to init gets it's own instance of this class.
*/
var NewGroup = function(selector, contextid) {
this.contextid = contextid;
this.init(selector);
};

/**
* @var {Modal} modal
* @private
*/
NewGroup.prototype.modal = null;

/**
* @var {int} contextid
* @private
*/
NewGroup.prototype.contextid = -1;

/**
* Initialise the class.
*
* @param {String} selector used to find triggers for the new group modal.
* @private
* @return {Promise}
*/
NewGroup.prototype.init = function(selector) {
var triggers = $(selector);
// Fetch the title string.
return Str.get_string('creategroup', 'core_group').then(function(title) {
// Create the modal.
return ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: title,
body: this.getBody()
}, triggers);
}.bind(this)).then(function(modal) {
// Keep a reference to the modal.
this.modal = modal;

// Forms are big, we want a big modal.
this.modal.setLarge();

// We want to reset the form every time it is opened.
this.modal.getRoot().on(ModalEvents.hidden, function() {
this.modal.setBody(this.getBody());
}.bind(this));

// We want to hide the submit buttons every time it is opened.
this.modal.getRoot().on(ModalEvents.shown, function() {
this.modal.getRoot().append('<style>[data-fieldtype=submit] { display: none ! important; }</style>');
}.bind(this));

// We catch the modal save event, and use it to submit the form inside the modal.
// Triggering a form submission will give JS validation scripts a chance to check for errors.
this.modal.getRoot().on(ModalEvents.save, this.submitForm.bind(this));
// We also catch the form submit event and use it to submit the form with ajax.
this.modal.getRoot().on('submit', 'form', this.submitFormAjax.bind(this));

return this.modal;
}.bind(this));
};

/**
* @method getBody
* @private
* @return {Promise}
*/
NewGroup.prototype.getBody = function(formdata) {
if (typeof formdata === "undefined") {
formdata = {};
}
// Get the content of the modal.
var params = {jsonformdata: JSON.stringify(formdata)};
return Fragment.loadFragment('core_group', 'new_group_form', this.contextid, params);
};

/**
* @method handleFormSubmissionResponse
* @private
* @return {Promise}
*/
NewGroup.prototype.handleFormSubmissionResponse = function() {
this.modal.hide();
// We could trigger an event instead.
// Yuk.
Y.use('moodle-core-formchangechecker', function() {
M.core_formchangechecker.reset_form_dirty_state();
});
document.location.reload();
};

/**
* @method handleFormSubmissionFailure
* @private
* @return {Promise}
*/
NewGroup.prototype.handleFormSubmissionFailure = function(data) {
// Oh noes! Epic fail :(
// Ah wait - this is normal. We need to re-display the form with errors!
this.modal.setBody(this.getBody(data));
};

/**
* Private method
*
* @method submitFormAjax
* @private
* @param {Event} e Form submission event.
*/
NewGroup.prototype.submitFormAjax = function(e) {
// We don't want to do a real form submission.
e.preventDefault();

var changeEvent = document.createEvent('HTMLEvents');
changeEvent.initEvent('change', true, true);

// Prompt all inputs to run their validation functions.
// Normally this would happen when the form is submitted, but
// since we aren't submitting the form normally we need to run client side
// validation.
this.modal.getRoot().find(':input').each(function(index, element) {
element.dispatchEvent(changeEvent);
});

// Now the change events have run, see if there are any "invalid" form fields.
var invalid = $.merge(
this.modal.getRoot().find('[aria-invalid="true"]'),
this.modal.getRoot().find('.error')
);

// If we found invalid fields, focus on the first one and do not submit via ajax.
if (invalid.length) {
invalid.first().focus();
return;
}

// Convert all the form elements values to a serialised string.
var formData = this.modal.getRoot().find('form').serialize();

// Now we can continue...
Ajax.call([{
methodname: 'core_group_submit_create_group_form',
args: {contextid: this.contextid, jsonformdata: JSON.stringify(formData)},
done: this.handleFormSubmissionResponse.bind(this, formData),
fail: this.handleFormSubmissionFailure.bind(this, formData)
}]);
};

/**
* This triggers a form submission, so that any mform elements can do final tricks before the form submission is processed.
*
* @method submitForm
* @param {Event} e Form submission event.
* @private
*/
NewGroup.prototype.submitForm = function(e) {
e.preventDefault();
this.modal.getRoot().find('form').submit();
};

return /** @alias module:core_group/newgroup */ {
// Public variables and functions.
/**
* Attach event listeners to initialise this module.
*
* @method init
* @param {string} selector The CSS selector used to find nodes that will trigger this module.
* @param {int} contextid The contextid for the course.
* @return {Promise}
*/
init: function(selector, contextid) {
return new NewGroup(selector, contextid);
}
};
});
</code>

Some things to note: This is the standard boilerplate for an AMD module that only returns a list of functions (in this case one function named "init"). Everything else is private to the module. There is a bunch of code here but the main parts are:

a) opening the modal
b) using the fragment api to load the body of the modal
c) catching the submit from the form so we can do something else with it

=== Step 3 - Add a callback for the fragments API to load the form ===

In the JS above we load the fragment for new_group_form from the core_group component. We need to add a callback to the core_group component that renders this fragment. This is a new global function in group/lib.php

<code php>
/**
* Serve the new group form as a fragment.
*
* @param array $args List of named arguments for the fragment loader.
* @return string
*/
function core_group_output_fragment_new_group_form($args) {
global $CFG;

require_once($CFG->dirroot . '/group/group_form.php');
$args = (object) $args;
$context = $args->context;
$o = '';

$formdata = [];
if (!empty($args->jsonformdata)) {
$serialiseddata = json_decode($args->jsonformdata);
parse_str($serialiseddata, $formdata);
}

list($ignored, $course) = get_context_info_array($context->id);
$group = new stdClass();
$group->courseid = $course->id;

require_capability('moodle/course:managegroups', $context);
$editoroptions = [
'maxfiles' => EDITOR_UNLIMITED_FILES,
'maxbytes' => $course->maxbytes,
'trust' => false,
'context' => $context,
'noclean' => true,
'subdirs' => false
];
$group = file_prepare_standard_editor($group, 'description', $editoroptions, $context, 'group', 'description', null);

$mform = new group_form(null, array('editoroptions' => $editoroptions), 'post', '', null, true, $formdata);
// Used to set the courseid.
$mform->set_data($group);

if (!empty($args->jsonformdata)) {
// If we were passed non-empty form data we want the mform to call validation functions and show errors.
$mform->is_validated();
}

ob_start();
$mform->display();
$o .= ob_get_contents();
ob_end_clean();

return $o;
}
</code>

Most of this code is the same as in group/group.php to build the mform. Note we accept a parameter which is the json encoded form data so we can pass it to the mform constructor. This is normally done by mforms parsing data from GET and POST params, but when we are in an ajax script we need to explicitly set the data like this. We also need to call is_validated() so the mform will render with error messages if this is required.

=== Step 4 - Add a webservice function to handle the form submission ===
We need to add a new webservice function to handle our ajax form submission. This is webservice is different to a normal one in that the list of parameters are accepted in one json encoded blob, rather than separated and validated properly. This is because we want the mform to perform the validation for us.

group/externallib.php

<code php>
/**
* Describes the parameters for submit_create_group_form webservice.
* @return external_function_parameters
*/
public static function submit_create_group_form_parameters() {
return new external_function_parameters(
array(
'contextid' => new external_value(PARAM_INT, 'The context id for the course'),
'jsonformdata' => new external_value(PARAM_RAW, 'The data from the create group form, encoded as a json array')
)
);
}

/**
* Submit the create group form.
*
* @param int $contextid The context id for the course.
* @param string $jsonformdata The data from the form, encoded as a json array.
* @return int new group id.
*/
public static function submit_create_group_form($contextid, $jsonformdata) {
global $CFG, $USER;

require_once($CFG->dirroot . '/group/lib.php');
require_once($CFG->dirroot . '/group/group_form.php');

// We always must pass webservice params through validate_parameters.
$params = self::validate_parameters(self::submit_create_group_form_parameters(),
['contextid' => $contextid, 'jsonformdata' => $jsonformdata]);

$context = context::instance_by_id($params['contextid'], MUST_EXIST);

// We always must call validate_context in a webservice.
self::validate_context($context);
require_capability('moodle/course:managegroups', $context);

list($ignored, $course) = get_context_info_array($context->id);
$serialiseddata = json_decode($params['jsonformdata']);

$data = array();
parse_str($serialiseddata, $data);

$warnings = array();

$editoroptions = [
'maxfiles' => EDITOR_UNLIMITED_FILES,
'maxbytes' => $course->maxbytes,
'trust' => false,
'context' => $context,
'noclean' => true,
'subdirs' => false
];
$group = new stdClass();
$group->courseid = $course->id;
$group = file_prepare_standard_editor($group, 'description', $editoroptions, $context, 'group', 'description', null);

// The last param is the ajax submitted data.
$mform = new group_form(null, array('editoroptions' => $editoroptions), 'post', '', null, true, $data);

$validateddata = $mform->get_data();

if ($validateddata) {
// Do the action.
$groupid = groups_create_group($validateddata, $mform, $editoroptions);
} else {
// Generate a warning.
throw new moodle_exception('erroreditgroup', 'group');
}

return $groupid;
}

/**
* Returns description of method result value.
*
* @return external_description
* @since Moodle 3.0
*/
public static function submit_create_group_form_returns() {
return new external_value(PARAM_INT, 'group id');
}
</code>

We also need to add the webservice to lib/db/services.php and bump the moodle version number.

lib/db/services.php

<code php>
'core_group_submit_create_group_form' => array(
'classname' => 'core_group_external',
'methodname' => 'submit_create_group_form',
'classpath' => 'group/externallib.php',
'description' => 'Creates a group from submitted form data',
'ajax' => true,
'type' => 'write',
'capabilities' => 'moodle/course:managegroups',
),
</code>

=== Summary ===
This shows a working example of displaying an mform in a modal with server side validation. It was a bit messy and fiddly with quite a few things that can catch you out - but there are benefits too - we re-used an existing mform with all it's validation logic and mform elements including a text editor, file manager and password field. This will work for auto-complete fields and other advanced fields too.

=== Related APIs ===
* [[Javascript_Modules]]
* [[Form_API]]
* [[AJAX]]
* [[Web_services_API]]
* [[Fragment]]
* [[Templates]]

Prototypes

2019-03-14T03:57:43Z

Damyon: /* Prototype for Badgr.io */

This page is where Moodle HQ shares early work on new features that will be included in coming versions of Moodle.
For an overview of new features please see the [[Roadmap]] page.

We use it to show features currently in development so that people can try them and provide feedback.

Feel free to explore the sites, but as we are seeking feedback, please follow instructions for each prototype and be prepared to participate in forum discussions and surveys.

You can provide feedback in the [https://moodle.org/mod/forum/view.php?id=55 general developer forum] or the [https://moodle.org/mod/forum/view.php?id=8052 future major features forum].

Thank you for helping us help you.

==Prototypes for Moodle 3.7 features==
Each prototype site has a short summary of the project, with a status update and login details.

===Forum update===
This project is collaborative project with and sponsored by the [https://moodleassociation.org/ Moodle User Association].

The scope for Moodle 3.7 includes:
* Forum to use mustache templates
* Accessibility improvements
* In-page reply to posts in a discussion
* In-page creation of discussions
* Ability to Star/Favourite a discussion
* Ability to manually lock a discussion
* Ability to sort the list of discussions in a number of ways
* Ability to reply privately to a post.

[https://forum.moodledemo.net Forum prototype site]

===Badges support for Open Badges 2.0===
This project is an upgrade to the backpack support for Badges so that Badges can be shared with a backpack that is compliant with the Open Badges v2.0 specification. This will allow publishing of Badges to a Badgr backpack. Badgr backpacks are taking over from Mozilla Open Badges.

The scope of this feature for Moodle 3.7 includes:
* [https://badgr.io Badgr] backpack support
* Upgrades for exiting connections to Mozilla Open Badges
* Moodle Competencies can be selected as a criteria for a Badge

[https://backpack.moodledemo.net Badgr backpack prototype site]

Peer reviewing

2017-12-18T08:55:56Z

Damyon: /* Sanity check */

=Process=

Peer review process helps to prepare the issue for integration. The peer reviewer is another developer who was not involved in the development process on the issue and therefore can take a fresh look and notice something that original developer might have forgotten during development. It is important to check that the bug actually is present and the code fixes it without creating new regressions.

==Completing Peer review as a community member==

Any other developer can review any change. That is why it is called 'peer' review. However, not everyone has the necessary permissions in the tracker to click the buttons 'Start peer review', 'Finish peer review' etc. This should not discourage you from looking at other contributors code and providing comments and feedback. The issue will still need to wait for someone with the right permissions to come along and click the buttons, but they can read your review and then need do no more than double-check some points, which will save a lot of time.

To provide feedback to the developer, leave the issue in "Waiting for Peer Review" (since you don't have permission to do anything else, and also that makes it easy for someone with sufficient permissions to find the issue and move it forwards). Review the code using the checklist below, including any appropriate comments. Once finished, please post a comment clearly stating the outcome of your review. If you think it needs more work then indicate what needs to be changes. If you are happy with the patch, leave a clear comment that you believe this is ready to be made part of Moodle. This can then easily be seen by a HQ developer or component lead and they can quickly take appropriate action.

If a followup review happens to identify something you did not find, you have an opportunity to expand your knowledge and provide better reviews in the future as well as having saved everybody else some time.

Feedback to indicate the issue is ready to progress might look like the following;

Thanks again for your contribution. I have reviewed the patch:
 
[Copy and paste the checklist here, and complete it]
 
I don't have permission to use the peer review buttons on this issue. I hope that someone with sufficient permissions will move the issue forwards soon.


Feedback to indicate the issue requires further work might look like the following;

Thanks for providing a patch. I think the following points require further work
 
[Copy and paste the checklist here, and complete it]
 
Please indicate If you are willing to continue working on this issue and complete the solution.


==Peer review for development by HQ or a known common contributor==

When code comes from a HQ developer or external developer who has been contributing significantly to Moodle and is well acquainted with Moodle standards, peer review is limited to checking the code according to the Checklist below.

If everything is fine, the peer reviewer submits the issue for integration.

If some additional work is needed or the author specifically asked not to submit for integration yet, the peer reviewer clicks on “Finish peer review” and the issue state returns to “Development in progress”. Usually the name of the peer reviewer stays on the issue and if a second peer review is requested it is expected that the same Peer reviewer picks it up. If the peer reviewer is not able to do the second review, they should remove their name and comment about it. Otherwise the issue does not appear on “waiting for peer review” dashboard. Please remember that not all jira users have permission to submit for integration.

==Peer review for external developers==

When the code has come from an external developer, the peer reviewer will also help the developer to lead the issue to integration. In this case the peer reviewer should not use “Finish peer review” button.

If the issue needs additional work, the peer reviewer comments about the suggested changes but does not change the status of the issue and it remains as “Peer review in progress”. If the author of the patch does not reply in 4 days, the peer reviewer may select either to complete the patch themselves or reopen the issue. The decision should be based on the amount of work required to complete the solution, for example, changing coding style or commit message, rebasing, backporting, adding testing instructions, etc. should be performed by the peer reviewer. This may require picking the commits into reviewer’s git branch.

It is very important to give the credit to the author of the code by either keeping their authorship on the commit or adding “Thanks to XXXX for providing the patch” to the commit message. If the author of the patch is not in jira-developers group the special user 'moodle.com' should be entered in Assignee field.

There could be situations when the patch is incomplete, does not fix the original issue, creates regressions or otherwise is not correct. As stated above, the peer reviewer should comment about it and wait for the feedback from the author. If there is no feedback, or the author can not work on this issue any more, and the peer reviewer also does not find it easy and important enough to complete, the issue needs to be reopened. Button “Fail peer review” (available to HQ developers only) will reset the issue status to “Reopened”. On this screen peer reviewer should remove assignee, peer reviewer and “patch” label from the issue. This way issue will become available again for anybody who want to work on it. All communication will remain in comments and issue history.

If the issue has passed peer review but the integrator or tester has raised some questions about it, then normally the developer who created the patch would be expected to respond. If they do no respond quickly enough, then the peer reviewer is expected to step in and take responsibility for the change they reviewed.

Once the issue is ready for integration, you can submit it to integration on behalf of the developer. Most external developers (those who are not in the jira-developers group) do not have permission to submit their own issues to integration so cannot do it themselves.

==Replies templates==


Thanks for providing a patch. 
I have reviewed your code and can confirm that it addresses the reported issue. We would like to include it in core. Moodle values its contributors and tries to give them credit when possible. If you are interested in your name appearing on the https://moodle.org/dev/contributions.php page you can create a git commit that we will then pull into Moodle. You can learn more about Git and how Moodle uses it at <nowiki>[Git for developers|https://docs.moodle.org/dev/Git_for_developers]</nowiki> page. Please let me know if you want to prepare a git branch. Or if you don’t have time to go through the whole process at the moment I can pick your patch myself.



Thanks for providing a patch. 
Your code looks almost ready for integration into Moodle. There are just some little things that need to be changed to comply with Moodle standards. Can you please take a look at the review results below and tell me if you are able to modify your branch to address them.



I have reviewed your patch, it addresses the problem and complies with Moodle standards. I'm pushing this issue for integration. Following Moodle <nowiki>[Process|https://docs.moodle.org/dev/Process]</nowiki> it will go through integration review and testing before being included in the product. There might be additional questions from an integrator and/or a tester at those stages. It would be appreciated if you read tracker emails and can reply to questions if needed. If everything goes well during the next two stages your issue will be included in the next weekly release and your count on https://moodle.org/dev/contributions.php page will increase. 
Thanks again for your contribution.



Thanks for providing a patch. 
Unfortunately this patch does not fully address the reported issue. ... DETAILS... 
Even though the code does solve the issue in the short-term it is very likely to create regressions ..... 
I have spent some time reviewing the patch and I would recommend that you ..... 
Please let me know If you are willing to continue working on this issue and complete the solution.


=Checklist=

These are points to consider while peer-reviewing issues. Further explanation below.

[] Syntax
[] Output
[] Language
[] Databases
[] Testing (instructions and automated tests)
[] Security
[] Performance and Clustering
[] Documentation
[] Git
[] Third party code
[] Sanity check
[] Icons

Acceptable check-marks are Y (for yes), N (for no) or - (for not applicable). All N check-marks should be accompanied by an explanation of the problem that still needs to be addressed.

==Syntax==
To allow the community of Moodle developers to work together, conventions should be followed.

* The code is easy to understand and, where it isn't, comments have been provided.
* Variables are named correctly (all lower case, no camel-case, no underscores).
* Functions are named correctly (all lower case, no camel-case, underscores allowed).
* PHP DocBlocks have been updated and adhere to [[Coding_style#Documentation_and_comments|coding style guide]].
* Where functions are being removed, the [[Deprecation]] process is followed.
* The code doesn't use [[Deprecated_functions_in_2.0|deprecated functions]].
* $_GET, $_POST, $_REQUEST, $_COOKIE, and $_SESSION are never used.

See the [[Coding style]] guide for details.

==Output==
Output needs to be controlled by renderers to achieve consistency and correct application of themes.

Ensure that:
* output renders are used to generate output strings, including HTML tags;
* HTML output is valid XHTML;
* no inline styles have been used in HTML output (everything has to be in CSS);
* CSS has been added to the appropriate CSS files (base, specific area, sometimes canvas); and
* the code doesn't use buffered output unless absolutely necessary.
* all visual output has a RTL alternative included

feedback any notices (E_STRICT, etc) seen into the MDL.

==Language==
To achieve appropriate internationalisation of Moodle, language strings must be managed correctly.

Ensure that:
* new language strings are named correctly (all lower case, no camel-case, underscores are permissible in some cases);
* help strings are named and formatted as described in [[Help strings]];
* language strings are used instead of hard-coded strings for text output;
* language strings have not been removed or renamed, had their meaning changed or had their parameters changed in stable branches (permitted only in master); and
* [https://docs.moodle.org/dev/Commit_cheat_sheet#Include_AMOS_script_in_the_commit_if_needed AMOS commands] have been specified when moving or copying language strings.

==Databases==
DB calls are the greatest performance bottleneck in Moodle.

If there is SQL code you can test quickly then do so.

Ensure that:
* there are minimal DB calls (no excessive use of the DB); and
* the code uses SQL compatible with all the supported DB engines (check all selected fields appear in an 'order by' clause).

==Testing instructions and automated tests==
It is the developer's responsibility to test code before integration. Issues should not be sent for peer review without tests so that the peer reviewer can assess their quality and use them to consider the scope of the issue.

Ensure that:
* there are specific testing instructions that state how, as well as what, to test. Please ensure that the testing instructions are in the correct format: [https://docs.moodle.org/dev/Behat Behat gherkin];
* the assignee has tested according to the instructions and verified that they are passing (This is the responsibility of the assignee, not the peer reviewer)
* new unit tests have been added when there is a change in functionality; and
* '''unit tests pass''' for related areas where changes have been made.
* '''Behat tests pass''' for related areas where changes have been made, especially when it involved UI changes.

==Security==
The user community relies on Moodle being responsibly secure.

Ensure that:
* user login is checked where an identity is needed;
* sesskey values are checked before all write actions where appropriate (some read actions as well);
* capabilities are checked where roles differ; and
* if the issue itself is a [[Security|security]] issue, the [[Process#Security_issues|security process]] is being followed.
** Ensure that the fix is '''not''' available in a public repository (ie. a personal Github account); stand-alone patches should be provided instead.
** The issue will not be integrated until just before the next minor version release.

==Performance and clustering==
It is easy to write code that works sufficiently well when you are working on either small sets of data or with a small number of active users. Picking performance issues can be quite difficult and can required a complex level of understanding of both the section of code being reviewed, but also other parts that interact with it.

Clustering is when the same code is run on different computers and an end user could send each request to a different computer. This can produce a number of concurrency issues if not thought through. One example is; If you complete an opcache_reset(), no other server except the one you ran it on knows that it happened. So data can get out of sync.

Ensure that:
* Any filesystem, database or cache accesses are done in the most efficient way.
* That any code or function that appear expensive are not in critical paths. eg; They don't load on every page.
* The least possible code is running to complete the task, especially looking for hidden loops. They can appear from calling functions.
* Any code that runs is not specific to a single node. (eg opcache_reset()) The ensures clusters will run correctly.
* If the code could affect performance at all, make sure there is a comment noting what was considered.
** What they did to mitigate performance impact, or why they thought it wasn't an issue.
** Why they made certain trade-offs.

==Documentation==
Work does not stop when code is integrated.

Ensure that:
* Appropriate [[Tracker_issue_labels|labels]] have been added when there has been a function change, particularly
** docs_required (any functional change, usually paired with ui_change),
** dev_docs_required (any change to APIs, usually paired with api_change),
** ui_change (any functional change, usually paired with docs_required, except ui_change remains permanetly),
** api_change (any change to APIs that devs will need to know about, usually paired with dev_docs_required, except api_change remains permanetly),
** unit_test_required and acceptance_test_required, when there are api or ui changes needing improved coverage, and
** qa_test_required (significant functional change, not covered by unit/acceptance ones).
* Also, verify that the components for the issue are correctly set, so maintainers (subscribed by default) will be mailed about issues early in the process.

==Git==
Ensure that:
* the commit matches the [[Coding style#Git_commits|Coding style]]
* the Git history is clean and the work has been rebased to logical commits; and
* the original author of the work provided as a patch has been given credit within the commit (as author of in the commit message if changes were made).

==Third party code==
Does the change contain third party code? If so, ensure that:

* The code is licensed under a [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| GPL compatible license].
* The instructions for upgrading/importing the library and contained within a readme_moodle.txt file.
* The library is recorded in a thirdparty.xml file, including licensing information.
* Third party code has been scanned to check for url accessible entry points that could be exploited. These should either be disabled, or if required functionality they should be checked for security weaknesses.
* Does not duplicate the functionality of any existing api or third party library in core.
* Any modifications to third party code are recorded in readme_moodle.txt

==Sanity check==
Ensure that:
* the code seems to solve the described problem completely within its reported scope (and further issues have been created to resolve remaining parts or further refactoring);
* the code makes sense in relation to the broader codebase (look at the whole function, not just the altered code); and
* the developer has searched for and fixed other areas that may also have been affected by the same problem.
* verify that the related component maintainers, if known, have participated and are aware of the issue (as assignee, or existing comments...). If they have not, please perform a friendly <tt>@mention</tt> to make them aware about the issue. A list of component leads is available here: https://docs.moodle.org/dev/Component_Leads
* if any version numbers have been changed in [[version.php]] files, then the changes follow [[Moodle_versions#How_to_increment_version_numbers_in_core|the rule for updating version numbers in core]].
* there are comments on tracker explaining why current approach was taken and why other options (especially large issues). If not comment asking them to explain

==Icons==
Are new icons being introduced? If so, ensure that:
* the icons abide by our [https://docs.moodle.org/dev/Moodle_icons icon guidelines] with regards to size, design and format
* the icons are do not unnecessarily add new ways of expressing existing concepts
* the icons are in a pix folder that makes sense

==See Also==
* [http://moodle.org/plugins/view.php?plugin=local_codechecker Code checker plugin]

[[Category: Processes]]

Peer reviewing

2017-12-18T08:55:20Z

Damyon: /* Checklist */

=Process=

Peer review process helps to prepare the issue for integration. The peer reviewer is another developer who was not involved in the development process on the issue and therefore can take a fresh look and notice something that original developer might have forgotten during development. It is important to check that the bug actually is present and the code fixes it without creating new regressions.

==Completing Peer review as a community member==

Any other developer can review any change. That is why it is called 'peer' review. However, not everyone has the necessary permissions in the tracker to click the buttons 'Start peer review', 'Finish peer review' etc. This should not discourage you from looking at other contributors code and providing comments and feedback. The issue will still need to wait for someone with the right permissions to come along and click the buttons, but they can read your review and then need do no more than double-check some points, which will save a lot of time.

To provide feedback to the developer, leave the issue in "Waiting for Peer Review" (since you don't have permission to do anything else, and also that makes it easy for someone with sufficient permissions to find the issue and move it forwards). Review the code using the checklist below, including any appropriate comments. Once finished, please post a comment clearly stating the outcome of your review. If you think it needs more work then indicate what needs to be changes. If you are happy with the patch, leave a clear comment that you believe this is ready to be made part of Moodle. This can then easily be seen by a HQ developer or component lead and they can quickly take appropriate action.

If a followup review happens to identify something you did not find, you have an opportunity to expand your knowledge and provide better reviews in the future as well as having saved everybody else some time.

Feedback to indicate the issue is ready to progress might look like the following;

Thanks again for your contribution. I have reviewed the patch:
 
[Copy and paste the checklist here, and complete it]
 
I don't have permission to use the peer review buttons on this issue. I hope that someone with sufficient permissions will move the issue forwards soon.


Feedback to indicate the issue requires further work might look like the following;

Thanks for providing a patch. I think the following points require further work
 
[Copy and paste the checklist here, and complete it]
 
Please indicate If you are willing to continue working on this issue and complete the solution.


==Peer review for development by HQ or a known common contributor==

When code comes from a HQ developer or external developer who has been contributing significantly to Moodle and is well acquainted with Moodle standards, peer review is limited to checking the code according to the Checklist below.

If everything is fine, the peer reviewer submits the issue for integration.

If some additional work is needed or the author specifically asked not to submit for integration yet, the peer reviewer clicks on “Finish peer review” and the issue state returns to “Development in progress”. Usually the name of the peer reviewer stays on the issue and if a second peer review is requested it is expected that the same Peer reviewer picks it up. If the peer reviewer is not able to do the second review, they should remove their name and comment about it. Otherwise the issue does not appear on “waiting for peer review” dashboard. Please remember that not all jira users have permission to submit for integration.

==Peer review for external developers==

When the code has come from an external developer, the peer reviewer will also help the developer to lead the issue to integration. In this case the peer reviewer should not use “Finish peer review” button.

If the issue needs additional work, the peer reviewer comments about the suggested changes but does not change the status of the issue and it remains as “Peer review in progress”. If the author of the patch does not reply in 4 days, the peer reviewer may select either to complete the patch themselves or reopen the issue. The decision should be based on the amount of work required to complete the solution, for example, changing coding style or commit message, rebasing, backporting, adding testing instructions, etc. should be performed by the peer reviewer. This may require picking the commits into reviewer’s git branch.

It is very important to give the credit to the author of the code by either keeping their authorship on the commit or adding “Thanks to XXXX for providing the patch” to the commit message. If the author of the patch is not in jira-developers group the special user 'moodle.com' should be entered in Assignee field.

There could be situations when the patch is incomplete, does not fix the original issue, creates regressions or otherwise is not correct. As stated above, the peer reviewer should comment about it and wait for the feedback from the author. If there is no feedback, or the author can not work on this issue any more, and the peer reviewer also does not find it easy and important enough to complete, the issue needs to be reopened. Button “Fail peer review” (available to HQ developers only) will reset the issue status to “Reopened”. On this screen peer reviewer should remove assignee, peer reviewer and “patch” label from the issue. This way issue will become available again for anybody who want to work on it. All communication will remain in comments and issue history.

If the issue has passed peer review but the integrator or tester has raised some questions about it, then normally the developer who created the patch would be expected to respond. If they do no respond quickly enough, then the peer reviewer is expected to step in and take responsibility for the change they reviewed.

Once the issue is ready for integration, you can submit it to integration on behalf of the developer. Most external developers (those who are not in the jira-developers group) do not have permission to submit their own issues to integration so cannot do it themselves.

==Replies templates==


Thanks for providing a patch. 
I have reviewed your code and can confirm that it addresses the reported issue. We would like to include it in core. Moodle values its contributors and tries to give them credit when possible. If you are interested in your name appearing on the https://moodle.org/dev/contributions.php page you can create a git commit that we will then pull into Moodle. You can learn more about Git and how Moodle uses it at <nowiki>[Git for developers|https://docs.moodle.org/dev/Git_for_developers]</nowiki> page. Please let me know if you want to prepare a git branch. Or if you don’t have time to go through the whole process at the moment I can pick your patch myself.



Thanks for providing a patch. 
Your code looks almost ready for integration into Moodle. There are just some little things that need to be changed to comply with Moodle standards. Can you please take a look at the review results below and tell me if you are able to modify your branch to address them.



I have reviewed your patch, it addresses the problem and complies with Moodle standards. I'm pushing this issue for integration. Following Moodle <nowiki>[Process|https://docs.moodle.org/dev/Process]</nowiki> it will go through integration review and testing before being included in the product. There might be additional questions from an integrator and/or a tester at those stages. It would be appreciated if you read tracker emails and can reply to questions if needed. If everything goes well during the next two stages your issue will be included in the next weekly release and your count on https://moodle.org/dev/contributions.php page will increase. 
Thanks again for your contribution.



Thanks for providing a patch. 
Unfortunately this patch does not fully address the reported issue. ... DETAILS... 
Even though the code does solve the issue in the short-term it is very likely to create regressions ..... 
I have spent some time reviewing the patch and I would recommend that you ..... 
Please let me know If you are willing to continue working on this issue and complete the solution.


=Checklist=

These are points to consider while peer-reviewing issues. Further explanation below.

[] Syntax
[] Output
[] Language
[] Databases
[] Testing (instructions and automated tests)
[] Security
[] Performance and Clustering
[] Documentation
[] Git
[] Third party code
[] Sanity check
[] Icons

Acceptable check-marks are Y (for yes), N (for no) or - (for not applicable). All N check-marks should be accompanied by an explanation of the problem that still needs to be addressed.

==Syntax==
To allow the community of Moodle developers to work together, conventions should be followed.

* The code is easy to understand and, where it isn't, comments have been provided.
* Variables are named correctly (all lower case, no camel-case, no underscores).
* Functions are named correctly (all lower case, no camel-case, underscores allowed).
* PHP DocBlocks have been updated and adhere to [[Coding_style#Documentation_and_comments|coding style guide]].
* Where functions are being removed, the [[Deprecation]] process is followed.
* The code doesn't use [[Deprecated_functions_in_2.0|deprecated functions]].
* $_GET, $_POST, $_REQUEST, $_COOKIE, and $_SESSION are never used.

See the [[Coding style]] guide for details.

==Output==
Output needs to be controlled by renderers to achieve consistency and correct application of themes.

Ensure that:
* output renders are used to generate output strings, including HTML tags;
* HTML output is valid XHTML;
* no inline styles have been used in HTML output (everything has to be in CSS);
* CSS has been added to the appropriate CSS files (base, specific area, sometimes canvas); and
* the code doesn't use buffered output unless absolutely necessary.
* all visual output has a RTL alternative included

feedback any notices (E_STRICT, etc) seen into the MDL.

==Language==
To achieve appropriate internationalisation of Moodle, language strings must be managed correctly.

Ensure that:
* new language strings are named correctly (all lower case, no camel-case, underscores are permissible in some cases);
* help strings are named and formatted as described in [[Help strings]];
* language strings are used instead of hard-coded strings for text output;
* language strings have not been removed or renamed, had their meaning changed or had their parameters changed in stable branches (permitted only in master); and
* [https://docs.moodle.org/dev/Commit_cheat_sheet#Include_AMOS_script_in_the_commit_if_needed AMOS commands] have been specified when moving or copying language strings.

==Databases==
DB calls are the greatest performance bottleneck in Moodle.

If there is SQL code you can test quickly then do so.

Ensure that:
* there are minimal DB calls (no excessive use of the DB); and
* the code uses SQL compatible with all the supported DB engines (check all selected fields appear in an 'order by' clause).

==Testing instructions and automated tests==
It is the developer's responsibility to test code before integration. Issues should not be sent for peer review without tests so that the peer reviewer can assess their quality and use them to consider the scope of the issue.

Ensure that:
* there are specific testing instructions that state how, as well as what, to test. Please ensure that the testing instructions are in the correct format: [https://docs.moodle.org/dev/Behat Behat gherkin];
* the assignee has tested according to the instructions and verified that they are passing (This is the responsibility of the assignee, not the peer reviewer)
* new unit tests have been added when there is a change in functionality; and
* '''unit tests pass''' for related areas where changes have been made.
* '''Behat tests pass''' for related areas where changes have been made, especially when it involved UI changes.

==Security==
The user community relies on Moodle being responsibly secure.

Ensure that:
* user login is checked where an identity is needed;
* sesskey values are checked before all write actions where appropriate (some read actions as well);
* capabilities are checked where roles differ; and
* if the issue itself is a [[Security|security]] issue, the [[Process#Security_issues|security process]] is being followed.
** Ensure that the fix is '''not''' available in a public repository (ie. a personal Github account); stand-alone patches should be provided instead.
** The issue will not be integrated until just before the next minor version release.

==Performance and clustering==
It is easy to write code that works sufficiently well when you are working on either small sets of data or with a small number of active users. Picking performance issues can be quite difficult and can required a complex level of understanding of both the section of code being reviewed, but also other parts that interact with it.

Clustering is when the same code is run on different computers and an end user could send each request to a different computer. This can produce a number of concurrency issues if not thought through. One example is; If you complete an opcache_reset(), no other server except the one you ran it on knows that it happened. So data can get out of sync.

Ensure that:
* Any filesystem, database or cache accesses are done in the most efficient way.
* That any code or function that appear expensive are not in critical paths. eg; They don't load on every page.
* The least possible code is running to complete the task, especially looking for hidden loops. They can appear from calling functions.
* Any code that runs is not specific to a single node. (eg opcache_reset()) The ensures clusters will run correctly.
* If the code could affect performance at all, make sure there is a comment noting what was considered.
** What they did to mitigate performance impact, or why they thought it wasn't an issue.
** Why they made certain trade-offs.

==Documentation==
Work does not stop when code is integrated.

Ensure that:
* Appropriate [[Tracker_issue_labels|labels]] have been added when there has been a function change, particularly
** docs_required (any functional change, usually paired with ui_change),
** dev_docs_required (any change to APIs, usually paired with api_change),
** ui_change (any functional change, usually paired with docs_required, except ui_change remains permanetly),
** api_change (any change to APIs that devs will need to know about, usually paired with dev_docs_required, except api_change remains permanetly),
** unit_test_required and acceptance_test_required, when there are api or ui changes needing improved coverage, and
** qa_test_required (significant functional change, not covered by unit/acceptance ones).
* Also, verify that the components for the issue are correctly set, so maintainers (subscribed by default) will be mailed about issues early in the process.

==Git==
Ensure that:
* the commit matches the [[Coding style#Git_commits|Coding style]]
* the Git history is clean and the work has been rebased to logical commits; and
* the original author of the work provided as a patch has been given credit within the commit (as author of in the commit message if changes were made).

==Third party code==
Does the change contain third party code? If so, ensure that:

* The code is licensed under a [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| GPL compatible license].
* The instructions for upgrading/importing the library and contained within a readme_moodle.txt file.
* The library is recorded in a thirdparty.xml file, including licensing information.
* Third party code has been scanned to check for url accessible entry points that could be exploited. These should either be disabled, or if required functionality they should be checked for security weaknesses.
* Does not duplicate the functionality of any existing api or third party library in core.
* Any modifications to third party code are recorded in readme_moodle.txt

==Sanity check==
Ensure that:
* the code seems to solve the described problem completely within its reported scope (and further issues have been created to resolve remaining parts or further refactoring);
* the code makes sense in relation to the broader codebase (look at the whole function, not just the altered code); and
* the developer has searched for and fixed other areas that may also have been affected by the same problem.
* verify that the related component maintainers, if known, have participated and are aware of the issue (as assignee, or existing comments...). If they have not, please perform a friendly <tt>@mention</tt> to make them aware about the issue.
* if any version numbers have been changed in [[version.php]] files, then the changes follow [[Moodle_versions#How_to_increment_version_numbers_in_core|the rule for updating version numbers in core]].
* there are comments on tracker explaining why current approach was taken and why other options (especially large issues). If not comment asking them to explain

==Icons==
Are new icons being introduced? If so, ensure that:
* the icons abide by our [https://docs.moodle.org/dev/Moodle_icons icon guidelines] with regards to size, design and format
* the icons are do not unnecessarily add new ways of expressing existing concepts
* the icons are in a pix folder that makes sense

==See Also==
* [http://moodle.org/plugins/view.php?plugin=local_codechecker Code checker plugin]

[[Category: Processes]]

Peer reviewing

2017-12-18T08:55:05Z

Damyon: /* Component Leads */

=Process=

Peer review process helps to prepare the issue for integration. The peer reviewer is another developer who was not involved in the development process on the issue and therefore can take a fresh look and notice something that original developer might have forgotten during development. It is important to check that the bug actually is present and the code fixes it without creating new regressions.

==Completing Peer review as a community member==

Any other developer can review any change. That is why it is called 'peer' review. However, not everyone has the necessary permissions in the tracker to click the buttons 'Start peer review', 'Finish peer review' etc. This should not discourage you from looking at other contributors code and providing comments and feedback. The issue will still need to wait for someone with the right permissions to come along and click the buttons, but they can read your review and then need do no more than double-check some points, which will save a lot of time.

To provide feedback to the developer, leave the issue in "Waiting for Peer Review" (since you don't have permission to do anything else, and also that makes it easy for someone with sufficient permissions to find the issue and move it forwards). Review the code using the checklist below, including any appropriate comments. Once finished, please post a comment clearly stating the outcome of your review. If you think it needs more work then indicate what needs to be changes. If you are happy with the patch, leave a clear comment that you believe this is ready to be made part of Moodle. This can then easily be seen by a HQ developer or component lead and they can quickly take appropriate action.

If a followup review happens to identify something you did not find, you have an opportunity to expand your knowledge and provide better reviews in the future as well as having saved everybody else some time.

Feedback to indicate the issue is ready to progress might look like the following;

Thanks again for your contribution. I have reviewed the patch:
 
[Copy and paste the checklist here, and complete it]
 
I don't have permission to use the peer review buttons on this issue. I hope that someone with sufficient permissions will move the issue forwards soon.


Feedback to indicate the issue requires further work might look like the following;

Thanks for providing a patch. I think the following points require further work
 
[Copy and paste the checklist here, and complete it]
 
Please indicate If you are willing to continue working on this issue and complete the solution.


==Peer review for development by HQ or a known common contributor==

When code comes from a HQ developer or external developer who has been contributing significantly to Moodle and is well acquainted with Moodle standards, peer review is limited to checking the code according to the Checklist below.

If everything is fine, the peer reviewer submits the issue for integration.

If some additional work is needed or the author specifically asked not to submit for integration yet, the peer reviewer clicks on “Finish peer review” and the issue state returns to “Development in progress”. Usually the name of the peer reviewer stays on the issue and if a second peer review is requested it is expected that the same Peer reviewer picks it up. If the peer reviewer is not able to do the second review, they should remove their name and comment about it. Otherwise the issue does not appear on “waiting for peer review” dashboard. Please remember that not all jira users have permission to submit for integration.

==Peer review for external developers==

When the code has come from an external developer, the peer reviewer will also help the developer to lead the issue to integration. In this case the peer reviewer should not use “Finish peer review” button.

If the issue needs additional work, the peer reviewer comments about the suggested changes but does not change the status of the issue and it remains as “Peer review in progress”. If the author of the patch does not reply in 4 days, the peer reviewer may select either to complete the patch themselves or reopen the issue. The decision should be based on the amount of work required to complete the solution, for example, changing coding style or commit message, rebasing, backporting, adding testing instructions, etc. should be performed by the peer reviewer. This may require picking the commits into reviewer’s git branch.

It is very important to give the credit to the author of the code by either keeping their authorship on the commit or adding “Thanks to XXXX for providing the patch” to the commit message. If the author of the patch is not in jira-developers group the special user 'moodle.com' should be entered in Assignee field.

There could be situations when the patch is incomplete, does not fix the original issue, creates regressions or otherwise is not correct. As stated above, the peer reviewer should comment about it and wait for the feedback from the author. If there is no feedback, or the author can not work on this issue any more, and the peer reviewer also does not find it easy and important enough to complete, the issue needs to be reopened. Button “Fail peer review” (available to HQ developers only) will reset the issue status to “Reopened”. On this screen peer reviewer should remove assignee, peer reviewer and “patch” label from the issue. This way issue will become available again for anybody who want to work on it. All communication will remain in comments and issue history.

If the issue has passed peer review but the integrator or tester has raised some questions about it, then normally the developer who created the patch would be expected to respond. If they do no respond quickly enough, then the peer reviewer is expected to step in and take responsibility for the change they reviewed.

Once the issue is ready for integration, you can submit it to integration on behalf of the developer. Most external developers (those who are not in the jira-developers group) do not have permission to submit their own issues to integration so cannot do it themselves.

==Replies templates==


Thanks for providing a patch. 
I have reviewed your code and can confirm that it addresses the reported issue. We would like to include it in core. Moodle values its contributors and tries to give them credit when possible. If you are interested in your name appearing on the https://moodle.org/dev/contributions.php page you can create a git commit that we will then pull into Moodle. You can learn more about Git and how Moodle uses it at <nowiki>[Git for developers|https://docs.moodle.org/dev/Git_for_developers]</nowiki> page. Please let me know if you want to prepare a git branch. Or if you don’t have time to go through the whole process at the moment I can pick your patch myself.



Thanks for providing a patch. 
Your code looks almost ready for integration into Moodle. There are just some little things that need to be changed to comply with Moodle standards. Can you please take a look at the review results below and tell me if you are able to modify your branch to address them.



I have reviewed your patch, it addresses the problem and complies with Moodle standards. I'm pushing this issue for integration. Following Moodle <nowiki>[Process|https://docs.moodle.org/dev/Process]</nowiki> it will go through integration review and testing before being included in the product. There might be additional questions from an integrator and/or a tester at those stages. It would be appreciated if you read tracker emails and can reply to questions if needed. If everything goes well during the next two stages your issue will be included in the next weekly release and your count on https://moodle.org/dev/contributions.php page will increase. 
Thanks again for your contribution.



Thanks for providing a patch. 
Unfortunately this patch does not fully address the reported issue. ... DETAILS... 
Even though the code does solve the issue in the short-term it is very likely to create regressions ..... 
I have spent some time reviewing the patch and I would recommend that you ..... 
Please let me know If you are willing to continue working on this issue and complete the solution.


=Checklist=

These are points to consider while peer-reviewing issues. Further explanation below.

[] Syntax
[] Output
[] Language
[] Databases
[] Testing (instructions and automated tests)
[] Security
[] Performance and Clustering
[] Documentation
[] Git
[] Third party code
[] Component Leads
[] Sanity check
[] Icons

Acceptable check-marks are Y (for yes), N (for no) or - (for not applicable). All N check-marks should be accompanied by an explanation of the problem that still needs to be addressed.

==Syntax==
To allow the community of Moodle developers to work together, conventions should be followed.

* The code is easy to understand and, where it isn't, comments have been provided.
* Variables are named correctly (all lower case, no camel-case, no underscores).
* Functions are named correctly (all lower case, no camel-case, underscores allowed).
* PHP DocBlocks have been updated and adhere to [[Coding_style#Documentation_and_comments|coding style guide]].
* Where functions are being removed, the [[Deprecation]] process is followed.
* The code doesn't use [[Deprecated_functions_in_2.0|deprecated functions]].
* $_GET, $_POST, $_REQUEST, $_COOKIE, and $_SESSION are never used.

See the [[Coding style]] guide for details.

==Output==
Output needs to be controlled by renderers to achieve consistency and correct application of themes.

Ensure that:
* output renders are used to generate output strings, including HTML tags;
* HTML output is valid XHTML;
* no inline styles have been used in HTML output (everything has to be in CSS);
* CSS has been added to the appropriate CSS files (base, specific area, sometimes canvas); and
* the code doesn't use buffered output unless absolutely necessary.
* all visual output has a RTL alternative included

feedback any notices (E_STRICT, etc) seen into the MDL.

==Language==
To achieve appropriate internationalisation of Moodle, language strings must be managed correctly.

Ensure that:
* new language strings are named correctly (all lower case, no camel-case, underscores are permissible in some cases);
* help strings are named and formatted as described in [[Help strings]];
* language strings are used instead of hard-coded strings for text output;
* language strings have not been removed or renamed, had their meaning changed or had their parameters changed in stable branches (permitted only in master); and
* [https://docs.moodle.org/dev/Commit_cheat_sheet#Include_AMOS_script_in_the_commit_if_needed AMOS commands] have been specified when moving or copying language strings.

==Databases==
DB calls are the greatest performance bottleneck in Moodle.

If there is SQL code you can test quickly then do so.

Ensure that:
* there are minimal DB calls (no excessive use of the DB); and
* the code uses SQL compatible with all the supported DB engines (check all selected fields appear in an 'order by' clause).

==Testing instructions and automated tests==
It is the developer's responsibility to test code before integration. Issues should not be sent for peer review without tests so that the peer reviewer can assess their quality and use them to consider the scope of the issue.

Ensure that:
* there are specific testing instructions that state how, as well as what, to test. Please ensure that the testing instructions are in the correct format: [https://docs.moodle.org/dev/Behat Behat gherkin];
* the assignee has tested according to the instructions and verified that they are passing (This is the responsibility of the assignee, not the peer reviewer)
* new unit tests have been added when there is a change in functionality; and
* '''unit tests pass''' for related areas where changes have been made.
* '''Behat tests pass''' for related areas where changes have been made, especially when it involved UI changes.

==Security==
The user community relies on Moodle being responsibly secure.

Ensure that:
* user login is checked where an identity is needed;
* sesskey values are checked before all write actions where appropriate (some read actions as well);
* capabilities are checked where roles differ; and
* if the issue itself is a [[Security|security]] issue, the [[Process#Security_issues|security process]] is being followed.
** Ensure that the fix is '''not''' available in a public repository (ie. a personal Github account); stand-alone patches should be provided instead.
** The issue will not be integrated until just before the next minor version release.

==Performance and clustering==
It is easy to write code that works sufficiently well when you are working on either small sets of data or with a small number of active users. Picking performance issues can be quite difficult and can required a complex level of understanding of both the section of code being reviewed, but also other parts that interact with it.

Clustering is when the same code is run on different computers and an end user could send each request to a different computer. This can produce a number of concurrency issues if not thought through. One example is; If you complete an opcache_reset(), no other server except the one you ran it on knows that it happened. So data can get out of sync.

Ensure that:
* Any filesystem, database or cache accesses are done in the most efficient way.
* That any code or function that appear expensive are not in critical paths. eg; They don't load on every page.
* The least possible code is running to complete the task, especially looking for hidden loops. They can appear from calling functions.
* Any code that runs is not specific to a single node. (eg opcache_reset()) The ensures clusters will run correctly.
* If the code could affect performance at all, make sure there is a comment noting what was considered.
** What they did to mitigate performance impact, or why they thought it wasn't an issue.
** Why they made certain trade-offs.

==Documentation==
Work does not stop when code is integrated.

Ensure that:
* Appropriate [[Tracker_issue_labels|labels]] have been added when there has been a function change, particularly
** docs_required (any functional change, usually paired with ui_change),
** dev_docs_required (any change to APIs, usually paired with api_change),
** ui_change (any functional change, usually paired with docs_required, except ui_change remains permanetly),
** api_change (any change to APIs that devs will need to know about, usually paired with dev_docs_required, except api_change remains permanetly),
** unit_test_required and acceptance_test_required, when there are api or ui changes needing improved coverage, and
** qa_test_required (significant functional change, not covered by unit/acceptance ones).
* Also, verify that the components for the issue are correctly set, so maintainers (subscribed by default) will be mailed about issues early in the process.

==Git==
Ensure that:
* the commit matches the [[Coding style#Git_commits|Coding style]]
* the Git history is clean and the work has been rebased to logical commits; and
* the original author of the work provided as a patch has been given credit within the commit (as author of in the commit message if changes were made).

==Third party code==
Does the change contain third party code? If so, ensure that:

* The code is licensed under a [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| GPL compatible license].
* The instructions for upgrading/importing the library and contained within a readme_moodle.txt file.
* The library is recorded in a thirdparty.xml file, including licensing information.
* Third party code has been scanned to check for url accessible entry points that could be exploited. These should either be disabled, or if required functionality they should be checked for security weaknesses.
* Does not duplicate the functionality of any existing api or third party library in core.
* Any modifications to third party code are recorded in readme_moodle.txt

==Sanity check==
Ensure that:
* the code seems to solve the described problem completely within its reported scope (and further issues have been created to resolve remaining parts or further refactoring);
* the code makes sense in relation to the broader codebase (look at the whole function, not just the altered code); and
* the developer has searched for and fixed other areas that may also have been affected by the same problem.
* verify that the related component maintainers, if known, have participated and are aware of the issue (as assignee, or existing comments...). If they have not, please perform a friendly <tt>@mention</tt> to make them aware about the issue.
* if any version numbers have been changed in [[version.php]] files, then the changes follow [[Moodle_versions#How_to_increment_version_numbers_in_core|the rule for updating version numbers in core]].
* there are comments on tracker explaining why current approach was taken and why other options (especially large issues). If not comment asking them to explain

==Icons==
Are new icons being introduced? If so, ensure that:
* the icons abide by our [https://docs.moodle.org/dev/Moodle_icons icon guidelines] with regards to size, design and format
* the icons are do not unnecessarily add new ways of expressing existing concepts
* the icons are in a pix folder that makes sense

==See Also==
* [http://moodle.org/plugins/view.php?plugin=local_codechecker Code checker plugin]

[[Category: Processes]]

Peer reviewing

2017-12-18T08:45:18Z

Damyon: /* Checklist */

=Process=

Peer review process helps to prepare the issue for integration. The peer reviewer is another developer who was not involved in the development process on the issue and therefore can take a fresh look and notice something that original developer might have forgotten during development. It is important to check that the bug actually is present and the code fixes it without creating new regressions.

==Completing Peer review as a community member==

Any other developer can review any change. That is why it is called 'peer' review. However, not everyone has the necessary permissions in the tracker to click the buttons 'Start peer review', 'Finish peer review' etc. This should not discourage you from looking at other contributors code and providing comments and feedback. The issue will still need to wait for someone with the right permissions to come along and click the buttons, but they can read your review and then need do no more than double-check some points, which will save a lot of time.

To provide feedback to the developer, leave the issue in "Waiting for Peer Review" (since you don't have permission to do anything else, and also that makes it easy for someone with sufficient permissions to find the issue and move it forwards). Review the code using the checklist below, including any appropriate comments. Once finished, please post a comment clearly stating the outcome of your review. If you think it needs more work then indicate what needs to be changes. If you are happy with the patch, leave a clear comment that you believe this is ready to be made part of Moodle. This can then easily be seen by a HQ developer or component lead and they can quickly take appropriate action.

If a followup review happens to identify something you did not find, you have an opportunity to expand your knowledge and provide better reviews in the future as well as having saved everybody else some time.

Feedback to indicate the issue is ready to progress might look like the following;

Thanks again for your contribution. I have reviewed the patch:
 
[Copy and paste the checklist here, and complete it]
 
I don't have permission to use the peer review buttons on this issue. I hope that someone with sufficient permissions will move the issue forwards soon.


Feedback to indicate the issue requires further work might look like the following;

Thanks for providing a patch. I think the following points require further work
 
[Copy and paste the checklist here, and complete it]
 
Please indicate If you are willing to continue working on this issue and complete the solution.


==Peer review for development by HQ or a known common contributor==

When code comes from a HQ developer or external developer who has been contributing significantly to Moodle and is well acquainted with Moodle standards, peer review is limited to checking the code according to the Checklist below.

If everything is fine, the peer reviewer submits the issue for integration.

If some additional work is needed or the author specifically asked not to submit for integration yet, the peer reviewer clicks on “Finish peer review” and the issue state returns to “Development in progress”. Usually the name of the peer reviewer stays on the issue and if a second peer review is requested it is expected that the same Peer reviewer picks it up. If the peer reviewer is not able to do the second review, they should remove their name and comment about it. Otherwise the issue does not appear on “waiting for peer review” dashboard. Please remember that not all jira users have permission to submit for integration.

==Peer review for external developers==

When the code has come from an external developer, the peer reviewer will also help the developer to lead the issue to integration. In this case the peer reviewer should not use “Finish peer review” button.

If the issue needs additional work, the peer reviewer comments about the suggested changes but does not change the status of the issue and it remains as “Peer review in progress”. If the author of the patch does not reply in 4 days, the peer reviewer may select either to complete the patch themselves or reopen the issue. The decision should be based on the amount of work required to complete the solution, for example, changing coding style or commit message, rebasing, backporting, adding testing instructions, etc. should be performed by the peer reviewer. This may require picking the commits into reviewer’s git branch.

It is very important to give the credit to the author of the code by either keeping their authorship on the commit or adding “Thanks to XXXX for providing the patch” to the commit message. If the author of the patch is not in jira-developers group the special user 'moodle.com' should be entered in Assignee field.

There could be situations when the patch is incomplete, does not fix the original issue, creates regressions or otherwise is not correct. As stated above, the peer reviewer should comment about it and wait for the feedback from the author. If there is no feedback, or the author can not work on this issue any more, and the peer reviewer also does not find it easy and important enough to complete, the issue needs to be reopened. Button “Fail peer review” (available to HQ developers only) will reset the issue status to “Reopened”. On this screen peer reviewer should remove assignee, peer reviewer and “patch” label from the issue. This way issue will become available again for anybody who want to work on it. All communication will remain in comments and issue history.

If the issue has passed peer review but the integrator or tester has raised some questions about it, then normally the developer who created the patch would be expected to respond. If they do no respond quickly enough, then the peer reviewer is expected to step in and take responsibility for the change they reviewed.

Once the issue is ready for integration, you can submit it to integration on behalf of the developer. Most external developers (those who are not in the jira-developers group) do not have permission to submit their own issues to integration so cannot do it themselves.

==Replies templates==


Thanks for providing a patch. 
I have reviewed your code and can confirm that it addresses the reported issue. We would like to include it in core. Moodle values its contributors and tries to give them credit when possible. If you are interested in your name appearing on the https://moodle.org/dev/contributions.php page you can create a git commit that we will then pull into Moodle. You can learn more about Git and how Moodle uses it at <nowiki>[Git for developers|https://docs.moodle.org/dev/Git_for_developers]</nowiki> page. Please let me know if you want to prepare a git branch. Or if you don’t have time to go through the whole process at the moment I can pick your patch myself.



Thanks for providing a patch. 
Your code looks almost ready for integration into Moodle. There are just some little things that need to be changed to comply with Moodle standards. Can you please take a look at the review results below and tell me if you are able to modify your branch to address them.



I have reviewed your patch, it addresses the problem and complies with Moodle standards. I'm pushing this issue for integration. Following Moodle <nowiki>[Process|https://docs.moodle.org/dev/Process]</nowiki> it will go through integration review and testing before being included in the product. There might be additional questions from an integrator and/or a tester at those stages. It would be appreciated if you read tracker emails and can reply to questions if needed. If everything goes well during the next two stages your issue will be included in the next weekly release and your count on https://moodle.org/dev/contributions.php page will increase. 
Thanks again for your contribution.



Thanks for providing a patch. 
Unfortunately this patch does not fully address the reported issue. ... DETAILS... 
Even though the code does solve the issue in the short-term it is very likely to create regressions ..... 
I have spent some time reviewing the patch and I would recommend that you ..... 
Please let me know If you are willing to continue working on this issue and complete the solution.


=Checklist=

These are points to consider while peer-reviewing issues. Further explanation below.

[] Syntax
[] Output
[] Language
[] Databases
[] Testing (instructions and automated tests)
[] Security
[] Performance and Clustering
[] Documentation
[] Git
[] Third party code
[] Component Leads
[] Sanity check
[] Icons

Acceptable check-marks are Y (for yes), N (for no) or - (for not applicable). All N check-marks should be accompanied by an explanation of the problem that still needs to be addressed.

==Syntax==
To allow the community of Moodle developers to work together, conventions should be followed.

* The code is easy to understand and, where it isn't, comments have been provided.
* Variables are named correctly (all lower case, no camel-case, no underscores).
* Functions are named correctly (all lower case, no camel-case, underscores allowed).
* PHP DocBlocks have been updated and adhere to [[Coding_style#Documentation_and_comments|coding style guide]].
* Where functions are being removed, the [[Deprecation]] process is followed.
* The code doesn't use [[Deprecated_functions_in_2.0|deprecated functions]].
* $_GET, $_POST, $_REQUEST, $_COOKIE, and $_SESSION are never used.

See the [[Coding style]] guide for details.

==Output==
Output needs to be controlled by renderers to achieve consistency and correct application of themes.

Ensure that:
* output renders are used to generate output strings, including HTML tags;
* HTML output is valid XHTML;
* no inline styles have been used in HTML output (everything has to be in CSS);
* CSS has been added to the appropriate CSS files (base, specific area, sometimes canvas); and
* the code doesn't use buffered output unless absolutely necessary.
* all visual output has a RTL alternative included

feedback any notices (E_STRICT, etc) seen into the MDL.

==Language==
To achieve appropriate internationalisation of Moodle, language strings must be managed correctly.

Ensure that:
* new language strings are named correctly (all lower case, no camel-case, underscores are permissible in some cases);
* help strings are named and formatted as described in [[Help strings]];
* language strings are used instead of hard-coded strings for text output;
* language strings have not been removed or renamed, had their meaning changed or had their parameters changed in stable branches (permitted only in master); and
* [https://docs.moodle.org/dev/Commit_cheat_sheet#Include_AMOS_script_in_the_commit_if_needed AMOS commands] have been specified when moving or copying language strings.

==Databases==
DB calls are the greatest performance bottleneck in Moodle.

If there is SQL code you can test quickly then do so.

Ensure that:
* there are minimal DB calls (no excessive use of the DB); and
* the code uses SQL compatible with all the supported DB engines (check all selected fields appear in an 'order by' clause).

==Testing instructions and automated tests==
It is the developer's responsibility to test code before integration. Issues should not be sent for peer review without tests so that the peer reviewer can assess their quality and use them to consider the scope of the issue.

Ensure that:
* there are specific testing instructions that state how, as well as what, to test. Please ensure that the testing instructions are in the correct format: [https://docs.moodle.org/dev/Behat Behat gherkin];
* the assignee has tested according to the instructions and verified that they are passing (This is the responsibility of the assignee, not the peer reviewer)
* new unit tests have been added when there is a change in functionality; and
* '''unit tests pass''' for related areas where changes have been made.
* '''Behat tests pass''' for related areas where changes have been made, especially when it involved UI changes.

==Security==
The user community relies on Moodle being responsibly secure.

Ensure that:
* user login is checked where an identity is needed;
* sesskey values are checked before all write actions where appropriate (some read actions as well);
* capabilities are checked where roles differ; and
* if the issue itself is a [[Security|security]] issue, the [[Process#Security_issues|security process]] is being followed.
** Ensure that the fix is '''not''' available in a public repository (ie. a personal Github account); stand-alone patches should be provided instead.
** The issue will not be integrated until just before the next minor version release.

==Performance and clustering==
It is easy to write code that works sufficiently well when you are working on either small sets of data or with a small number of active users. Picking performance issues can be quite difficult and can required a complex level of understanding of both the section of code being reviewed, but also other parts that interact with it.

Clustering is when the same code is run on different computers and an end user could send each request to a different computer. This can produce a number of concurrency issues if not thought through. One example is; If you complete an opcache_reset(), no other server except the one you ran it on knows that it happened. So data can get out of sync.

Ensure that:
* Any filesystem, database or cache accesses are done in the most efficient way.
* That any code or function that appear expensive are not in critical paths. eg; They don't load on every page.
* The least possible code is running to complete the task, especially looking for hidden loops. They can appear from calling functions.
* Any code that runs is not specific to a single node. (eg opcache_reset()) The ensures clusters will run correctly.
* If the code could affect performance at all, make sure there is a comment noting what was considered.
** What they did to mitigate performance impact, or why they thought it wasn't an issue.
** Why they made certain trade-offs.

==Documentation==
Work does not stop when code is integrated.

Ensure that:
* Appropriate [[Tracker_issue_labels|labels]] have been added when there has been a function change, particularly
** docs_required (any functional change, usually paired with ui_change),
** dev_docs_required (any change to APIs, usually paired with api_change),
** ui_change (any functional change, usually paired with docs_required, except ui_change remains permanetly),
** api_change (any change to APIs that devs will need to know about, usually paired with dev_docs_required, except api_change remains permanetly),
** unit_test_required and acceptance_test_required, when there are api or ui changes needing improved coverage, and
** qa_test_required (significant functional change, not covered by unit/acceptance ones).
* Also, verify that the components for the issue are correctly set, so maintainers (subscribed by default) will be mailed about issues early in the process.

==Git==
Ensure that:
* the commit matches the [[Coding style#Git_commits|Coding style]]
* the Git history is clean and the work has been rebased to logical commits; and
* the original author of the work provided as a patch has been given credit within the commit (as author of in the commit message if changes were made).

==Third party code==
Does the change contain third party code? If so, ensure that:

* The code is licensed under a [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| GPL compatible license].
* The instructions for upgrading/importing the library and contained within a readme_moodle.txt file.
* The library is recorded in a thirdparty.xml file, including licensing information.
* Third party code has been scanned to check for url accessible entry points that could be exploited. These should either be disabled, or if required functionality they should be checked for security weaknesses.
* Does not duplicate the functionality of any existing api or third party library in core.
* Any modifications to third party code are recorded in readme_moodle.txt

==Component Leads==
If no component leads have not been involved in the issue, at least one of the component leads should be asked for a +1 on the issue to ensure they are aware of the issues being worked on in their components. The list of component leads is available here:
https://docs.moodle.org/dev/Component_Leads

==Sanity check==
Ensure that:
* the code seems to solve the described problem completely within its reported scope (and further issues have been created to resolve remaining parts or further refactoring);
* the code makes sense in relation to the broader codebase (look at the whole function, not just the altered code); and
* the developer has searched for and fixed other areas that may also have been affected by the same problem.
* verify that the related component maintainers, if known, have participated and are aware of the issue (as assignee, or existing comments...). If they have not, please perform a friendly <tt>@mention</tt> to make them aware about the issue.
* if any version numbers have been changed in [[version.php]] files, then the changes follow [[Moodle_versions#How_to_increment_version_numbers_in_core|the rule for updating version numbers in core]].
* there are comments on tracker explaining why current approach was taken and why other options (especially large issues). If not comment asking them to explain

==Icons==
Are new icons being introduced? If so, ensure that:
* the icons abide by our [https://docs.moodle.org/dev/Moodle_icons icon guidelines] with regards to size, design and format
* the icons are do not unnecessarily add new ways of expressing existing concepts
* the icons are in a pix folder that makes sense

==See Also==
* [http://moodle.org/plugins/view.php?plugin=local_codechecker Code checker plugin]

[[Category: Processes]]

HQ component teams

2017-12-18T08:44:31Z

Damyon: Created page with "As of Dec 2017, at Moodle HQ each core developer is assigned a list of components to lead. They are responsible for triaging the issues in those components, planning the roadm..."

As of Dec 2017, at Moodle HQ each core developer is assigned a list of components to lead. They are responsible for triaging the issues in those components, planning the roadmap of issues to be worked on and should be consulted as part of the peer review process for all issues relating to their components.

The current list of component leads is:

'''Adrian (abgreeve), Mihail (Geshoski)'''

Blocks, Blog, Book, Filepicker, Glossary, Lesson, Ratings, Reports, Repositories, Resource

'''Andrew (dobedobedoh), Ryan (ryanwyllie)'''

Email, Forum, HTML Editor (Atto), HTML Editor (TinyMCE), Installation, JavaScript, Logging, RSS, Unit tests, User Tours

'''Damyon (damyon), Zig (zig)'''

Assignment, Assignment (2.2), Competencies, Database activity module, Backup, Backup: IMS-CC

'''David (dmonllao), Ankit (ankit_frenz)'''

Analytics, Caching, Global search, Gradebook, Grading methods, Libraries, Performance, Tasks

'''David (mudrd8mz), Sara (saraarjona)'''

Badges, Cohorts, Dashboard (My home), Enrolments, Language, Maths filters, MNet, Plagiarism, Roles / Access, SCORM, Translation, User management, Workshop

'''Jake (jaked), Jun (jpataleta )'''

Automated functional tests (behat), Choice, Comments, Conditional activities, Database SQL/XMLDB, Events API, Files API, Filters, Forms Library, Portfolio, Web Services

'''Marina (marina)'''

Feedback, Hub, Survey, Tags, Wiki (2.x)

'''Mark (markn)'''

Activity completion, Authentication, Chat, Course completion, External Tool (IMS-LTI), IMS-CP resource type, LTI provider, Media, Messages

'''Simey (lameze), Shamim (rezaie9)'''

Calendar, Groups, Questions, Quiz

Peer reviewing

2017-12-18T08:19:01Z

Damyon: /* Testing instructions and automated tests */

=Process=

Peer review process helps to prepare the issue for integration. The peer reviewer is another developer who was not involved in the development process on the issue and therefore can take a fresh look and notice something that original developer might have forgotten during development. It is important to check that the bug actually is present and the code fixes it without creating new regressions.

==Completing Peer review as a community member==

Any other developer can review any change. That is why it is called 'peer' review. However, not everyone has the necessary permissions in the tracker to click the buttons 'Start peer review', 'Finish peer review' etc. This should not discourage you from looking at other contributors code and providing comments and feedback. The issue will still need to wait for someone with the right permissions to come along and click the buttons, but they can read your review and then need do no more than double-check some points, which will save a lot of time.

To provide feedback to the developer, leave the issue in "Waiting for Peer Review" (since you don't have permission to do anything else, and also that makes it easy for someone with sufficient permissions to find the issue and move it forwards). Review the code using the checklist below, including any appropriate comments. Once finished, please post a comment clearly stating the outcome of your review. If you think it needs more work then indicate what needs to be changes. If you are happy with the patch, leave a clear comment that you believe this is ready to be made part of Moodle. This can then easily be seen by a HQ developer or component lead and they can quickly take appropriate action.

If a followup review happens to identify something you did not find, you have an opportunity to expand your knowledge and provide better reviews in the future as well as having saved everybody else some time.

Feedback to indicate the issue is ready to progress might look like the following;

Thanks again for your contribution. I have reviewed the patch:
 
[Copy and paste the checklist here, and complete it]
 
I don't have permission to use the peer review buttons on this issue. I hope that someone with sufficient permissions will move the issue forwards soon.


Feedback to indicate the issue requires further work might look like the following;

Thanks for providing a patch. I think the following points require further work
 
[Copy and paste the checklist here, and complete it]
 
Please indicate If you are willing to continue working on this issue and complete the solution.


==Peer review for development by HQ or a known common contributor==

When code comes from a HQ developer or external developer who has been contributing significantly to Moodle and is well acquainted with Moodle standards, peer review is limited to checking the code according to the Checklist below.

If everything is fine, the peer reviewer submits the issue for integration.

If some additional work is needed or the author specifically asked not to submit for integration yet, the peer reviewer clicks on “Finish peer review” and the issue state returns to “Development in progress”. Usually the name of the peer reviewer stays on the issue and if a second peer review is requested it is expected that the same Peer reviewer picks it up. If the peer reviewer is not able to do the second review, they should remove their name and comment about it. Otherwise the issue does not appear on “waiting for peer review” dashboard. Please remember that not all jira users have permission to submit for integration.

==Peer review for external developers==

When the code has come from an external developer, the peer reviewer will also help the developer to lead the issue to integration. In this case the peer reviewer should not use “Finish peer review” button.

If the issue needs additional work, the peer reviewer comments about the suggested changes but does not change the status of the issue and it remains as “Peer review in progress”. If the author of the patch does not reply in 4 days, the peer reviewer may select either to complete the patch themselves or reopen the issue. The decision should be based on the amount of work required to complete the solution, for example, changing coding style or commit message, rebasing, backporting, adding testing instructions, etc. should be performed by the peer reviewer. This may require picking the commits into reviewer’s git branch.

It is very important to give the credit to the author of the code by either keeping their authorship on the commit or adding “Thanks to XXXX for providing the patch” to the commit message. If the author of the patch is not in jira-developers group the special user 'moodle.com' should be entered in Assignee field.

There could be situations when the patch is incomplete, does not fix the original issue, creates regressions or otherwise is not correct. As stated above, the peer reviewer should comment about it and wait for the feedback from the author. If there is no feedback, or the author can not work on this issue any more, and the peer reviewer also does not find it easy and important enough to complete, the issue needs to be reopened. Button “Fail peer review” (available to HQ developers only) will reset the issue status to “Reopened”. On this screen peer reviewer should remove assignee, peer reviewer and “patch” label from the issue. This way issue will become available again for anybody who want to work on it. All communication will remain in comments and issue history.

If the issue has passed peer review but the integrator or tester has raised some questions about it, then normally the developer who created the patch would be expected to respond. If they do no respond quickly enough, then the peer reviewer is expected to step in and take responsibility for the change they reviewed.

Once the issue is ready for integration, you can submit it to integration on behalf of the developer. Most external developers (those who are not in the jira-developers group) do not have permission to submit their own issues to integration so cannot do it themselves.

==Replies templates==


Thanks for providing a patch. 
I have reviewed your code and can confirm that it addresses the reported issue. We would like to include it in core. Moodle values its contributors and tries to give them credit when possible. If you are interested in your name appearing on the https://moodle.org/dev/contributions.php page you can create a git commit that we will then pull into Moodle. You can learn more about Git and how Moodle uses it at <nowiki>[Git for developers|https://docs.moodle.org/dev/Git_for_developers]</nowiki> page. Please let me know if you want to prepare a git branch. Or if you don’t have time to go through the whole process at the moment I can pick your patch myself.



Thanks for providing a patch. 
Your code looks almost ready for integration into Moodle. There are just some little things that need to be changed to comply with Moodle standards. Can you please take a look at the review results below and tell me if you are able to modify your branch to address them.



I have reviewed your patch, it addresses the problem and complies with Moodle standards. I'm pushing this issue for integration. Following Moodle <nowiki>[Process|https://docs.moodle.org/dev/Process]</nowiki> it will go through integration review and testing before being included in the product. There might be additional questions from an integrator and/or a tester at those stages. It would be appreciated if you read tracker emails and can reply to questions if needed. If everything goes well during the next two stages your issue will be included in the next weekly release and your count on https://moodle.org/dev/contributions.php page will increase. 
Thanks again for your contribution.



Thanks for providing a patch. 
Unfortunately this patch does not fully address the reported issue. ... DETAILS... 
Even though the code does solve the issue in the short-term it is very likely to create regressions ..... 
I have spent some time reviewing the patch and I would recommend that you ..... 
Please let me know If you are willing to continue working on this issue and complete the solution.


=Checklist=

These are points to consider while peer-reviewing issues. Further explanation below.

[] Syntax
[] Output
[] Language
[] Databases
[] Testing (instructions and automated tests)
[] Security
[] Performance and Clustering
[] Documentation
[] Git
[] Third party code
[] Sanity check
[] Icons

Acceptable check-marks are Y (for yes), N (for no) or - (for not applicable). All N check-marks should be accompanied by an explanation of the problem that still needs to be addressed.

==Syntax==
To allow the community of Moodle developers to work together, conventions should be followed.

* The code is easy to understand and, where it isn't, comments have been provided.
* Variables are named correctly (all lower case, no camel-case, no underscores).
* Functions are named correctly (all lower case, no camel-case, underscores allowed).
* PHP DocBlocks have been updated and adhere to [[Coding_style#Documentation_and_comments|coding style guide]].
* Where functions are being removed, the [[Deprecation]] process is followed.
* The code doesn't use [[Deprecated_functions_in_2.0|deprecated functions]].
* $_GET, $_POST, $_REQUEST, $_COOKIE, and $_SESSION are never used.

See the [[Coding style]] guide for details.

==Output==
Output needs to be controlled by renderers to achieve consistency and correct application of themes.

Ensure that:
* output renders are used to generate output strings, including HTML tags;
* HTML output is valid XHTML;
* no inline styles have been used in HTML output (everything has to be in CSS);
* CSS has been added to the appropriate CSS files (base, specific area, sometimes canvas); and
* the code doesn't use buffered output unless absolutely necessary.
* all visual output has a RTL alternative included

feedback any notices (E_STRICT, etc) seen into the MDL.

==Language==
To achieve appropriate internationalisation of Moodle, language strings must be managed correctly.

Ensure that:
* new language strings are named correctly (all lower case, no camel-case, underscores are permissible in some cases);
* help strings are named and formatted as described in [[Help strings]];
* language strings are used instead of hard-coded strings for text output;
* language strings have not been removed or renamed, had their meaning changed or had their parameters changed in stable branches (permitted only in master); and
* [https://docs.moodle.org/dev/Commit_cheat_sheet#Include_AMOS_script_in_the_commit_if_needed AMOS commands] have been specified when moving or copying language strings.

==Databases==
DB calls are the greatest performance bottleneck in Moodle.

If there is SQL code you can test quickly then do so.

Ensure that:
* there are minimal DB calls (no excessive use of the DB); and
* the code uses SQL compatible with all the supported DB engines (check all selected fields appear in an 'order by' clause).

==Testing instructions and automated tests==
It is the developer's responsibility to test code before integration. Issues should not be sent for peer review without tests so that the peer reviewer can assess their quality and use them to consider the scope of the issue.

Ensure that:
* there are specific testing instructions that state how, as well as what, to test. Please ensure that the testing instructions are in the correct format: [https://docs.moodle.org/dev/Behat Behat gherkin];
* the assignee has tested according to the instructions and verified that they are passing (This is the responsibility of the assignee, not the peer reviewer)
* new unit tests have been added when there is a change in functionality; and
* '''unit tests pass''' for related areas where changes have been made.
* '''Behat tests pass''' for related areas where changes have been made, especially when it involved UI changes.

==Security==
The user community relies on Moodle being responsibly secure.

Ensure that:
* user login is checked where an identity is needed;
* sesskey values are checked before all write actions where appropriate (some read actions as well);
* capabilities are checked where roles differ; and
* if the issue itself is a [[Security|security]] issue, the [[Process#Security_issues|security process]] is being followed.
** Ensure that the fix is '''not''' available in a public repository (ie. a personal Github account); stand-alone patches should be provided instead.
** The issue will not be integrated until just before the next minor version release.

==Performance and clustering==
It is easy to write code that works sufficiently well when you are working on either small sets of data or with a small number of active users. Picking performance issues can be quite difficult and can required a complex level of understanding of both the section of code being reviewed, but also other parts that interact with it.

Clustering is when the same code is run on different computers and an end user could send each request to a different computer. This can produce a number of concurrency issues if not thought through. One example is; If you complete an opcache_reset(), no other server except the one you ran it on knows that it happened. So data can get out of sync.

Ensure that:
* Any filesystem, database or cache accesses are done in the most efficient way.
* That any code or function that appear expensive are not in critical paths. eg; They don't load on every page.
* The least possible code is running to complete the task, especially looking for hidden loops. They can appear from calling functions.
* Any code that runs is not specific to a single node. (eg opcache_reset()) The ensures clusters will run correctly.
* If the code could affect performance at all, make sure there is a comment noting what was considered.
** What they did to mitigate performance impact, or why they thought it wasn't an issue.
** Why they made certain trade-offs.

==Documentation==
Work does not stop when code is integrated.

Ensure that:
* Appropriate [[Tracker_issue_labels|labels]] have been added when there has been a function change, particularly
** docs_required (any functional change, usually paired with ui_change),
** dev_docs_required (any change to APIs, usually paired with api_change),
** ui_change (any functional change, usually paired with docs_required, except ui_change remains permanetly),
** api_change (any change to APIs that devs will need to know about, usually paired with dev_docs_required, except api_change remains permanetly),
** unit_test_required and acceptance_test_required, when there are api or ui changes needing improved coverage, and
** qa_test_required (significant functional change, not covered by unit/acceptance ones).
* Also, verify that the components for the issue are correctly set, so maintainers (subscribed by default) will be mailed about issues early in the process.

==Git==
Ensure that:
* the commit matches the [[Coding style#Git_commits|Coding style]]
* the Git history is clean and the work has been rebased to logical commits; and
* the original author of the work provided as a patch has been given credit within the commit (as author of in the commit message if changes were made).

==Third party code==
Does the change contain third party code? If so, ensure that:

* The code is licensed under a [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| GPL compatible license].
* The instructions for upgrading/importing the library and contained within a readme_moodle.txt file.
* The library is recorded in a thirdparty.xml file, including licensing information.
* Third party code has been scanned to check for url accessible entry points that could be exploited. These should either be disabled, or if required functionality they should be checked for security weaknesses.
* Does not duplicate the functionality of any existing api or third party library in core.
* Any modifications to third party code are recorded in readme_moodle.txt

==Sanity check==
Ensure that:
* the code seems to solve the described problem completely within its reported scope (and further issues have been created to resolve remaining parts or further refactoring);
* the code makes sense in relation to the broader codebase (look at the whole function, not just the altered code); and
* the developer has searched for and fixed other areas that may also have been affected by the same problem.
* verify that the related component maintainers, if known, have participated and are aware of the issue (as assignee, or existing comments...). If they have not, please perform a friendly <tt>@mention</tt> to make them aware about the issue.
* if any version numbers have been changed in [[version.php]] files, then the changes follow [[Moodle_versions#How_to_increment_version_numbers_in_core|the rule for updating version numbers in core]].
* there are comments on tracker explaining why current approach was taken and why other options (especially large issues). If not comment asking them to explain

==Icons==
Are new icons being introduced? If so, ensure that:
* the icons abide by our [https://docs.moodle.org/dev/Moodle_icons icon guidelines] with regards to size, design and format
* the icons are do not unnecessarily add new ways of expressing existing concepts
* the icons are in a pix folder that makes sense

==See Also==
* [http://moodle.org/plugins/view.php?plugin=local_codechecker Code checker plugin]

[[Category: Processes]]

Peer reviewing

2017-12-18T08:18:30Z

Damyon: /* Testing instructions and automated tests */

=Process=

Peer review process helps to prepare the issue for integration. The peer reviewer is another developer who was not involved in the development process on the issue and therefore can take a fresh look and notice something that original developer might have forgotten during development. It is important to check that the bug actually is present and the code fixes it without creating new regressions.

==Completing Peer review as a community member==

Any other developer can review any change. That is why it is called 'peer' review. However, not everyone has the necessary permissions in the tracker to click the buttons 'Start peer review', 'Finish peer review' etc. This should not discourage you from looking at other contributors code and providing comments and feedback. The issue will still need to wait for someone with the right permissions to come along and click the buttons, but they can read your review and then need do no more than double-check some points, which will save a lot of time.

To provide feedback to the developer, leave the issue in "Waiting for Peer Review" (since you don't have permission to do anything else, and also that makes it easy for someone with sufficient permissions to find the issue and move it forwards). Review the code using the checklist below, including any appropriate comments. Once finished, please post a comment clearly stating the outcome of your review. If you think it needs more work then indicate what needs to be changes. If you are happy with the patch, leave a clear comment that you believe this is ready to be made part of Moodle. This can then easily be seen by a HQ developer or component lead and they can quickly take appropriate action.

If a followup review happens to identify something you did not find, you have an opportunity to expand your knowledge and provide better reviews in the future as well as having saved everybody else some time.

Feedback to indicate the issue is ready to progress might look like the following;

Thanks again for your contribution. I have reviewed the patch:
 
[Copy and paste the checklist here, and complete it]
 
I don't have permission to use the peer review buttons on this issue. I hope that someone with sufficient permissions will move the issue forwards soon.


Feedback to indicate the issue requires further work might look like the following;

Thanks for providing a patch. I think the following points require further work
 
[Copy and paste the checklist here, and complete it]
 
Please indicate If you are willing to continue working on this issue and complete the solution.


==Peer review for development by HQ or a known common contributor==

When code comes from a HQ developer or external developer who has been contributing significantly to Moodle and is well acquainted with Moodle standards, peer review is limited to checking the code according to the Checklist below.

If everything is fine, the peer reviewer submits the issue for integration.

If some additional work is needed or the author specifically asked not to submit for integration yet, the peer reviewer clicks on “Finish peer review” and the issue state returns to “Development in progress”. Usually the name of the peer reviewer stays on the issue and if a second peer review is requested it is expected that the same Peer reviewer picks it up. If the peer reviewer is not able to do the second review, they should remove their name and comment about it. Otherwise the issue does not appear on “waiting for peer review” dashboard. Please remember that not all jira users have permission to submit for integration.

==Peer review for external developers==

When the code has come from an external developer, the peer reviewer will also help the developer to lead the issue to integration. In this case the peer reviewer should not use “Finish peer review” button.

If the issue needs additional work, the peer reviewer comments about the suggested changes but does not change the status of the issue and it remains as “Peer review in progress”. If the author of the patch does not reply in 4 days, the peer reviewer may select either to complete the patch themselves or reopen the issue. The decision should be based on the amount of work required to complete the solution, for example, changing coding style or commit message, rebasing, backporting, adding testing instructions, etc. should be performed by the peer reviewer. This may require picking the commits into reviewer’s git branch.

It is very important to give the credit to the author of the code by either keeping their authorship on the commit or adding “Thanks to XXXX for providing the patch” to the commit message. If the author of the patch is not in jira-developers group the special user 'moodle.com' should be entered in Assignee field.

There could be situations when the patch is incomplete, does not fix the original issue, creates regressions or otherwise is not correct. As stated above, the peer reviewer should comment about it and wait for the feedback from the author. If there is no feedback, or the author can not work on this issue any more, and the peer reviewer also does not find it easy and important enough to complete, the issue needs to be reopened. Button “Fail peer review” (available to HQ developers only) will reset the issue status to “Reopened”. On this screen peer reviewer should remove assignee, peer reviewer and “patch” label from the issue. This way issue will become available again for anybody who want to work on it. All communication will remain in comments and issue history.

If the issue has passed peer review but the integrator or tester has raised some questions about it, then normally the developer who created the patch would be expected to respond. If they do no respond quickly enough, then the peer reviewer is expected to step in and take responsibility for the change they reviewed.

Once the issue is ready for integration, you can submit it to integration on behalf of the developer. Most external developers (those who are not in the jira-developers group) do not have permission to submit their own issues to integration so cannot do it themselves.

==Replies templates==


Thanks for providing a patch. 
I have reviewed your code and can confirm that it addresses the reported issue. We would like to include it in core. Moodle values its contributors and tries to give them credit when possible. If you are interested in your name appearing on the https://moodle.org/dev/contributions.php page you can create a git commit that we will then pull into Moodle. You can learn more about Git and how Moodle uses it at <nowiki>[Git for developers|https://docs.moodle.org/dev/Git_for_developers]</nowiki> page. Please let me know if you want to prepare a git branch. Or if you don’t have time to go through the whole process at the moment I can pick your patch myself.



Thanks for providing a patch. 
Your code looks almost ready for integration into Moodle. There are just some little things that need to be changed to comply with Moodle standards. Can you please take a look at the review results below and tell me if you are able to modify your branch to address them.



I have reviewed your patch, it addresses the problem and complies with Moodle standards. I'm pushing this issue for integration. Following Moodle <nowiki>[Process|https://docs.moodle.org/dev/Process]</nowiki> it will go through integration review and testing before being included in the product. There might be additional questions from an integrator and/or a tester at those stages. It would be appreciated if you read tracker emails and can reply to questions if needed. If everything goes well during the next two stages your issue will be included in the next weekly release and your count on https://moodle.org/dev/contributions.php page will increase. 
Thanks again for your contribution.



Thanks for providing a patch. 
Unfortunately this patch does not fully address the reported issue. ... DETAILS... 
Even though the code does solve the issue in the short-term it is very likely to create regressions ..... 
I have spent some time reviewing the patch and I would recommend that you ..... 
Please let me know If you are willing to continue working on this issue and complete the solution.


=Checklist=

These are points to consider while peer-reviewing issues. Further explanation below.

[] Syntax
[] Output
[] Language
[] Databases
[] Testing (instructions and automated tests)
[] Security
[] Performance and Clustering
[] Documentation
[] Git
[] Third party code
[] Sanity check
[] Icons

Acceptable check-marks are Y (for yes), N (for no) or - (for not applicable). All N check-marks should be accompanied by an explanation of the problem that still needs to be addressed.

==Syntax==
To allow the community of Moodle developers to work together, conventions should be followed.

* The code is easy to understand and, where it isn't, comments have been provided.
* Variables are named correctly (all lower case, no camel-case, no underscores).
* Functions are named correctly (all lower case, no camel-case, underscores allowed).
* PHP DocBlocks have been updated and adhere to [[Coding_style#Documentation_and_comments|coding style guide]].
* Where functions are being removed, the [[Deprecation]] process is followed.
* The code doesn't use [[Deprecated_functions_in_2.0|deprecated functions]].
* $_GET, $_POST, $_REQUEST, $_COOKIE, and $_SESSION are never used.

See the [[Coding style]] guide for details.

==Output==
Output needs to be controlled by renderers to achieve consistency and correct application of themes.

Ensure that:
* output renders are used to generate output strings, including HTML tags;
* HTML output is valid XHTML;
* no inline styles have been used in HTML output (everything has to be in CSS);
* CSS has been added to the appropriate CSS files (base, specific area, sometimes canvas); and
* the code doesn't use buffered output unless absolutely necessary.
* all visual output has a RTL alternative included

feedback any notices (E_STRICT, etc) seen into the MDL.

==Language==
To achieve appropriate internationalisation of Moodle, language strings must be managed correctly.

Ensure that:
* new language strings are named correctly (all lower case, no camel-case, underscores are permissible in some cases);
* help strings are named and formatted as described in [[Help strings]];
* language strings are used instead of hard-coded strings for text output;
* language strings have not been removed or renamed, had their meaning changed or had their parameters changed in stable branches (permitted only in master); and
* [https://docs.moodle.org/dev/Commit_cheat_sheet#Include_AMOS_script_in_the_commit_if_needed AMOS commands] have been specified when moving or copying language strings.

==Databases==
DB calls are the greatest performance bottleneck in Moodle.

If there is SQL code you can test quickly then do so.

Ensure that:
* there are minimal DB calls (no excessive use of the DB); and
* the code uses SQL compatible with all the supported DB engines (check all selected fields appear in an 'order by' clause).

==Testing instructions and automated tests==
It is the developer's responsibility to test code before integration. Issues should not be sent for peer review without tests so that the peer reviewer can assess their quality and use them to consider the scope of the issue.

Ensure that:
* there are specific testing instructions that state how, as well as what, to test. Please ensure that the testing instructions are in the correct format: [https://docs.moodle.org/dev/Behat Behat gherkin];
* the assignee has tested according to the instructions and verified that they are passing
* new unit tests have been added when there is a change in functionality; and
* '''unit tests pass''' for related areas where changes have been made.
* '''Behat tests pass''' for related areas where changes have been made, especially when it involved UI changes.

==Security==
The user community relies on Moodle being responsibly secure.

Ensure that:
* user login is checked where an identity is needed;
* sesskey values are checked before all write actions where appropriate (some read actions as well);
* capabilities are checked where roles differ; and
* if the issue itself is a [[Security|security]] issue, the [[Process#Security_issues|security process]] is being followed.
** Ensure that the fix is '''not''' available in a public repository (ie. a personal Github account); stand-alone patches should be provided instead.
** The issue will not be integrated until just before the next minor version release.

==Performance and clustering==
It is easy to write code that works sufficiently well when you are working on either small sets of data or with a small number of active users. Picking performance issues can be quite difficult and can required a complex level of understanding of both the section of code being reviewed, but also other parts that interact with it.

Clustering is when the same code is run on different computers and an end user could send each request to a different computer. This can produce a number of concurrency issues if not thought through. One example is; If you complete an opcache_reset(), no other server except the one you ran it on knows that it happened. So data can get out of sync.

Ensure that:
* Any filesystem, database or cache accesses are done in the most efficient way.
* That any code or function that appear expensive are not in critical paths. eg; They don't load on every page.
* The least possible code is running to complete the task, especially looking for hidden loops. They can appear from calling functions.
* Any code that runs is not specific to a single node. (eg opcache_reset()) The ensures clusters will run correctly.
* If the code could affect performance at all, make sure there is a comment noting what was considered.
** What they did to mitigate performance impact, or why they thought it wasn't an issue.
** Why they made certain trade-offs.

==Documentation==
Work does not stop when code is integrated.

Ensure that:
* Appropriate [[Tracker_issue_labels|labels]] have been added when there has been a function change, particularly
** docs_required (any functional change, usually paired with ui_change),
** dev_docs_required (any change to APIs, usually paired with api_change),
** ui_change (any functional change, usually paired with docs_required, except ui_change remains permanetly),
** api_change (any change to APIs that devs will need to know about, usually paired with dev_docs_required, except api_change remains permanetly),
** unit_test_required and acceptance_test_required, when there are api or ui changes needing improved coverage, and
** qa_test_required (significant functional change, not covered by unit/acceptance ones).
* Also, verify that the components for the issue are correctly set, so maintainers (subscribed by default) will be mailed about issues early in the process.

==Git==
Ensure that:
* the commit matches the [[Coding style#Git_commits|Coding style]]
* the Git history is clean and the work has been rebased to logical commits; and
* the original author of the work provided as a patch has been given credit within the commit (as author of in the commit message if changes were made).

==Third party code==
Does the change contain third party code? If so, ensure that:

* The code is licensed under a [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| GPL compatible license].
* The instructions for upgrading/importing the library and contained within a readme_moodle.txt file.
* The library is recorded in a thirdparty.xml file, including licensing information.
* Third party code has been scanned to check for url accessible entry points that could be exploited. These should either be disabled, or if required functionality they should be checked for security weaknesses.
* Does not duplicate the functionality of any existing api or third party library in core.
* Any modifications to third party code are recorded in readme_moodle.txt

==Sanity check==
Ensure that:
* the code seems to solve the described problem completely within its reported scope (and further issues have been created to resolve remaining parts or further refactoring);
* the code makes sense in relation to the broader codebase (look at the whole function, not just the altered code); and
* the developer has searched for and fixed other areas that may also have been affected by the same problem.
* verify that the related component maintainers, if known, have participated and are aware of the issue (as assignee, or existing comments...). If they have not, please perform a friendly <tt>@mention</tt> to make them aware about the issue.
* if any version numbers have been changed in [[version.php]] files, then the changes follow [[Moodle_versions#How_to_increment_version_numbers_in_core|the rule for updating version numbers in core]].
* there are comments on tracker explaining why current approach was taken and why other options (especially large issues). If not comment asking them to explain

==Icons==
Are new icons being introduced? If so, ensure that:
* the icons abide by our [https://docs.moodle.org/dev/Moodle_icons icon guidelines] with regards to size, design and format
* the icons are do not unnecessarily add new ways of expressing existing concepts
* the icons are in a pix folder that makes sense

==See Also==
* [http://moodle.org/plugins/view.php?plugin=local_codechecker Code checker plugin]

[[Category: Processes]]

Integration Review

2017-11-24T02:02:47Z

Damyon: /* On-sync period */

==Purpose==

The purpose of the integration review is to:
* Ensure consistent quality across the codebase
* Ensure that pedagogical aims of Moodle are at the forefront of any change
* Take into consideration the holistic view of moodle, looking at the impact beyond where the original developer was focused
* Provide guidance and feedback to developers, helping them learn and improve
* Consider '''other perspectives''' of other users perhaps not considered by original developers e.g.
** Teachers
** Students
** Administrators
**Third-party developers

==Integration Review Process==

# Run automated pre-checks against the continuous integration server. (In future this can be automated and also moved into a publicly accessible domain.)
# Final code review, much like the peer review, except that this is the final check. To include
## Takes place in-situ (integrated) to examine the impact to other integrated issues
## Checking against the coding guidelines - syntax/whitespace
## Moodleisms - using the built-in API functions where appropriate
## Cross-DB compatibility
## Security
# Check purpose - the patch needs to fix the issue reported.
# Verify target branches are appropriated. They must match 100% the rules defined for [[#Backporting|backporting issues]].
# Ensure backwards compatibility is maintained. As a starting point backwards compatibility must always be maintained. Where backwards compatibility is affected it should be:
## Well discussed with evidence of justification
## Documented and communicated to the community
# Verify that components are correct and check the right people have been involved (e.g. component maintainers)
# For fundamental changes, check that a thread has been started in an appropriate forum, and other Moodlers, given enough time to comment.
# Tests - must be written to guide tester to verify the fix is working.
## Unit test - very much preferred if applicable
## at end of Wednesday, ensure testing is going to complete as expected. else take other actions (speak to test manager)
# Performance - we have to look at maintaining optimum code here, as far as simple patches that can affect performance. (simple optimisations)
# Scalability - if master only - we're looking far future, stable branches may not be lucky to get such improvements.
# git authorship is correct vs committer + credits due are mentioned + email addresses
# Documentation / PHP Doc / readability
# [[Tracker_issue_labels]] which might need adding. Particularly:
## docs_required / dev_docs_required / release_notes: About which type of documentation is required for the issue.
## ui_change / api_change: About the implications of the change.
## unit_test_required / acceptance_test_required / qa_test_required: About the need to cover the issue with some test.
# Fixed Version after integration - is the versions that the issue is patched for. (A rule here: mention master if its the only branched fixed. If not, don't mention master)
# Update the workflow counters
## If an issue is in need of a second review +1 to errors column in integration workflow counters

== Integration Principles ==

Integration (non-technical but philosophical) principles (4-5 words determining if something has to be integrated/backported or no):

# safety: if something does not look safe, stable, it won't land. Be conservative.
# security: all security issues, if not breaking principle (1) will be integrated/backported to all security-supported versions.
# community: Anything not useful for the community (or against it) won't be integrated/backported. We can measure the community as 10%HQ, 10%Partners, 10%Core developers, 20%Admins, 20%Teachers, 30%Students - not exact science, just one approximation, you know). Question yourself how the change will affect those groups and ensure positives are bigger always (only affected groups count). All community issues, if not breaking principles (1) and (2) will be integrated.
# typology: bug fixes will be always integrated/backported to all the supported braches if none of the principles (1), (2) and (3) are violated. Also, partially-unsupported branches can receive some if they are important enough. Improvements and new features go, exclusively, to master only, that's the main reason for short release periods. We *must* not make exceptions to this.
# priority: issues will be "ordered down" by priority down (where priority is a [https://tracker.moodle.org/issues/?filter=14000 mix of various factors], dynamic). And will be integrated in that order. If something has to be delayed, better if it is low priority. Once again, nothing here can break any of the previous principles.
# tests: unit tests and acceptance tests will backported as far as possible without breaking (1) and (2). New features required to implement tests will be backported if the API is 100% backwards compatible.
If all the principles are fulfilled, the answer for "should I integrate this?" is, "yes, please!"
(apart from technical findings, of course, that can lead to the issue being not integrated/reopened at last, these principles are 100% philosophical)

==Schedule==
===In normal periods ===
The integrators adhere to the following schedule:

* Sunday 22:00 UTC: Issues waiting for integration brought into current integration.
* Monday: Integration
* Tuesday: Integration
* Wednesday: [[Testing of integrated issues#The testing process|Testing]]. Integrators duties during this time are to monitor, facilitate and 'problem solve' the testing process.
* Thursday: Testing should be completed by 07:00 UTC, at which time remaining testing failures will be reverted and reopened. The release process follows.
* Friday: Should be kept free from integration. Integration systems are maintained during this time.

=== During continuous integration/Freeze/QA period ===
During the continuous integration period the integration team are continuously focused on producing regular builds of master to facilitate QA and fast fixes to issues identified.

* Throughout:
** Issues are picked on a one by one basis, prioritising [https://docs.moodle.org/dev/QA_testing#Resetting_tests QA blockers] and master regressions (MUST FIX) issues.
** Any non bug fix issues are given the ''integration_held'' label and are explicitly not picked for integration. Still, anybody is able to add a reasoned ''unhold_requested'' label to those issues in order to get them unblocked by the development managers. Note this does not guarantee the issue to land before release, but just gives it a chance to be integrated like any other issue.
** Our goal is to achieve 'releaseability' throughout, so we stop integrating to ensure a release happens

So, basically, once the QA cycle begins (4 weeks before release) and until release, we do organize work as follows:
* Continuous officially begins. Everybody is on integration. Until end of on-sync period.
* Monday: Integration and [[Testing of integrated issues#Differences in test process during continuous integration periods|testing]] happens.
* Tuesday: Integration happens until 12:00 (UTC+8), [[Testing of integrated issues#Differences in test process during continuous integration periods|afterwards we try to achieve 100% 'Test Passed']] and stop integrating any untested changes until a master release is produced.
* Wednesday: [Assuming a master release has been rolled] Integration and testing continues
* Thursday: Integration and testing continues
* Friday: Integration happens until 12:00 (UTC+8), afterwards we try to achieve 100% 'Test Passed' and stop integrating any untested changes until a master release is produced.

Note: along this period we always release as many stable weeklies as master rolls (on-demand, beta, rc) happen (see MDLSITE-3470). Note that those tags are not simply tags but they come with some important implications, aiming to stability, safety and clarity. Integrators will try to remain loyal to them, be warned:

* Once beta is released... new features or improvements "unrelated" with the release will be really harder to be accepted. A +4 from developer managers (normally +3 is enough) will be needed to proceed with the issue. Integrators vote will be, always, -1.
* Once rc are released... new features or improvements "unrelated" with the release are forbidden. No unhold voting, no managers. Simply forbidden.
* Last week before release, only "related" issues will be picked for integration. Everything else (bug fixes included) are kept out (given the "integration_held" label) if unrelated, at very least until after release. No distractions.
Definition: "related": said to be a followup of required to release, planned OR security issue.

=== On-sync period ===
Immediately after a major release and for a short period (right now, 2 weeks, matching 1st HQ sprint duration), the integration team is under the named on-sync period.

At all effects, it's a normal period (see above), and weeklies are produced for supported stable branches and also for master. But with one important rule/goal:

* We must keep the latest stable branch and master 100% on-sync, specifically about versions and upgrade steps.

This simple, but important constraint, is there to facilitate the integration of impeding bugs, needing urgent resolution, and by keeping them the same, we guarantee that any stable or master fix will apply without problems to both branches. Of course, in order to achieve the rule, these must be also observed along the period:

* We continuously perform diffs between the latest stable and master, controlling that we are on-sync. Any non-authorised difference is cleaned (rewritten).
* Both improvements and new features (and, in general, everything leading to divergence) are held until the on-sync period ends.

Last, but not less important, a second goal for this on-sync period is:

* The environmental requirements '''for next major version''' [[Release process#2_weeks_after|must be agreed and resolved so they can land to master]] early in the process, remaining defined and stable over the next, 6 months of, development cycle.

At the beginning of the on-sync period, we "unhold" all bugs that were held during the last week before the release because they were unrelated to the release. At the end of the onsync period we "unhold" all new features that were submitted after the code freeze for the the release.

== Backporting ==

Whilst we'd all like all Moodle users to be using our latest and greatest code, there is a balance to strike between improving our software and maintaining stability (both in terms of regressions, but also training and documentation materials). Large amounts of change on the stable branches make the lives difficult for institutions to manage upgrades between point releases.

==== General policy ====
Our general policy is as follows:

* Bug fixes will be backported to all (and only to) supported stable branches.
** When fixing a bug, please provide a fix for all supported stable branches.
** If a fix doesn't make sense to be backported to every branch, please make it clear in the issue.
* Improvements or new features will only land in master.

==== Process for requesting a non bug-fix backport ====
Improvements or new features can be requested to be backported to the stable branches. We urge developers to consider this request carefully. In recent years, Moodle has moved to a short and predicatable time based release schedule and we use a very effective distributed source control system. Both of these process changes should ensure that a change not being backported to the stable branches is not as problematic as it may have used to be.

Should you feel that a new feature or improvement needs backporting, please follow this process:

# File a new issue.
# Set the issue title using our backport template guide. (i.e. "Fix forum alignment (backport of MDL-99999)") - see [https://docs.moodle.org/dev/Tracker_guide#Tracker_fields Tracker_guide]
# Link the original issue
# You should include clear rationale for the request to backport

The integration team will process backport requests, with the following guidelines:
# The integration team will together consider each request individually considering the needs of the community (influenced by forum posts, moodle partners, nagging developers etc).
# Backports will happen not earlier than 3 weeks and not later than 2 months after the issue has landed in master.
# Rationale will be given for rejection

If the backport request is approved, please follow the usual development process to submit the feature or improvement on earlier branches.

==== Polite note about bug classification ====
Many issues can be appropiately classified as borderline bugfix/improvements. We politely request that developers do not try and 'game the system' by clasifying their improvements as bugs intentionally. If your fix is in a grey area, please state your case for it being a bug fix clearly. The integration team will use their discretion where necessary.

==== Backport fixes to unsupported branches ====
* Given the [[#General policy|general policy]] above, only supported stable branches are candidates normally.
* Also security and dataloss issues are accepted to be fixed into security-only supported branches.
* Apart from the previous, backport to unsupported branches only will happen when the issue is a '''direct regression caused by a bug fix''' introduced by the latest releases. This applies to both security-only and out-of-support branches. A new weekly release will be performed including the fix.

== Fixing issues identified during integration review/ testing ==

When a branch has been merged by an integrator, it is important that you do not modify the existing history of your branch (e.g. by amending or squashing your commits) and instead add new commits on top. If you modify the history of your branch, it makes it extremely difficult for the integrator to merge your changes (and see the differences).

As a general rule, this means that if your issue has entered the 'in integration review' stage of the development process, please only add new commits on top of your existing commits. There are circumstances when your issue will be 'in integration review' but not merged (and thus possible to squash changes) but if in any doubt, please add new commits and ask the integrator to squash your changes for you.

== Commit squashing ==

The Integration team will sometimes recommend squashing commits when things do not look natural (and may offer to do this for you), especially when there are "fix-commits" in the history happening before integration. But [https://moodle.org/local/chatlogs/index.php?conversationid=13987#c489485 our policy] is "if you want your history of commits to look like bad, it's your history". You will not be forced to squash your changes. You should pay close attention to https://docs.moodle.org/dev/Coding_style#Git_commits and intend to "Tell a perfect, cleaned up version of the history. As if the code was written perfectly first time.".

[[Category: Processes]]

Integration Review

2017-11-24T02:00:00Z

Damyon: /* During continuous integration/Freeze/QA period */

==Purpose==

The purpose of the integration review is to:
* Ensure consistent quality across the codebase
* Ensure that pedagogical aims of Moodle are at the forefront of any change
* Take into consideration the holistic view of moodle, looking at the impact beyond where the original developer was focused
* Provide guidance and feedback to developers, helping them learn and improve
* Consider '''other perspectives''' of other users perhaps not considered by original developers e.g.
** Teachers
** Students
** Administrators
**Third-party developers

==Integration Review Process==

# Run automated pre-checks against the continuous integration server. (In future this can be automated and also moved into a publicly accessible domain.)
# Final code review, much like the peer review, except that this is the final check. To include
## Takes place in-situ (integrated) to examine the impact to other integrated issues
## Checking against the coding guidelines - syntax/whitespace
## Moodleisms - using the built-in API functions where appropriate
## Cross-DB compatibility
## Security
# Check purpose - the patch needs to fix the issue reported.
# Verify target branches are appropriated. They must match 100% the rules defined for [[#Backporting|backporting issues]].
# Ensure backwards compatibility is maintained. As a starting point backwards compatibility must always be maintained. Where backwards compatibility is affected it should be:
## Well discussed with evidence of justification
## Documented and communicated to the community
# Verify that components are correct and check the right people have been involved (e.g. component maintainers)
# For fundamental changes, check that a thread has been started in an appropriate forum, and other Moodlers, given enough time to comment.
# Tests - must be written to guide tester to verify the fix is working.
## Unit test - very much preferred if applicable
## at end of Wednesday, ensure testing is going to complete as expected. else take other actions (speak to test manager)
# Performance - we have to look at maintaining optimum code here, as far as simple patches that can affect performance. (simple optimisations)
# Scalability - if master only - we're looking far future, stable branches may not be lucky to get such improvements.
# git authorship is correct vs committer + credits due are mentioned + email addresses
# Documentation / PHP Doc / readability
# [[Tracker_issue_labels]] which might need adding. Particularly:
## docs_required / dev_docs_required / release_notes: About which type of documentation is required for the issue.
## ui_change / api_change: About the implications of the change.
## unit_test_required / acceptance_test_required / qa_test_required: About the need to cover the issue with some test.
# Fixed Version after integration - is the versions that the issue is patched for. (A rule here: mention master if its the only branched fixed. If not, don't mention master)
# Update the workflow counters
## If an issue is in need of a second review +1 to errors column in integration workflow counters

== Integration Principles ==

Integration (non-technical but philosophical) principles (4-5 words determining if something has to be integrated/backported or no):

# safety: if something does not look safe, stable, it won't land. Be conservative.
# security: all security issues, if not breaking principle (1) will be integrated/backported to all security-supported versions.
# community: Anything not useful for the community (or against it) won't be integrated/backported. We can measure the community as 10%HQ, 10%Partners, 10%Core developers, 20%Admins, 20%Teachers, 30%Students - not exact science, just one approximation, you know). Question yourself how the change will affect those groups and ensure positives are bigger always (only affected groups count). All community issues, if not breaking principles (1) and (2) will be integrated.
# typology: bug fixes will be always integrated/backported to all the supported braches if none of the principles (1), (2) and (3) are violated. Also, partially-unsupported branches can receive some if they are important enough. Improvements and new features go, exclusively, to master only, that's the main reason for short release periods. We *must* not make exceptions to this.
# priority: issues will be "ordered down" by priority down (where priority is a [https://tracker.moodle.org/issues/?filter=14000 mix of various factors], dynamic). And will be integrated in that order. If something has to be delayed, better if it is low priority. Once again, nothing here can break any of the previous principles.
# tests: unit tests and acceptance tests will backported as far as possible without breaking (1) and (2). New features required to implement tests will be backported if the API is 100% backwards compatible.
If all the principles are fulfilled, the answer for "should I integrate this?" is, "yes, please!"
(apart from technical findings, of course, that can lead to the issue being not integrated/reopened at last, these principles are 100% philosophical)

==Schedule==
===In normal periods ===
The integrators adhere to the following schedule:

* Sunday 22:00 UTC: Issues waiting for integration brought into current integration.
* Monday: Integration
* Tuesday: Integration
* Wednesday: [[Testing of integrated issues#The testing process|Testing]]. Integrators duties during this time are to monitor, facilitate and 'problem solve' the testing process.
* Thursday: Testing should be completed by 07:00 UTC, at which time remaining testing failures will be reverted and reopened. The release process follows.
* Friday: Should be kept free from integration. Integration systems are maintained during this time.

=== During continuous integration/Freeze/QA period ===
During the continuous integration period the integration team are continuously focused on producing regular builds of master to facilitate QA and fast fixes to issues identified.

* Throughout:
** Issues are picked on a one by one basis, prioritising [https://docs.moodle.org/dev/QA_testing#Resetting_tests QA blockers] and master regressions (MUST FIX) issues.
** Any non bug fix issues are given the ''integration_held'' label and are explicitly not picked for integration. Still, anybody is able to add a reasoned ''unhold_requested'' label to those issues in order to get them unblocked by the development managers. Note this does not guarantee the issue to land before release, but just gives it a chance to be integrated like any other issue.
** Our goal is to achieve 'releaseability' throughout, so we stop integrating to ensure a release happens

So, basically, once the QA cycle begins (4 weeks before release) and until release, we do organize work as follows:
* Continuous officially begins. Everybody is on integration. Until end of on-sync period.
* Monday: Integration and [[Testing of integrated issues#Differences in test process during continuous integration periods|testing]] happens.
* Tuesday: Integration happens until 12:00 (UTC+8), [[Testing of integrated issues#Differences in test process during continuous integration periods|afterwards we try to achieve 100% 'Test Passed']] and stop integrating any untested changes until a master release is produced.
* Wednesday: [Assuming a master release has been rolled] Integration and testing continues
* Thursday: Integration and testing continues
* Friday: Integration happens until 12:00 (UTC+8), afterwards we try to achieve 100% 'Test Passed' and stop integrating any untested changes until a master release is produced.

Note: along this period we always release as many stable weeklies as master rolls (on-demand, beta, rc) happen (see MDLSITE-3470). Note that those tags are not simply tags but they come with some important implications, aiming to stability, safety and clarity. Integrators will try to remain loyal to them, be warned:

* Once beta is released... new features or improvements "unrelated" with the release will be really harder to be accepted. A +4 from developer managers (normally +3 is enough) will be needed to proceed with the issue. Integrators vote will be, always, -1.
* Once rc are released... new features or improvements "unrelated" with the release are forbidden. No unhold voting, no managers. Simply forbidden.
* Last week before release, only "related" issues will be picked for integration. Everything else (bug fixes included) are kept out (given the "integration_held" label) if unrelated, at very least until after release. No distractions.
Definition: "related": said to be a followup of required to release, planned OR security issue.

=== On-sync period ===
Immediately after a major release and for a short period (right now, 2 weeks, matching 1st HQ sprint duration), the integration team is under the named on-sync period.

At all effects, it's a normal period (see above), and weeklies are produced for supported stable branches and also for master. But with one important rule/goal:

* We must keep the latest stable branch and master 100% on-sync, specifically about versions and upgrade steps.

This simple, but important constraint, is there to facilitate the integration of impeding bugs, needing urgent resolution, and by keeping them the same, we guarantee that any stable or master fix will apply without problems to both branches. Of course, in order to achieve the rule, these must be also observed along the period:

* We continuously perform diffs between the latest stable and master, controlling that we are on-sync. Any non-authorised difference is cleaned (rewritten).
* Both improvements and new features (and, in general, everything leading to divergence) are held until the on-sync period ends.

Last, but not less important, a second goal for this on-sync period is:

* The environmental requirements '''for next major version''' [[Release process#2_weeks_after|must be agreed and resolved so they can land to master]] early in the process, remaining defined and stable over the next, 6 months of, development cycle.

== Backporting ==

Whilst we'd all like all Moodle users to be using our latest and greatest code, there is a balance to strike between improving our software and maintaining stability (both in terms of regressions, but also training and documentation materials). Large amounts of change on the stable branches make the lives difficult for institutions to manage upgrades between point releases.

==== General policy ====
Our general policy is as follows:

* Bug fixes will be backported to all (and only to) supported stable branches.
** When fixing a bug, please provide a fix for all supported stable branches.
** If a fix doesn't make sense to be backported to every branch, please make it clear in the issue.
* Improvements or new features will only land in master.

==== Process for requesting a non bug-fix backport ====
Improvements or new features can be requested to be backported to the stable branches. We urge developers to consider this request carefully. In recent years, Moodle has moved to a short and predicatable time based release schedule and we use a very effective distributed source control system. Both of these process changes should ensure that a change not being backported to the stable branches is not as problematic as it may have used to be.

Should you feel that a new feature or improvement needs backporting, please follow this process:

# File a new issue.
# Set the issue title using our backport template guide. (i.e. "Fix forum alignment (backport of MDL-99999)") - see [https://docs.moodle.org/dev/Tracker_guide#Tracker_fields Tracker_guide]
# Link the original issue
# You should include clear rationale for the request to backport

The integration team will process backport requests, with the following guidelines:
# The integration team will together consider each request individually considering the needs of the community (influenced by forum posts, moodle partners, nagging developers etc).
# Backports will happen not earlier than 3 weeks and not later than 2 months after the issue has landed in master.
# Rationale will be given for rejection

If the backport request is approved, please follow the usual development process to submit the feature or improvement on earlier branches.

==== Polite note about bug classification ====
Many issues can be appropiately classified as borderline bugfix/improvements. We politely request that developers do not try and 'game the system' by clasifying their improvements as bugs intentionally. If your fix is in a grey area, please state your case for it being a bug fix clearly. The integration team will use their discretion where necessary.

==== Backport fixes to unsupported branches ====
* Given the [[#General policy|general policy]] above, only supported stable branches are candidates normally.
* Also security and dataloss issues are accepted to be fixed into security-only supported branches.
* Apart from the previous, backport to unsupported branches only will happen when the issue is a '''direct regression caused by a bug fix''' introduced by the latest releases. This applies to both security-only and out-of-support branches. A new weekly release will be performed including the fix.

== Fixing issues identified during integration review/ testing ==

When a branch has been merged by an integrator, it is important that you do not modify the existing history of your branch (e.g. by amending or squashing your commits) and instead add new commits on top. If you modify the history of your branch, it makes it extremely difficult for the integrator to merge your changes (and see the differences).

As a general rule, this means that if your issue has entered the 'in integration review' stage of the development process, please only add new commits on top of your existing commits. There are circumstances when your issue will be 'in integration review' but not merged (and thus possible to squash changes) but if in any doubt, please add new commits and ask the integrator to squash your changes for you.

== Commit squashing ==

The Integration team will sometimes recommend squashing commits when things do not look natural (and may offer to do this for you), especially when there are "fix-commits" in the history happening before integration. But [https://moodle.org/local/chatlogs/index.php?conversationid=13987#c489485 our policy] is "if you want your history of commits to look like bad, it's your history". You will not be forced to squash your changes. You should pay close attention to https://docs.moodle.org/dev/Coding_style#Git_commits and intend to "Tell a perfect, cleaned up version of the history. As if the code was written perfectly first time.".

[[Category: Processes]]

Improved Question Bank Tags

2017-11-20T02:03:51Z

Damyon: /* Architecture */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category (optionally including sub categories) with optional filtering by tags.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually). It also becomes more difficult to prevent a student from seeing the same random question in the same quiz more than once.

Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category (optionally including sub categories) with optional filtering by tags."

Note: The MUA requires the ability to pull random questions from multiple categories. It needs to be confirmed if pulling questions from a parent category including sub categories, combined with filtering by a tag will fullfill this requirement.

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* Type of thing that can be added to a quiz "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

After these changes there will only be 2 possible slot types (single question, or random question). The random question will require new fields in the quiz_slots table storing questioncategoryid, includesubcats, and tagid.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

Currently there is a "fake" question category for each context. It does not exist in the database, but in places in the UI it is shown as a "fake" question category named top. We need to turn this into a real question category in the database, and enforce some validation rules to prevent modifying it, adding questions to it, or adding new questions categories as siblings of it. This allows us to (for example) add questions from any category in this course that have the label "midterm4" (because all categories will be a child of this top question category). We will need to modify import/restore to auto-create this top level category for backups older than $versionnumber (and enforce the other validation rules).

===== Other related code improvements =====

Tim suggests that before making the changes requested here might be the appropriate moment to improve parts of the quiz code, because then implementing the new features would be easier, and could be done using the latest coding practices:
* There are currently two separate classes classes/structure.php and classes/repaginate.php. There is not good reason for this split. Implementing this proposal may require more new classes. These could all be in a new namespace mod_quiz\local\structure namespace and combine, and the two spearate historical classes could be merged.
* The Edit quiz page currently uses old YUI javascript, renderers and a custom ajax script mod/quiz/edit_rest.php. This would be better as AMD, Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>
quiz_slots(id, slot, quizid, page, requireprevious, question, questioncategoryid, subcats, tagid, maxmark)
</code>

(Note: please keep all the columns relating to what question gets slected together. That means that maxmark needs to go after them all, or before them all.)

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Add a random question from a category + tag]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from category + tag added to a quiz]]

===== A problem =====

Note: There is currently a limitation in the question bank. There is no categoryid meaning "all the questions in this context", for example "All the questions in this course". In some places in the UI, that is shown as 'Top' under the context name, but it does not really exist - and the UI options (but fortunately not the database) adopt a horrible convention where the argument is $categoryid,$contextid, but if $categoryid is 0 then it means any category in this context. The kind of problem this causes is that you cannot export all the questions in a course.

This is also a problem for this bit of work. We want to be able to add a random question which is "Any question in this course with tag X".

I think the minimal change to allow this is to create in the database a question_category for "Top level of this Course question bank" for each context which has question. I think we can do that with only minimal changes in the question bank (e.g. we don't need to clean up to nasty $categoryid,$contextid params now. However, we would need to ensure that adding this category did not break things.)

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid, subcats and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar. Although it should not happen we need to allow for the same random question instance being used by 2 quizzes.
* We will then need to delete all "random" questions.
* Create a new question category for every context that has questions. Update the existing question categories in that context with parent = 0 to parent = new "Top" question category id

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

("... the component will be core_course ..." it was not immediately obvious to me that this was 'right'. After some thought I have concluded that is, indeed, the least bad way to represent it. Would it be good to explain this choice?)

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

Is the long list of icons really good UI. Is this the moment to do what has been done elsewhere in Moodle, and go for an "Edit" menu?

Also, editing question tags is done on the Edit quiestion form. Should we consolidate it, so that all question tag editing is done in one place? (Probably in the proposed new page, not in the Edit question form.)

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-20T02:01:59Z

Damyon: /* Architecture */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category (optionally including sub categories) with optional filtering by tags.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually). It also becomes more difficult to prevent a student from seeing the same random question in the same quiz more than once.

Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category (optionally including sub categories) with optional filtering by tags."

Note: The MUA requires the ability to pull random questions from multiple categories. It needs to be confirmed if pulling questions from a parent category including sub categories, combined with filtering by a tag will fullfill this requirement.

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* Type of thing that can be added to a quiz "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

After these changes there will only be 2 possible slot types (single question, or random question). The random question will require new fields in the quiz_slots table storing questioncategoryid, includesubcats, and tagid.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

Currently there is a "fake" question category for each context. It does not exist in the database, but in places in the UI it is shown as a "fake" question category named top. We need to turn this into a real question category in the database, and enforce some validation rules to prevent modifying it, adding questions to it, or adding new questions categories as siblings of it. This allows us to (for example) add questions from any category in this course that have the label "midterm4" (because all categories will be a child of this top question category).

===== Other related code improvements =====

Tim suggests that before making the changes requested here might be the appropriate moment to improve parts of the quiz code, because then implementing the new features would be easier, and could be done using the latest coding practices:
* There are currently two separate classes classes/structure.php and classes/repaginate.php. There is not good reason for this split. Implementing this proposal may require more new classes. These could all be in a new namespace mod_quiz\local\structure namespace and combine, and the two spearate historical classes could be merged.
* The Edit quiz page currently uses old YUI javascript, renderers and a custom ajax script mod/quiz/edit_rest.php. This would be better as AMD, Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>
quiz_slots(id, slot, quizid, page, requireprevious, question, questioncategoryid, subcats, tagid, maxmark)
</code>

(Note: please keep all the columns relating to what question gets slected together. That means that maxmark needs to go after them all, or before them all.)

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Add a random question from a category + tag]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from category + tag added to a quiz]]

===== A problem =====

Note: There is currently a limitation in the question bank. There is no categoryid meaning "all the questions in this context", for example "All the questions in this course". In some places in the UI, that is shown as 'Top' under the context name, but it does not really exist - and the UI options (but fortunately not the database) adopt a horrible convention where the argument is $categoryid,$contextid, but if $categoryid is 0 then it means any category in this context. The kind of problem this causes is that you cannot export all the questions in a course.

This is also a problem for this bit of work. We want to be able to add a random question which is "Any question in this course with tag X".

I think the minimal change to allow this is to create in the database a question_category for "Top level of this Course question bank" for each context which has question. I think we can do that with only minimal changes in the question bank (e.g. we don't need to clean up to nasty $categoryid,$contextid params now. However, we would need to ensure that adding this category did not break things.)

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid, subcats and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar. Although it should not happen we need to allow for the same random question instance being used by 2 quizzes.
* We will then need to delete all "random" questions.
* Create a new question category for every context that has questions. Update the existing question categories in that context with parent = 0 to parent = new "Top" question category id

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

("... the component will be core_course ..." it was not immediately obvious to me that this was 'right'. After some thought I have concluded that is, indeed, the least bad way to represent it. Would it be good to explain this choice?)

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

Is the long list of icons really good UI. Is this the moment to do what has been done elsewhere in Moodle, and go for an "Edit" menu?

Also, editing question tags is done on the Edit quiestion form. Should we consolidate it, so that all question tag editing is done in one place? (Probably in the proposed new page, not in the Edit question form.)

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-20T01:57:54Z

Damyon: /* Upgrade Steps Required */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category (optionally including sub categories) with optional filtering by tags.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually). It also becomes more difficult to prevent a student from seeing the same random question in the same quiz more than once.

Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category (optionally including sub categories) with optional filtering by tags."

Note: The MUA requires the ability to pull random questions from multiple categories. It needs to be confirmed if pulling questions from a parent category including sub categories, combined with filtering by a tag will fullfill this requirement.

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* Type of thing that can be added to a quiz "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

After these changes there will only be 2 possible slot types (single question, or random question). The random question will require new fields in the quiz_slots table storing questioncategoryid, includesubcats, and tagid.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim suggests that before making the changes requested here might be the appropriate moment to improve parts of the quiz code, because then implementing the new features would be easier, and could be done using the latest coding practices:
* There are currently two separate classes classes/structure.php and classes/repaginate.php. There is not good reason for this split. Implementing this proposal may require more new classes. These could all be in a new namespace mod_quiz\local\structure namespace and combine, and the two spearate historical classes could be merged.
* The Edit quiz page currently uses old YUI javascript, renderers and a custom ajax script mod/quiz/edit_rest.php. This would be better as AMD, Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>
quiz_slots(id, slot, quizid, page, requireprevious, question, questioncategoryid, subcats, tagid, maxmark)
</code>

(Note: please keep all the columns relating to what question gets slected together. That means that maxmark needs to go after them all, or before them all.)

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Add a random question from a category + tag]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from category + tag added to a quiz]]

===== A problem =====

Note: There is currently a limitation in the question bank. There is no categoryid meaning "all the questions in this context", for example "All the questions in this course". In some places in the UI, that is shown as 'Top' under the context name, but it does not really exist - and the UI options (but fortunately not the database) adopt a horrible convention where the argument is $categoryid,$contextid, but if $categoryid is 0 then it means any category in this context. The kind of problem this causes is that you cannot export all the questions in a course.

This is also a problem for this bit of work. We want to be able to add a random question which is "Any question in this course with tag X".

I think the minimal change to allow this is to create in the database a question_category for "Top level of this Course question bank" for each context which has question. I think we can do that with only minimal changes in the question bank (e.g. we don't need to clean up to nasty $categoryid,$contextid params now. However, we would need to ensure that adding this category did not break things.)

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid, subcats and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar. Although it should not happen we need to allow for the same random question instance being used by 2 quizzes.
* We will then need to delete all "random" questions.
* Create a new question category for every context that has questions. Update the existing question categories in that context with parent = 0 to parent = new "Top" question category id

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

("... the component will be core_course ..." it was not immediately obvious to me that this was 'right'. After some thought I have concluded that is, indeed, the least bad way to represent it. Would it be good to explain this choice?)

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

Is the long list of icons really good UI. Is this the moment to do what has been done elsewhere in Moodle, and go for an "Edit" menu?

Also, editing question tags is done on the Edit quiestion form. Should we consolidate it, so that all question tag editing is done in one place? (Probably in the proposed new page, not in the Edit question form.)

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T09:18:50Z

Damyon: /* User Stories / Requirements */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category (optionally including sub categories) with optional filtering by tags.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually). It also becomes more difficult to prevent a student from seeing the same random question in the same quiz more than once.

Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category (optionally including sub categories) with optional filtering by tags."

Note: The MUA requires the ability to pull random questions from multiple categories. It needs to be confirmed if pulling questions from a parent category including sub categories, combined with filtering by a tag will fullfill this requirement.

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

After these changes there will only be 2 possible slot types (single question, or random question). The random question will require new fields in the quiz_slots table storing questioncategoryid, includesubcats, and tagid.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, questioncategoryid, subcats, tagid)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Add a random question from a category + tag]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from category + tag added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid, subcats and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar. Although it should not happen we need to allow for the same random question instance being used by 2 quizzes.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

File:QBankTags-DBChanges.png

2017-11-16T09:16:45Z

Damyon: Damyon uploaded a new version of File:QBankTags-DBChanges.png

Improved Question Bank Tags

2017-11-16T09:14:01Z

Damyon: /* Design */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually). It also becomes more difficult to prevent a student from seeing the same random question in the same quiz more than once.

Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category (optionally including sub categories) with optional filtering by tags."

Note: The MUA requires the ability to pull random questions from multiple categories. It needs to be confirmed if pulling questions from a parent category including sub categories, combined with filtering by a tag will fullfill this requirement.

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

After these changes there will only be 2 possible slot types (single question, or random question). The random question will require new fields in the quiz_slots table storing questioncategoryid, includesubcats, and tagid.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, questioncategoryid, subcats, tagid)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Add a random question from a category + tag]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from category + tag added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid, subcats and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar. Although it should not happen we need to allow for the same random question instance being used by 2 quizzes.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T09:00:36Z

Damyon: /* Updates */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually). It also becomes more difficult to prevent a student from seeing the same random question in the same quiz more than once.

Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category (optionally including sub categories) with optional filtering by tags."

Note: The MUA requires the ability to pull random questions from multiple categories. It needs to be confirmed if pulling questions from a parent category including sub categories, combined with filtering by a tag will fullfill this requirement.

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Add a random question from a category + tag]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from category + tag added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar. Although it should not happen we need to allow for the same random question instance being used by 2 quizzes.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

File:RandomQuestionInQuiz.png

2017-11-16T08:57:27Z

Damyon: Damyon uploaded a new version of File:RandomQuestionInQuiz.png

Improved Question Bank Tags

2017-11-16T08:52:57Z

Damyon: /* UI changes */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually). It also becomes more difficult to prevent a student from seeing the same random question in the same quiz more than once.

Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

Note for Tim: We discussed having all the data in the slots table, but that's not really possible because the MUA requires the ability to pull random questions from multiple categories. So it needs to be stored as a list of question categories, and optional tags.

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Add a random question from a category + tag]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from category + tag added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar. Although it should not happen we need to allow for the same random question instance being used by 2 quizzes.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

File:RandomQuestionFromListMenu.png

2017-11-16T08:51:38Z

Damyon: Damyon uploaded a new version of File:RandomQuestionFromListMenu.png

Improved Question Bank Tags

2017-11-16T03:45:37Z

Damyon: /* Updates */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually). It also becomes more difficult to prevent a student from seeing the same random question in the same quiz more than once.

Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

Note for Tim: We discussed having all the data in the slots table, but that's not really possible because the MUA requires the ability to pull random questions from multiple categories. So it needs to be stored as a list of question categories, and optional tags.

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar. Although it should not happen we need to allow for the same random question instance being used by 2 quizzes.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T03:45:05Z

Damyon: /* Upgrade Steps Required */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually). It also becomes more difficult to prevent a student from seeing the same random question in the same quiz more than once.

Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

Note for Tim: We discussed having all the data in the slots table, but that's not really possible because the MUA requires the ability to pull random questions from multiple categories. So it needs to be stored as a list of question categories, and optional tags.

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar. Although it should not happen we need to allow for the same random question instance being used by 2 quizzes.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T03:43:45Z

Damyon: /* Updates */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually). It also becomes more difficult to prevent a student from seeing the same random question in the same quiz more than once.

Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

Note for Tim: We discussed having all the data in the slots table, but that's not really possible because the MUA requires the ability to pull random questions from multiple categories. So it needs to be stored as a list of question categories, and optional tags.

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T03:42:51Z

Damyon: /* Updates */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every question instance using the set. Adding 10 random questions from a set would create 10 individual questions with the list of question ids stored in each (and each would then require updating individually).
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

Note for Tim: We discussed having all the data in the slots table, but that's not really possible because the MUA requires the ability to pull random questions from multiple categories. So it needs to be stored as a list of question categories, and optional tags.

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T03:40:17Z

Damyon: /* UI Changes */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

Note for Tim: We discussed having all the data in the slots table, but that's not really possible because the MUA requires the ability to pull random questions from multiple categories. So it needs to be stored as a list of question categories, and optional tags.

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question bank shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

File:CourseTagsIconForQuestions.png

2017-11-16T03:39:46Z

Damyon: Damyon uploaded a new version of File:CourseTagsIconForQuestions.png

Improved Question Bank Tags

2017-11-16T03:11:46Z

Damyon: /* Search for question by tag */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

Note for Tim: We discussed having all the data in the slots table, but that's not really possible because the MUA requires the ability to pull random questions from multiple categories. So it needs to be stored as a list of question categories, and optional tags.

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
We should be able to search for questions by tag from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T03:06:47Z

Damyon: /* Architecture */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

Note for Tim: We discussed having all the data in the slots table, but that's not really possible because the MUA requires the ability to pull random questions from multiple categories. So it needs to be stored as a list of question categories, and optional tags.

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

===== Other related code improvements =====

Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T03:06:22Z

Damyon: /* Architecture */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

Note for Tim: We discussed having all the data in the slots table, but that's not really possible because the MUA requires the ability to pull random questions from multiple categories. So it needs to be stored as a list of question categories, and optional tags.

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there.
We will introduce a new abstract class "mod_quiz\local\structure\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the \mod_quiz\local\structure\slot_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the \mod_quiz\local\structure\slot_random class is loaded directly from the quiz (also not a sub-plugin).

Other related code improvements: Tim has requested to move the classes from classes/structure.php and classes/repaginate.php to the mod_quiz\local\structure namespace and combine them.

Before modifying the existing quiz editing UI, Tim has requested that we move it from YUI + custom ajax to AMD + Templates and webservices.

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T02:59:49Z

Damyon: /* Updates */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

Note for Tim: We discussed having all the data in the slots table, but that's not really possible because the MUA requires the ability to pull random questions from multiple categories. So it needs to be stored as a list of question categories, and optional tags.

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T02:56:49Z

Damyon: /* DB changes */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_randomslot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

File:QBankTags-DBChanges.png

2017-11-16T02:55:18Z

Damyon: Damyon uploaded a new version of File:QBankTags-DBChanges.png

Improved Question Bank Tags

2017-11-16T02:51:33Z

Damyon: /* DB changes */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

<code>
quiz_random_slot(id, quizslotid, category, tagid *allow null*)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T02:51:16Z

Damyon: /* Random question from a question category + tag */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a new table storing a list of questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Update the quiz_slots table to change questionid to allow null.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

Introduce 1 new table to store a list of questioncategoryid + optional tagid for each random question slot.

quiz_random_slot(id, quizslotid, category, tagid *allow null*)

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T02:46:22Z

Damyon: /* Updates */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag. We also need to meet the use case where we want to use questions from different question categories.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from multiple question categories with optional filtering by tags."

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Make questionid allow null and add 1 new fields to the quiz_slots table.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T02:31:34Z

Damyon: /* Architecture */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category. The list of questions can be further restricted by specifying a tag."

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will make this field optional (allow null). The slot type can be determined by the presence or absence of the questionid field.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Make questionid allow null and add 1 new fields to the quiz_slots table.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T02:29:45Z

Damyon: /* Design */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category. The list of questions can be further restricted by specifying a tag."

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a question category + tag"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will change this table to abstract the logic for determining the question from the slot.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Make questionid allow null and add 1 new fields to the quiz_slots table.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T02:28:56Z

Damyon: /* Updates */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag.

This impacts one of the user requirements for the project:

"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:

"As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category. The list of questions can be further restricted by specifying a tag."

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a set of questions"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will change this table to abstract the logic for determining the question from the slot.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Make questionid allow null and add 1 new fields to the quiz_slots table.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T02:28:34Z

Damyon: /* Updates */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag.

This impacts one of the user requirements for the project:
"As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag."

would have to be modified to:
"As a teacher, I can add a 'random question' to my quiz where the question is taken from a question category. The list of questions can be further restricted by specifying a tag."
----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a set of questions"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will change this table to abstract the logic for determining the question from the slot.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Make questionid allow null and add 1 new fields to the quiz_slots table.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T02:22:20Z

Damyon: /* Update */

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Updates ==
16th Nov 2017

It was discussed that the "random question from a set of questions" is not ideal because it is hard to "manage" the set of questions, e.g. adding or deleting questions from a set would have to be done individually for every quiz instance using the set.
Initially "random question from a tag" was discarded earlier because there are problems when users with different permissions are editing the question. If we add the questioncategory (context) to the information that would solve the ambiguity.
So we would have only one random question type, which could be further restricted by specifying a tag.

----
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).
----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a set of questions"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will change this table to abstract the logic for determining the question from the slot.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Make questionid allow null and add 1 new fields to the quiz_slots table.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]

Improved Question Bank Tags

2017-11-16T02:16:14Z

Damyon: Updates changing "random question from a set of questions" to "random question from a category + tagid"

== Overview ==

This document is the technical design for a set of features proposed by the Moodle Users Association for Moodle 3.5.

The project proposal is here: https://moodleassociation.org/mod/page/view.php?id=465

The requirements / user stories have been written by the MUA - a copy is included here for clarity

== User Stories / Requirements ==

Must:

* As a teacher, I can add tag(s) to a question bank question for use in my course for organizational and search/filtering of questions.
* As a teacher, I can filter my questions in courses based on tags.
* As a teacher, I can see tags on questions at higher category assigned by Question sharer role holder.
* As another teacher in the same course, I have access to the question tags on the questions in that course context.
* As a teacher in a course, I do not see tags of other in contexts I do not have access to. (Instructor 1’s “midterm 1” question set would not be relevant to Instructor 2)
* As a teacher, I am able to add/modify/remove tags on questions.
* As a teacher, I should not have to copy a question into my course from higher category contexts to include it in a ‘random question from question set’ question type.
* As a teacher, I can add a 'random question from question set' question type to my quiz where the question set is a selectable list of questions. These questions can be searched for and filtered by tag but the set itself is not defined by specifying a tag.

Nice to have:
* Tags can contain any visible ASCII characters including characters such as apostrophes, slashes, and colons. Exception of Comma.
* As a teacher, when searching for questions to add to a ‘random question from question set’ I see the question with its context clearly visible.
* As a teacher, I can export/import questions with their tags.
* As a Question sharer role holder, I can add a tag(s) to a question bank questions that exist at the category context.
* As a Question sharer role holder, I can search/filter all the questions I have access to and see them along with their context.

== Update ==
Following a meeting between Tim / Damyon I'm saving a record of the chat conversation here. I'll then update this design page based on those notes and delete the notes (but they will exist in the history).

----
Damyon, [08.11.17 21:06]
thanks - here are my notes (sorry they are rough - feel free to add more detail / correct them)

Damyon, [08.11.17 21:06]
# drop random question from set, replace with random question from tag + context, that makes to manage multiple questions from the same tag + context and we can store it all in the slots table

# plugin vs classes - much easier to do the ui and if it's all in one table classes makes sense.

structure.php could contain the classes.

correct to move category to this new model. upgrade is scary.

OU has 40,000 questions - need progress bar.

possible to have one random question from category in 2 quizes.

need to ensure that 3 random questions in a row do not get the same question.

mobile needs to duplicate this a bit.

use existing hooks

How much re-work for AMD?

re-do edit quiz page using templates + AMD + webservices - need to investigate how much work.

Move tagging UI into the question bank - not in the quiz.

Tim Hunt, [08.11.17 23:53]
Re: structure.php could contain the classes - Better to say: Classes could go in a new namespace corresponding to mod/quiz/classes/local/structure/. Should rpobalby move the existing classes/structure.php & repaginate.php in there. (There is no good reason why those are two separate classes. Feel free to change.)

Tim Hunt, [08.11.17 23:54]
Re structure.php could contain the classes - I would say that the fact that the OU only has 40,000 questions is a sign that this upgrade is not a scary as it might have been. No need for excessive measures, just a progress bar.

Tim Hunt, [08.11.17 23:55]
Re: possible to have one random question from category in 2 quizes - this certainly exists in the data, but really only because of past bugs. THe upgrade needs to deal with this, but that shoudl be possible.

Tim Hunt, [08.11.17 23:56]
Re: mobile needs to duplicate this a bit. - sorry, I was not clear. Mobile does not need to duplicate this. It calls a start attempt function, which uses the same sever-side PHP to build the quiz attempt, and returns a list of questions, so no worries there.

Tim Hunt, [08.11.17 23:59]
Both startattempt.php and mobile web service call quiz_prepare_and_start_new_attempt, which calls quiz_start_new_attempt, which is where the randomisation is currently done, so that is the key code to read. The other key class to understand is random_question_loader, used there.

Tim Hunt, [08.11.17 23:59]
I hope those clarifications are helpful. Other than that, good complete notes.

----

== Design ==

The requirements listed above can be met by implementing the following changes (which are described in detail further down):
* New question type "Random question from a set of questions"
* Enhanced question search allowing search/filter by tag everywhere
* Allow adding course level tags to questions that exist in a category

=== Random question from a question category + tag ===
==== Architecture ====
Currently the quiz_slots DB table has a questionid column that directly links to the question for that slot. We will change this table to abstract the logic for determining the question from the slot.

The slot type can be determined from the fields in the quiz_slots table. After these changes there will only be 2 possible slot types (single question, or random question). The random question will require a questioncategoryid and an optional tag.

We will introduce a new abstract class "mod_quiz\slot_type".

The slot_type subclass will be responsible for:
* Determining a specific question id from a quizid + slotid + userid. A new question id is only queried when a new attempt is started, or a question is re-attempted.
* Display of UI to configure this slot type (JS and non-JS).

When the slottype is "single" - the slot_type_single class is loaded directly from the quiz (not a sub-plugin). When the slottype is "random" the slot_type_random class is loaded directly from the quiz (also not a sub-plugin).

==== DB changes ====

Make questionid allow null and add 1 new fields to the quiz_slots table.
<code>

quiz_slots(id, slot, quizid, page, requireprevious, question, maxmark, category, tagid)
</code>

[[File:QBankTags-DBChanges.png|frame|center|DB structure changes]]

==== UI changes ====
These images are mockups '''for illustration only''' and are not to be taken as the final UI design.

[[File:RandomQuestionFromListMenu.png|frame|center|Random question from list added to quiz structure menu]]

[[File:RandomQuestionPopup.png|frame|center|Dialog to edit the list of random questions]]

[[File:RandomQuestionPicker.png|frame|center|Question picker to add questions to the random list]]

[[File:RandomQuestionInQuiz.png|frame|center|Random question from list added to a quiz]]

==== Upgrade Steps Required ====
* We will need to change the questionid column of the quiz_slots table to allow null. (Quick DB update, no conflicts to resolve).
* We will need to add columns to the quiz_slots table for questioncategoryid and tagid. (Quick update, columns will be initially null).
* We will need to search for all "random" questions in the question bank and for each one - move the configuration data to the quiz_slots table. This will be the slow part of the upgrade and will require a progress bar.
* We will then need to delete all "random" questions.

=== Search for question by tag ===

==== Architecture ====
There are 2 places we could (should) be able to search questions by tag.

The first is from the tag management page. This work has been started on https://tracker.moodle.org/browse/MDL-59781, all that remains to complete it is to create a moodle page that can show a single question from a question bank (so the tag search results page can link to the question).

The second is to be able to search for questions by tag in the question picker while adding questions to a quiz. There is an existing API to extend this search form and an example in the local plugin https://github.com/MorrisR2/moodle_local_searchquestions. This would just require adding a new plugin that implements the get_question_bank_search_conditions callback to return an instance of core_question\bank\search\condition for searching tags. The search field for tags should just be a text field. The current API does not allow javascript to be used in search conditions, if a full "autocomplete" element is required for the tags search we will need to extend the question bank API.

==== UI Changes ====
[[File:SearchQuestionsByTags.png|frame|center|Search for questions from global tag search]]

[[File:SearchByTagsInQuestionPicker.png|frame|center|Search by tags while picking questions from the question bank]]

=== Course level tags for questions ===

==== Architecture ====
This will be implemented by defining a new "tag area" for "course questions". The itemtype will be question and the component will be core_course. We will still have to implement the UI for adding and deleting "course question tags", and make sure that searching for questions by tags returns results from both the question tags, and the course question tags. We will add this new tag area to the backup/restore and ensure questions tagged in a course are included in the course backup file. Viewing the coursetags for a question will be controlled by a new capability: "moodle/course:viewquestiontags". Changing the course tags for a question will be controlled by a new capability "moodle/course:managequestiontags".

==== UI Changes ====

[[File:CourseTagsIconForQuestions.png|frame|center|Question shows course tags icon]]

[[File:ManageCourseTagsForQuestion.png|frame|center|Edit the course tags for a question]]