MoodleDocs - User contributions [en]

QA testing

2021-08-11T14:54:55Z

Moodlebot: Text replacement - "<code>" to "<syntaxhighlight lang="php">"

'''Quality Assurance''' tests look at the functionality of Moodle from a user's point of view.

Real users systematically try each feature in Moodle and test that it works in the current version of the Moodle code. These tests are repeated in series of cycles, usually 4 weeks before a major release, once all major features have landed.

'''QA testing latest''': ''A 100% pass rate was obtained in Moodle 3.11 QA testing. Many thanks to all our [[Testing credits|QA testers]].''
==Getting involved==

Would you like to help with QA testing? If so, please make sure you have created an account in the [[Tracker_introduction|Moodle tracker]] and you're subscribed to the [https://moodle.org/mod/forum/view.php?id=56 Testing and QA forum] in order to receive QA testing news updates.

==Running tests==

# Go to the [https://tracker.moodle.org/secure/Dashboard.jspa?selectPageId=11454 Moodle QA testing dashboard] and choose a test from the list of current QA cycle open issues. When viewing a test, if you wish, you can click the 'Assign to me' link on the right, so that nobody else chooses the same test to run. (If you then find you are unable to run the test, you can click the Assign button and set the assignee as 'Unassigned'.) Please note:
#* Only assign an issue to yourself which no one else is testing (Assignee = Unassigned).
#* Only assign one issue at a time unless you plan to test a number of related issues within the next 24 hours. In other words, don't assign several issues to yourself then do nothing for several days. ;-)
#* The label ''test_server_required'' indicates issues that can't be tested on the QA testing site. The label ''credentials_required'' indicates that credentials such as an OAuth 2 service client ID and secret are required.
# Using either the [https://qa.moodledemo.net/ Moodle QA Testing Site] or your own test site running the latest Moodle 4.0dev (available from Git on the integration/MOODLE_400_STABLE branch ''<nowiki>git://git.moodle.org/integration.git</nowiki>'') with [[:en:Debugging|debugging]] set to developer, perform each of the steps listed in the test.
# ''Please attach screenshots of the steps where you verify or check something.''
# If it makes sense, please test using the currently supported themes, Boost and Classic.
# Choose an appropriate workflow action:
#* ''Pass'' - Test runs perfectly. Add comment such as feedback about a new feature, browsers used for testing (if applicable; example: "This test passes on Q&A site with Teacher role using Boost theme"), or simply "This test passes - yippee!"
#* ''Fail'' - Something doesn't work, or you obtain debugging messages. Add comment describing the step that doesn't work. If in doubt whether to pass a test, give it a fail and add a comment describing your doubts.
#* ''Obsolete'' - Test is no longer relevant in the current Moodle version. Add comment explaining why.

If you notice that the test description is out-of-date, add a comment mentioning that it needs updating. Alternatively, if you'd like to help with updating the test yourself, see below.

==Any questions?==

If there is anything you are unsure of, such as whether to mark a test as failed, or you have any other questions, please ask in one of the following places:

* [https://t.me/moodleqa Moodle QA Telegram chat room] *new*
* [https://moodle.org/mod/forum/view.php?id=56 Testing and QA forum]

==Moodle QA Testing Site==

The [https://qa.moodledemo.net/ Moodle QA Testing Site] is updated daily at around 13:00 UTC with the latest bug fixes to enable you to re-run QA tests.

To prevent the site being used for sending spam, no emails are sent from it. Thus, tests involving email cannot be run using the Moodle QA Testing Site. (If such tests are attempted, an email debug message is displayed. This is not a bug but rather expected behaviour.)

Teacher and student accounts are provided. Please contact [https://moodle.org/user/profile.php?id=24152&course=1 Helen] if you would like admin or manager access to the Moodle QA Testing Site for running certain tests.

==<div id="failedTests">Failed tests</div>==

So you ran a test and it failed? Congratulations on finding a bug! Please do the following.

# Click the Fail button at the top of the page.
# Add a comment to the QA test stating that there was a problem and that you will report it as a Moodle bug.
# Note the MDLQA number; it will be something like <nowiki>MDLQA-448</nowiki>.
# Try searching for whether the bug has been reported previously, and if not create a new issue for it (as described in [[Tracker introduction]]).
# In the new Moodle (MDL) issue select 'Link' from the 'More actions' dropdown menu. [[Image:LinkIssue.png|150px|Linking to the QA issue in the tracker]]
# Link to the QA test by selecting 'blocks' as the link type, entering the MDLQA number that you noted earlier, and optionally adding a comment. [[Image:LinkDetails.png|150px|Adding details for a link to the QA issue]]
# Give the issue the label 'mdlqa'.
# (Optional) Add yourself as a watcher to the MDL issue so that you receive email notification when the issue is fixed.
# When the MDL issue is fixed, hopefully within a day or two, the QA test can be reset and can then be run again.

==Resetting tests==

''Note for integrators:''

After integrating a fix,

# Reset the MDLQA test, adding a comment.
# Remove the 'mdlqa' label from the MDL issue.
# If the issue doesn't have testing instructions, pass it with message "Will be tested by MDLQA-XXXX".

The tester will then receive email notification that the bug is fixed and will hopefully decide to run the test again soon.

==Fixing existing bugs==

At the beginning of the QA cycle, all bugs identified (both new and existing) are investigated promptly and hopefully fixed.

When we are close to the scheduled release date (1-2 weeks prior), developers must focus on fixing new bugs (which affect the upcoming release version) only.

Thus, at this point in the QA cycle, any bugs which also affect existing versions of Moodle are labelled qa_identified (and the label mdlqa removed) for investigation after the release.

==Testing tips==

When entering text into a form, try things like:

* <syntaxhighlight lang="php">&</syntaxhighlight> (ampersand), <syntaxhighlight lang="php">></syntaxhighlight> (greater than) or <syntaxhighlight lang="php"><</syntaxhighlight> (less than) e.g. <syntaxhighlight lang="php">x < 1 && x > 0</syntaxhighlight>
* <syntaxhighlight lang="php">0</syntaxhighlight> (the single digit 0)
* <syntaxhighlight lang="php">'</syntaxhighlight> (single quote) e.g. <syntaxhighlight lang="php">Fergal.O'Brien@example.com</syntaxhighlight>
* special characters e.g. <syntaxhighlight lang="php">café</syntaxhighlight> or <syntaxhighlight lang="php">囲碁</syntaxhighlight>
* very long strings
* different languages, such as a RTL language

==New QA tests required==

''Note for developers:''

If an issue fix cannot be covered by automated tests,

# Add the label 'qa_test_required' to the issue.
# Add a comment explaining why it can't be covered by automated tests and suggesting which steps of the testing instructions should be included in a QA test e.g. steps 6-10 or all steps.

QA tests will then be written and included in the next QA cycle. For issues with long testing instructions, several QA tests will be written to cover the issue. If appropriate, activities etc. will be set up on the [https://qa.moodledemo.net/ Moodle QA Testing Site] to enable the issue to be easily tested in future.

Similarly, for new features and improvements which would benefit from exploratory testing,

# Add the label 'qa_test_required' to the issue.
# Add a comment mentioning that exploratory testing is required.

Exploratory QA tests will then be written and included in the next QA cycle and then removed.

==Updating tests==

QA tests often become out-of-date due to new developments. If you would like to help with updating tests, you'll need to be a member of the test writers group in the Tracker. Please contact Helen about being added.

To update a QA test:

# Search for the master copy of the test - with affects version as 'Master copy' and MDLQA-1 as parent.
# Edit the test description.
# Optional: Add a comment describing your edit.

==Writing new tests==

Would you like to help with writing new QA tests? If so, as for updating tests, you'll need to be a member of the test writers group in the Tracker. Please contact Helen about being added.

To create a new QA test:

# Choose an issue from the [https://tracker.moodle.org/issues/?jql=labels%20%3D%20qa_test_required%20AND%20status%20%3D%20Closed closed qa_test_required-labelled issues]
# Do a quick search of MDLQA-1 to check if there is an existing test which can be updated
# If not, create a sub-task of MDLQA-1
# Select 'Original' as affected version
# Select appropriate components
# Set assignee as unassigned
# Write the test (usually between 3 and 10 steps). It's a good idea to try doing the steps yourself as you write the test.
# Add the label ''new''
# For tests which can’t be run on the QA site, label ''test_server_required''. For OAuth 2 tests and any other tests which require a client ID or secret to be entered, label ''credentials_required''.
# For issues which specifically mention in the testing instructions to test in different browsers, use the phrase "Test in as many browsers as possible and mention in a comment which ones you’ve used."
# For an exploratory test, begin the test description with "This is an exploratory test of a new feature or improvement, so please feel free to try anything you like and not just the test steps!"
# For a test requiring admin access which can be run on the QA site, add:
This test requires admin access. If you would like to use the [QA testing site|https://qa.moodledemo.net/] for running it, please see the [QA testing guide|https://docs.moodle.org/dev/QA_testing] for details of how to request admin access. Begin just after the hourly reset to give yourself plenty of time to complete the test!

13. Go to the MDL issue and create a ‘has a QA test’ link to the new QA test, adding a comment “Thanks for this improvement which is now covered by the QA test MDLQA....”, and remove the qa_test_required label. ''Make sure that all QA tests are linked back to a corresponding MDL issue.''

New tests will be included in the next QA cycle.

==Feedback==

Feedback on all aspects of our QA testing process is welcome. If you have any questions or comments, please post in the [https://moodle.org/mod/forum/view.php?id=56 Testing and QA forum].

==See also==

* [https://tracker.moodle.org/secure/Dashboard.jspa?selectPageId=11454 QA testing dashboard]
* [[Testing credits]]
* [[MDLQA-features]]
* [https://moodle.org/mod/forum/discuss.php?d=351302 Useful tips for QA testing]

Comments on tests from previous QA cycles:
* [https://tracker.moodle.org/browse/MDLQA-150 Moodle 2.0 QA Cycle 1]
* [https://tracker.moodle.org/browse/MDLQA-328 Moodle 2.0 QA Cycle 2]
* [https://tracker.moodle.org/browse/MDLQA-540 Moodle 2.0.2 QA]
* [https://tracker.moodle.org/browse/MDLQA-944 Moodle 2.1 QA Cycle 1]
* [https://tracker.moodle.org/browse/MDLQA-1190 Moodle 2.2 QA]
* [https://tracker.moodle.org/browse/MDLQA-1814 Moodle 2.3 QA]
* [https://tracker.moodle.org/browse/MDLQA-4602 Moodle 2.4 QA]
* [https://tracker.moodle.org/browse/MDLQA-5267 Moodle 2.5 QA]
* [https://tracker.moodle.org/browse/MDLQA-5740 Moodle 2.6 QA]
* [https://tracker.moodle.org/browse/MDLQA-6693 Moodle 2.7 QA]
* [https://tracker.moodle.org/browse/MDLQA-7170 Moodle 2.8 QA]
* [https://tracker.moodle.org/browse/MDLQA-7660 Moodle 2.9 QA]
* [https://tracker.moodle.org/browse/MDLQA-8205 Moodle 3.0 QA]
* [https://tracker.moodle.org/browse/MDLQA-9267 Moodle 3.1 QA]
* [https://tracker.moodle.org/browse/MDLQA-9827 Moodle 3.2 QA]
* [https://tracker.moodle.org/browse/MDLQA-10403 Moodle 3.3 QA]
* [https://tracker.moodle.org/browse/MDLQA-10999 Moodle 3.4 QA]
* [https://tracker.moodle.org/browse/MDLQA-11698 Moodle 3.5 QA]
* [https://tracker.moodle.org/browse/MDLQA-12282 Moodle 3.6 QA]
* [https://tracker.moodle.org/browse/MDLQA-12911 Moodle 3.7 QA]
* [https://tracker.moodle.org/browse/MDLQA-13517 Moodle 3.8 QA]
* [https://tracker.moodle.org/browse/MDLQA-14131 Moodle 3.9 QA]
* [https://tracker.moodle.org/browse/MDLQA-14813 Moodle 3.10 QA]
* [https://tracker.moodle.org/browse/MDLQA-15457 Moodle 3.11 QA]

[[Category:Quality Assurance]]

Languages subsystem improvements 2.0

2021-08-11T14:54:53Z

Moodlebot: Text replacement - "<code>" to "<syntaxhighlight lang="php">"

{{Infobox Project
|name = Languages subsystem improvements
|state = Complete
|tracker = MDL-18797 MDL-15252
|discussion = [http://moodle.org/mod/forum/discuss.php?d=118707]
|assignee = [[User:David Mudrak|David Mudrak]]
}}
{{Moodle 2.0}}

{{Warning|This page was once used as an initial specification of the project. Only parts of it were finally implemented. It is kept for archive purposes only.}}

This is a specification of changes to the language strings processing in Moodle 2.0 and 2.1. You should start looking at the [http://www.mindmeister.com/41382366/proposed-changes-for-moodle-2-x-languages-machinery overview of proposed changes] mindmap.

== Current issues ==

Why the changes in the current tools and process are needed:

; String files are not branched : We must keep all strings from all branches in place for backwards compatibility and we are unable to easily clean up language packs. Some say the branching and merging is too much work for our translators (see MDL-15252).
; Plural forms, gender forms and other grammar : We are unable to handle plurals at all. For example, handling [http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html plural forms in gettext] is traditional, well tested and robust way (see MDL-4790). MDL-12433 by Sam Marshall shows alternative approach based on logical expressions.
; Strings can't be modified : It is difficult to notify translators that some string was modified (expanded, fixed, changed) - as in [http://git.moodle.org/gw?p=moodle.git;a=commit;h=d033b1288713625a733ce5fcbce5e7b5a1f6d5d1 this case], for example. The current work around is the policy of adding another string with the same suffixed name (like 'license2'). It would be nice if such strings were tagged/highlighted in the translation UI.
; We do not use standard formats : Translators can't use specialized tools for translation (PO/gettext editors, community translation portals). Also, I (David) am not aware of any benchmarking showing the performance differences between out native $string[] format compared to, for example, standard .po format.
; More syntax checks are required : So the translators do not brake Moodle functionality (see MDL-12433)
; Language packs are PHP code, but stored in moodledata : This increases the severity of some security exploits. It means that any exploit that lets you write files to an arbitrary location in moodledata suddenly lets you execute arbitrary PHP code on the server. On the other hand, it would be nice to be able to allow complex logic when evaluating dynamic strings (ie such containing $a param/params).
; Right-to-left languages : There are problems reported in RTL languages when using online tools (including the our current one) which lead to putting placeholders like a$ and a$->lastname into the string definition.

== Goals ==

# Fix all the issues listed above
# Do not reinvent the wheel
# Keep "do one thing and do it well" principle
# Keep it simple and stupid.
# Have the translation process as simple as possible - translators are not geeks
# Make simple things easy and hard things possible
# Make most of this available for Moodle 2.0

== Key design questions ==

When working on the specification, these were the key questions to keep in mind:

; What is the data structure for storing the master copies of the lang packs : At the moment, strings are defined in plain PHP associative arrays, editable via translation UI or directly. These arrays are stored in PHP files in Moodle CVS. We are going to change it. According to the original Petr Skoda's proposal, the primary place for keeping all translated strings will be a central database at one of moodle.org servers. Together with the translation itself, usefule meta-data are kept in the database: the timestamp of the last modifications, links to the revision of the English string that the translation is based on, the author name, proposed alternatives, comments etc (see rosetta translation tool at launchpad for the example of possible metadata).
; What is the UI for translators, what are the processes of contributing and how the translations are redistributed to Moodle sites : Thanks to storing all strings in a database, we will be able to produce their list in various standardised formats (like PO or XLIFF). Therefore, the translators will not be forced to use the only one possible tool but can use their favourite advanced tool with its own translation memory, connected with dictionaries, i18n portals etc. Our central strings repository will support data export and import from/into various formats.
; What is the data structure that get_string() uses at runtime : This is just a performance optimization (implementation detail), should be independent on the native format that humans work with so it could be modified anytime in the future. For example, see the system proposed by Tim based on calling class methods (inspired by Perl's Maketext).
; What is the format of a lang string, and how are placeholders substituted : It is strongly tied together with the runtime format, it can be changed any time. On the other hand, both the UI and storage format must support it.

== Use cases ==

# Developers add new strings to the code and commit their work into CVS (core or contrib)
# Developers can add a comment to the string, eg. "this string is used for ..."
# Developers add new string and link it with a current one with an explanation eg "this string replaces ...". Such links are available to translators and help them to decide the correct translation.
# Developers moves the string from one component (like enrol.php) into another (like enrol_manual.php). The current translations are re-used.
# Developers change the string identificator, for example from configfoobar to foobar_desc.
# Translators translate strings on several Moodle branches and do not need to worry about branching, commiting and merging
# Translators can see the list of untranslated strings and translate them
# Translators can see the list of outdated translated strings (aka English string was changed) and update the translation
# Admins can locally modify the language pack for their site
# Community members can propose alternative translations. They are reviewed by the lang pack maintainer and may be approved.

== Research ==

This is the list of projects, resources and tools that were explored before writing this spec

* [http://search.cpan.org/~ferreira/Locale-Maketext-1.13_82/lib/Locale/Maketext/TPJ13.pod Great CPAN article about software localization]. Plain string based lexicon is not enough. Strings can be translated by functions only. "A phrase is a function; a phrasebook is a bunch of functions."
* [http://en.wikipedia.org/wiki/XLIFF XLIFF] - XML Localization Interchange File Format
* [http://translate.sourceforge.net/wiki/virtaal/index Virtaal] - promising, we could have XLIFF <-> .php conversion
* [http://launchpad.net/+tour/translation Launchpad] - translation portal used by Ubuntu and many other projects. Would require BSD licensing, therefore IMO not suitable as we could not import our current GPL'ed translation. Seems to be quite slow during the process.
* [http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html Plural forms in gettext]
* [http://framework.zend.com/manual/en/zend.translate.html Zend_Translate reference guide]
* MDL-12433 - Sam Marshal's proposal
* MediaWiki approach: [http://www.mediawiki.org/wiki/Manual:$wgGrammarForms Grammar forms] and plurals: <syntaxhighlight lang="php">{{plural:1|is|are}} {{plural:2|is|are}}</syntaxhighlight> (Example of how mediawiki outputs the correct given pluralization form depending on the count. Plural transformations are used for languages like Russian based on "count mod 10").

== Functional proposals ==

=== Overall strings processing flow ===

(Follow the attached UML flow diagram) [[Image:languages20_overview1.png|thumb|right|UML: Overall string processing flow]]

* All string definitions are kept in a central database togeteher with other all meta-data (branch, where does the string come from, what was its history etc.). Officially maintained language packs are referred to as ''master'' in this proposal. Every language pack can have its ''parent'' defined. The English language pack can be seen as the greatest common parent of all language packs.
* During upgrade or on demand, the relevant branch of master language packs are fetched (downloaded) automatically from the central database. Together with the selected language, all its parents, grandparent, great-grandparents, ... etc are downloaded, too.
* Administrators can keep local modifications (customizations) of any master pack. We call them ''local'' language packs.
* Immediately after upgrade (or again, on demand), the string definitions are merged from all available sources. The merge logic is so that the sources for any given string are evaluated in the order like: fr_ca_local, fr_ca, fr_local, fr, en_local, en. Strings are merged for the performance reasons so that the searching for the string to use (local, parent, master, English etc.) is done just once and we do not need to load all possible sources on runtime. After the merge, we have a single place to look for the string definition for every installed language. By default, the location for these merged strings will be $CFG->dataroot/cache/lang/XX/component.php where XX is the language code (fr_ca, fr, en in this example). The benefit is that get_string() can rely on always having the string defined in this file, no other seeking and I/O is needed in runtime.
* Together with the merge, strings are compiled into a runtime format that may be optimised in the future. Humans do not modify the compiled format. Strings must be re-merged and re-compiled after any update of master or local packs. During the compilation, syntax checks are performed.
* The runtime format we will start with will be very similar with the current one. Strings are defined as array elements indexed by the string identifier. The arrays are defined in separate files for every module. We can, however, modify this in the future. For example, we can divide string definitions into files not by the module name but by the real usage frequency. Strings that are used very often (like at every page) would go into common file which can be loaded during bootstrap. This would reduce memory usage and number of I/O operations.
* There will be a way how to let get_string() call a PHP function/method to actually return the translated string instead of a static string definition. This will allow advanced translators to deal with many grammar issues they have in their languages (notably singular v plural forms).

=== Naming and locations ===

* Languages will be reffered to as "en", "cs", "en_us" or "fr_local" etc. Directories will be renamed.
* Downloaded lang packs are stored in $CFG->langpacks, which is by default $CFG->datadir/lang. Paranoid admins can change this to a different location that is normally read-only for the web server. Then they will manually switch to read-write when they are performing an upgrade, doing lang editing, or installing a lang pack. The UI should therefore check whether $CFG->langpacks is writable before starting any of these operations, and explain the situation to admins if it is not.
* After mergin and compiling, the strings in runtime format are stored in $CFG->dataroot/cache/lang/ (see above).
* All core plugins will have their language files in their own scope as the contrib plugins have. So for example workshop strings will be defined in '/mod/workshop/lang/en/workshop.php' instead of legacy '/lang/en_utf8/workshop.php'

=== HTML help files replaced with ordinary strings ===

Help should consist of a paragraph or two of a static HTML only, the rest goes to wiki. We will drop help files indices (index of all help files) as well as other dynamically generated helps in favour of wiki. This will make the translation easier as we do not need to have other tools to translate help files.

Help strings are kept together with other workshop strings as in <syntaxhighlight lang="php">$string['intro'] = 'Workshop intro'; $string['intro_help'] = 'This is the ...';</syntaxhighlight>. It allows to keep the string and their help together which helps translators to keep translation consistency.

See [[Help strings]] for further information.

=== Other changes ===

* The only valid placeholder in runtime format is <syntaxhighlight lang="php">{$a}</syntaxhighlight> for strings and numbers and <syntaxhighlight lang="php">{$a->foobar}</syntaxhighlight> for objects MDL-18841.
* Around 90% of our strings do not contain any placeholder and they will be immediately returned by get_string().
* If the string contains one or more placeholders, they are replaced with their eval()-uated result. We can safely eval() the whole string definition because the string compiler makes sure that the placeholders are the only executable/evaluable code. All other malicious code and $variables are properly quoted/escaped/htmlentitled.
* Valid format of string identifier must be defined. These identifiers may be used as associative array keys (as in <syntaxhighlight lang="php">$string['identifier']</syntaxhighlight>), function names, HTML form field names, file names etc. No characters like '*' can be used (as happened in MDL-21375).
* Some string identifiers are not hardcoded (explicitly referenced) in the code but computed, eg. <syntaxhighlight lang="php">get_string('level' . $level, 'arcade')</syntaxhighlight> with strings 'level1', 'level2', 'level3' etc being defined. It is difficult to automatically search for the usage of such strings. Therefore, I (David) propose the following guideline (rule): String identifiers must follow our convention for naming $variables: single lowercase word, no underscore. The colon (:) sign can be used only in strings with the names of capabilities and nowhere else. The minus sign (-) can be used only in string identifiers witch are partially computed, as in <syntaxhighlight lang="php">get_string('region-' . $regionid, 'theme_example')</syntaxhighlight> so that is a sign that we should be careful when trying to find an usage of such string in the code. The underscore is reserved for special _help and _desc suffixes.

=== Central web-based translation tool ===

See [[Automated_Manipulation_of_Strings_2.0]]

== Implementation proposals ==

Read [http://moodle.org/mod/forum/discuss.php?d=118707#p542197 Petr's proposal] to store strings in one central database and to disable direct commits. That is roughly valid with the exception that the "no change meaning" rule is not forced. AMOS is able to track changes and inform translators that their translation is outdated. So we will be able to fix/update/extend English string as needed. Together with branching, this will lead to a nice "reduced" packs without redundancy.

=== Translation tools and the process ===

See MDL-15252 (Cleanup of English language pack) and the discussion at http://moodle.org/mod/forum/discuss.php?d=118707 for Koen's proposition. Branching issue, the translation process and other aspects discussed there.

Some notes:

From Martin in Dev chat: ''if you want crazy ideas, how about get_string returns some special tags and those tags get converted to ajax on the GUI so that translators can translate directly in the main Moodle GUI?''

What a cool idea. Could be a special mode you have to turn on in the admin screens. Perhaps even if you turned this mode on, it would still only be active for people with certain roles, or perhaps when it was turned on, it would have to apply to all roles, so that you could edit strings for not-logged-in users. Anyway, when this mode was on, it would:

# Adds Language editing around each string on the page - to use one example.
# $PAGE->requires->js an extra JS file that adds an on-click handler to all such spans, so that when you click on it, it pops up the language editing UI in a YUI dialogue.

:: [[User:David Mudrak|David Mudrak]] 14:07, 23 November 2009 (UTC): the solution based on wrapping around every string was already considered and dropped. It may badly break XHTML as the string itself may appear as a value of an HTML tag's attribute: <syntaxhighlight lang="php"><img title=". We are unable to say the scope where the string will appear.
:: David's contra-proposal: get_string() could track all strings used at the current page and the AJAX form to edit them all could be rendered before the footer(). Or 'Edit system text on this page' link would appear there.

=== Getting the history of strings into database ===

Source code management systems can't show us how the given string evolved during the time. Translators on the other hand need to know "personal history" of any given string, each with the author of the change, date, comment etc. String timeline will be populated from DB. To let it work, we will need to load all the strings history into DB. That can be done using our git mirror. This conversion is done:

# Regularly for the master English strings that are part of Moodle source code. David already has a prototype of script to track commits into languages files and updates the database.
# Once for all other languages. When we have the new translation portal prepared, we will stop supporting direct CVS commits into languages. The history of all commits into all lang packs will be transferred into the database and further translations will be recorded there.

David is writing these migration script as a part of his [[Languages/AMOS]] tool.

== Design decisions and voting ==

* MDL-21690 Central master database of all strings and their translations
* MDL-21635 Decide how to implement information in langconfig.php in AMOS
* MDL-21693 Drop _utf8 suffix from language codes and folder names
* MDL-21694 Move language files to the plugin space
* MDL-21695 Replace built-in HTML help files with proper strings

== See also ==
* [http://live.gnome.org/TranslationProject/GitHowTo How to use Git for GNOME translators]
* [http://translate.sourceforge.net/wiki/ Nice site with tools, localisation problems and alternatives...]
* [[Languages:Tim's crazy proposal based on maketext]]

[[Category:Language]]

Global search (GSoC2013)

2021-08-11T14:54:49Z

Moodlebot: Text replacement - "<code>" to "<syntaxhighlight lang="php">"

{{obsolete}}
{{Infobox Project
|name = Global search
|state = Coding period
|tracker = MDL-31989
|discussion = [https://moodle.org/mod/forum/discuss.php?d=227805 Writing Moodle's Global Search]
|assignee = [https://moodle.org/user/view.php?id=1565904&course=5 Prateek Sachan]
}}

GSOC
 '13


== Introduction ==
Global Search will have the feature of searching keywords within the entire Moodle site across modules keeping the security intact having full-text advance search capabilities.
*It will display results based on relevance weightage.
*Security will be preserved throughout the search.
*Search Modules will enable chosen search engine integration with ease. Admins will have the option for selecting the modules that could be made "searchable"
*It will include keywords from other files types (like PDFs, PPTs, HTML content and others).
*Following are the features that I'm considering in implementing in the first version of Global Search:
# Groupings of boolean operators:<syntaxhighlight lang="php">AND</syntaxhighlight>, <syntaxhighlight lang="php">OR</syntaxhighlight>, <syntaxhighlight lang="php">NOT</syntaxhighlight>. Eg.: <syntaxhighlight lang="php">("query1" AND "query2") OR ("query3" NOT "query4")</syntaxhighlight>
# Highlighting: All matched keywords will be highlighted. For long content, only a short part will be displayed alongwith the highlighted keyword.
# Searching for phrases. Results with matched phrase will have higher priority and hence will be shown higher in the results.
# Wildcard (<syntaxhighlight lang="php">*</syntaxhighlight>) (<syntaxhighlight lang="php">?</syntaxhighlight>) feature.
# Stemming. Eg.: <syntaxhighlight lang="php">bag</syntaxhighlight> will return results both from <syntaxhighlight lang="php">bag</syntaxhighlight> and <syntaxhighlight lang="php">bags</syntaxhighlight>
# Proximity Searches:
:*"mood"~2 returns "moodle". (2 alphabets away from the searched term).
:*"moodle australia"~3 returns results containing "moodle hq at perth australia" (the queried terms were within 3 words of each other)

== Requirements ==
*Moodle 2.5 and above.
*PHP Solr extension.

==Design==
'''Adding a Global Search Block'''

[[File:Add_Global_Search_Block.png]]

'''Search through Global Search Block'''

[[File:Global_Search_Block.png]]

'''Global Search Results UI'''

[[File:Global_Search_Results_UI.png|900px]]

'''Global Search Admin Solr settings'''

[[File:Global_Search_Admin_Solr_Settings.png|900px]]

'''Global Search Admin Modules Activation'''

[[File:Global_Search_Admin_Module_Activation.png|900px]]

'''Global Search Admin Indexing Statistics'''

[[File:Global_Search_Admin_Indexing_Statistics.png|900px]]

== Admin Controls ==
These controls appear under Site Administration > Global Search. (Please refer the screenshots above).
=== Search Engine ===
This will enable you to choose your preferred Search Engine. Currently, Global Search only supports Apache Solr.
=== Solr Settings ===
This section lists down the various server connection settings that you'll need to configure for your server.
=== Activated Modules ===
This section lists down the modules that are enabled in Global Search for indexing and searching of the content within them. You may activate/deactivate modules.
=== Indexing Statistics ===
*This lists down the indexing statistics of Global Search.
*It also gives you the control for deleting index from specific modules or deleting the entire index in one go. (Deleting "Entire Index" deletes the entire Solr index irrespective of whether a module is activated/deactivated).
*The content will have to be re-indexed through cron.

== Installing PHP Solr extension==
=== UNIX ===
*You may download pecl-php-solr extension version <syntaxhighlight lang="php">1.0.3-alpha</syntaxhighlight> by <syntaxhighlight lang="php">git clone https://github.com/lukaszkujawa/php-pecl-solr.git</syntaxhighlight> or official versions <syntaxhighlight lang="php"><=1.0.2</syntaxhighlight> from http://pecl.php.net/package/solr. (Extract the contents in a directory)
*Install the extension dependencies by executing <syntaxhighlight lang="php">apt-get install libxml2-dev libcurl4-openssl-dev libpcre3-dev</syntaxhighlight>
*Restart apache server. <syntaxhighlight lang="php">sudo service apache2 restart</syntaxhighlight>
*Assuming you cloned or downloaded the extension in a directory, you'll have to compile the downloaded extension.
*<syntaxhighlight lang="php">cd /your-downloaded-or-cloned-php-solr-extension-directory/</syntaxhighlight>
*<syntaxhighlight lang="php">phpize</syntaxhighlight>
**This a shell script used to prepare the build environment for a php extension to be compiled. If you don't have <syntaxhighlight lang="php">phpize</syntaxhighlight>, you can install it by executing <syntaxhighlight lang="php">sudo apt-get install php5-dev</syntaxhighlight>
<syntaxhighlight lang="php">sudo ./configure</syntaxhighlight>
*sudo make
*sudo make install

The above procedure will compile and install it in the <syntaxhighlight lang="php">extension_dir</syntaxhighlight> directory in the <syntaxhighlight lang="php">php.ini</syntaxhighlight> file. To enable, the installed extension, you could follow any of the following two steps:

1. Navigate to the directory <syntaxhighlight lang="php">/etc/php5/conf.d</syntaxhighlight> and create a new <syntaxhighlight lang="php">solr.ini</syntaxhighlight> file with the following line:
extension=solr.so

OR

2. Open your <syntaxhighlight lang="php">php.ini</syntaxhighlight> file and include the following line:
extension=solr.so

You may follow any of the above two steps. You will need to restart your apache server after that by executing <syntaxhighlight lang="php">sudo service apache2 restart</syntaxhighlight>

You can now view the '''solr''' extension details by clicking '''PHP info''' from Site administration > Server in browser or <syntaxhighlight lang="php">php -m</syntaxhighlight> in Terminal (<syntaxhighlight lang="php">Ctrl+Alt+T</syntaxhighlight>)

=== OSX using macports ===
This method provides an easy install of php solr extension without any downloads.(php solr extension version: <syntaxhighlight lang="php"><=1.0.2</syntaxhighlight>)
- sudo port install apache-solr4
- sudo port install php54-solr

you can choose your relevant available versions @ http://www.macports.org/ports.php?by=name&substr=solr

== Setting up Global Search for Moodle ==

After installing the php-pecl-solr extension, users will have to download the required [http://lucene.apache.org/solr/ Apache Solr] release (version 4.x for solr-php extension <syntaxhighlight lang="php">1.0.3-alpha</syntaxhighlight> or 3.x for solr-php extension version <syntaxhighlight lang="php"><=1.0.2</syntaxhighlight>), unzip it and keep it in an external directory of Moodle.

Users will have to replace <syntaxhighlight lang="php">solconfig.xml</syntaxhighlight> and <syntaxhighlight lang="php">schema.xml</syntaxhighlight> inside the downloaded directory <syntaxhighlight lang="php">example/solr/collection1/conf/</syntaxhighlight> with the ones that Global Search will provide in <syntaxhighlight lang="php">/search/solr/conf/</syntaxhighlight> directory.

Once the files have been copied and replaced, users will have to start the java jetty server <syntaxhighlight lang="php">start.jar</syntaxhighlight> located in <syntaxhighlight lang="php">/example/</syntaxhighlight> directory by executing <syntaxhighlight lang="php">java -jar start.jar</syntaxhighlight>. For the production setup you may prefert to [http://jmuras.com/blog/2012/setup-solr-4-tomcat-ubuntu-server-12-04-lts run solr on tomcat 6 or 7] and Ubuntu server.

Admins will then have to Enable Global Search in Site Administration > Plugins > Global Search > Manage Global Search

== Searchable content in Global Search==
Following are the modules/resources covered so far in Global Search. I'll be continuing my work, including other modules shortly as well.

All the contents of the following modules including all uploaded rich document media(PDFs, PPTXs, .TXTs, etc.) will be indexed and made searchable taking proper care of security through Moodle capabilities.

*Book Resource
*Forum Module
*Glossary Module
*Label Resource
*Lesson Module
*Page Resource
*File Resource
*Url Resource
*Wiki Module

The search results will display highlighted matched queries alongwith context links/direct links to the corresponding record.

== Implementation and Milestones ==
*Writing cron jobs:(17th June - 21st June)
**Addition of records.
**Deletion of records.[shouldn't be focused upon just now]
**Update of records.
*Design the solr schema and solconfig files. (22nd June - 26th June)
**These files will be embedded in the in a separate directory under the Global Search directory. Users will have to copy these two files to the Apache Solr example directory that they will download which will run the Solr jetty server. See Installation for more.
**<syntaxhighlight lang="php">schema.xml</syntaxhighlight> contains all the properties about the documents fields which are being indexed. There may be different fields pertaining to different modules.
**<syntaxhighlight lang="php">solrconfig.xml</syntaxhighlight> contains the configurational parameters for solr.
*Writing the core search API for all searchable modules. (27th June - 3rd July)
**_SEARCH_ITERATOR($from=0)
**_SEARCH_DOCUMENTS($id)
*Adding proper security to the search API.(4th July - 8th July)
**_SEARCH_ACCESS($id)
***Use of Access API
****ACCESS_DENIED
****ACCESS_GRANTED
***ACCESS_DELETED: Situations where the records may have been deleted-hence not viewable.
*Reviewing all the above once. (9th July - 10th July)
*Integrating Apache Tika to handle indexing from external files (<syntaxhighlight lang="php">PDFs</syntaxhighlight>, <syntaxhighlight lang="php">PPTX</syntaxhighlight> etc.) (11th July - 13th July)
*Writing the search functions for querying. (Just a basic search UI to be used at this moment). (14th July - 17th July)
**Input for query.
**Input for filter fields for filtering the search results.
**Input for AND/OR.
**Phrase searches.
**Stemming.
**Support for wildcards.
*Admin page for search configuration options. (18th July - 21st July) (The UI page here will be the default type as being currently used. For example, Site Administration>Advance features)
**Deletion of index.
***Deletion of entire index in one go.
***Deletion of index by specific modules only.(For example, only the index of records belonging to 'forum' module is to be deleted).
**configurational options for cron
***Time of cron run.
*Implementing and releasing the first prototype <syntaxhighlight lang="php">version: 1.0</syntaxhighlight> for developers' feedback. (22nd July - 28th July)
**See the '''Prototype''' section.
*Preparing for mid-term evaluation. (29th July - 1st August)
*MID_TERM EVALUATION (2nd August)
*Re-designing the search page. (2nd August - 7th August) (Taking ideas from community+discussion in [https://moodle.org/mod/forum/discuss.php?d=227805 forum])
*Improving the prototype after feedback from developers.(8th August - 15th August)
**Bug-fixing.
**Fixing security leaks.
**Improving relevance & speed of search results.
*Running Test cases and performance testing. (16th August - 21st August) (Performance testing will be good at this point as the code would have been optimized to some level as instructed by the developers above)
*Debugging. (22nd August - 29th August)
*Finalizing the Global Search documentation. (30th August - 6th September)
**Discussing it with my mentors whether everything has been properly covered or not.
*Buffer Period. (7th September - 8th September)
**Making sure everything above has been implemented correctly and efficiently.
*Submitting my code to Moodle and Google. (9th September - 15th September)
*Suggested Pencils Down Period. (16th September)
*Performing edits to the documentation after feedback from the Moodle community. (17th September - 22nd September)
*Firm Pencils Down and Final Evaluation. (23rd September)

== Quick setup for testing ==
This covers the features and procedure to install Global Search plugin. It would be very good if developers may come forward to test it and give their feedback which would be very crucial for improving it.
Developers may check out the cases in the '''Testing''' section. Developers may add their own preferred test cases and results (pass/fail) in that section which would be helpful for the other developers or you may comment on [https://moodle.org/mod/forum/discuss.php?d=227805 Global Search] discussion on Developer Forum.
*Here are some things that I've summarized that may be focused upon:
**Finding out any security leaks that I may have missed out.
**Relevance/speed of displaying search results.
**Taking ideas to optimize the [https://github.com/prateeksachan/moodle/tree/gs2rebased source code] wherever possible.
**Getting feedback.
**Addition/deletion of any search features that you may feel would be useful.
*Features included in this prototype:
**Indexing/Searching of content in all the above mentioned modules/resources.
**Support for indexing/searching rich documents.
**Admin configuration options.
**Support for advanced search queries as stated above.
*Steps to install and test Global Search plugin:
**Make sure you've installed your preferred PHP Solr extension (see sections above).
**You can simply clone my Github branch and checkout <syntaxhighlight lang="php">gs2rebased</syntaxhighlight> branch.
:<code language="text">
git clone https://github.com/prateeksachan/moodle.git
git checkout gs2rebased
</syntaxhighlight>
**Go to '''Setting up Global Search in Moodle after installing PHP Solr extension''' section above.
**Open <syntaxhighlight lang="php">../moodle/admin</syntaxhighlight> in your browser, and update the admin Global Search settings.
**Indexing is through cron. You will have to run the cron script to index content.

==Search workflow==
===Simple version===
# Moodle sends a query to standard solr handler.
# solr returns 1000 results. Results include all fields required to render search result row. Results are ordered by relevancy.
# Moodle checks each result in order to establish if it should be visible for current user or not
# Once 100 visible results are found, Moodle stops checking the rest and displays 100 results

The best case scenario is that Moodle needs to check only 100 returned results (first 100 are accessible for the current user).
The worst case scenario is that out of 1000 returned documents, none of them is available for the current user. In this case Moodle performs 1000 checks and displays "no results found" message.

===Advanced version===
More advanced version will use a logic on solr side to pre-filter some of the results.

== Testing ==
A list of test cases.
===New content===
* index
* add new forum post
* re-index

* make sure new content is searchable

===Updated content===
* index
* edit existing forum post
* re-index

* make sure new content is searchable
* make sure old content is not searchable

===Deleted content===
* index
* delete existing forum post
* re-index

* make sure deleted content is not searchable

===Backup restored===
* index
* restore whole course from a backup
* re-index

* make sure restored content is searchable

===Access Tests===
====Common Access====
*Add courses.
*Create activity modules/resources that are supported by Global Search (See section '''Searchable content in Global Search''').
*Insert content or attach files (wherever possible)
*Index
*Make sure the results are visible only to those who have access to the respective course's activity/resource.
*Set Common Module Settings of activities/resources as Hidden.
*Make sure those activities/resources do not appear in search results.

====Forum Activity Module Access====
*Create a course.
*Create groups in it.
*Create a Forum Activity.
*Post in the forum discussions from members of different groups. (+you may also attach files)
*Index.
*Make sure members see posts only from those groups which they are a member of.

====Lesson Activity Module Access====
*Create a course.
*Create a Lesson Activity.
1. Type 1
*Assign Availability
**Available From only
**Deadline only
**Time limit
**Password Protection
**Combinations of the above
*Index.
*Make sure there are no access leaks when searching as a student.
*Make sure the teacher, manager are able to see the searches.

2. Type 2
*Assign Prerequisite Lesson
**Set Dependent On Prerequisite feature.
**Set Time spent Prerequisite feature.
**Toggle completed Prerequisite feature.
**Set Grade Prerequisite feature.
**Combinations of the above.
*Index
*Make sure there are no access leaks when searching as a student.
*Make sure the teacher, manager are able to see the searches.

====Wiki Activity Module Access====
*Create a course.
*Create Groups.
*Create a Wiki Activity.
*Set Group Mode On
1. Type 1
*Group Mode: Separate Groups
*Add Wikipages. (+you may also attach files)
*Index
*Make sure there are no access leaks: A group shouldn't see results from other groups.
2. Type 2
*Group Mode: Visible Groups
*Add Wikipages.(+you may also attach files)
*Index
*Make sure there are no access leaks: A group shouldn't see results from other groups.

====Results====
#
#
#
#

== Credits ==
*My Mentors:[https://moodle.org/user/view.php?id=353008&course=5 Tomasz Muras] & [https://moodle.org/user/view.php?id=1146834&course=5 Aparup Banerjee]
*[http://lucene.apache.org/solr/ Apache Solr Community]
*[https://github.com/ecaron/php-pecl-solr PHP-Solr extension for Solr 4.x]

== See also ==
* [[GSOC/2013|Moodle GSoC projects for 2013]]
* [[GSOC|Moodle GSoC Overview page]]
* [https://moodle.org/mod/forum/discuss.php?d=227805 Writing Moodle's Global Search Discussion]

[[Category:GSOC]]
[[Category:Project]]

CodeSniffer

2021-08-11T14:54:45Z

Moodlebot: Text replacement - "<code>" to "<syntaxhighlight lang="php">"

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Installing PHP CS===

'''Using pear installer'''

1. Install the Pear package for PHP CS, pear install PHP_CodeSniffer

2. Download the standard: PHPCompatibility and moodle directories from https://github.com/moodlehq/moodle-local_codechecker

3. Copy the previous directories to the PHP CS standard path:
* in Mac with Macports is /opt/local/lib/php/PHP/CodeSniffer/Standards/
* In Mac with Homebrew is /usr/local/share/pear\@7.0/PHP/CodeSniffer/Standards/
* in Linux is /usr/share/php/PHP/CodeSniffer/Standards/ or /usr/share/php/PHP/CodeSniffer/src/Standards

4. If they are installed properly, moodle and PHPCompatibility will show up in the output of `phpcs -i`. Here is a typical example:
<syntaxhighlight lang="php">
The installed coding standards are MySource, PHPCompatibility, Squiz, PSR2, moodle, PEAR, PSR1, PSR12 and Zend
</syntaxhighlight>

5. Optionally, you can set the default standard in a configuration file:
<syntaxhighlight lang="php">
phpcs --config-set default_standard moodle
</syntaxhighlight>

'''Install using composer'''

1. Run the following in your terminal from your moodle folder:
<syntaxhighlight lang="php">
composer global require "squizlabs/php_codesniffer=3.*"
</syntaxhighlight>

2. Download the standard: PHPCompatibility and moodle directories from https://github.com/moodlehq/moodle-local_codechecker
to an accessible location on your computer - it doesn't have to be your project folder.

Note: "blackboard-open-source/moodle-coding-standard" is no longer being maintained.

3. Tell phpcs about where to find the Moodle code checker
<syntaxhighlight lang="php">
phpcs --config-set installed_paths /path/to/moodle-local_codechecker # adds moodle's standard to phpcs
</syntaxhighlight>

4. If they are installed properly, moodle and PHPCompatibility will show up in the output of `phpcs -i`. Here is a typical example:
<syntaxhighlight lang="php">
The installed coding standards are MySource, PHPCompatibility, Squiz, PSR2, moodle, PEAR, PSR1, PSR12 and Zend
</syntaxhighlight>

5. Optionally, you can set the default standard in a configuration file:
<syntaxhighlight lang="php">
phpcs --config-set default_standard moodle
</syntaxhighlight>

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

====Windows set up====

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will not include Moodle. To install the moodle standard, copy the"moodle" and "phpcompatibility" folders from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

====Linux set up====

After installing codesniffer and codechecker, copy the moodle and phpcompatibility standard folders from (assuming you have the code in /local/codechecker)

/var/www/moodle/local/codechecker/

to

/usr/share/pear/PHP/CodeSniffer/Standards/

There is an option to set the default standard in a configuration file:

phpcs --config-set default_standard moodle

Then restart Netbeans and it should now work. You can also switch between coding standards.

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<syntaxhighlight lang="php">
lib/pear/PHP/runsniffer index.php
</syntaxhighlight>

You will get a report that looks like this:

<syntaxhighlight lang="php">
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</syntaxhighlight>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<syntaxhighlight lang="php">
lib/pear/PHP/runsniffer -n index.php
</syntaxhighlight>

Resulting output:
<syntaxhighlight lang="php">
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</syntaxhighlight>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<syntaxhighlight lang="php">
lib/pear/PHP/runsniffer --report=summary files
</syntaxhighlight>

Report:
<syntaxhighlight lang="php">
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</syntaxhighlight>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<syntaxhighlight lang="php">
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</syntaxhighlight>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===

When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle core, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

For using the thirdpartylibs.xml in your plugins, please see [[Plugin files#thirdpartylibs.xml]].

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]

Bug triage

2021-08-11T14:54:42Z

Moodlebot: Text replacement - "<code>" to "<syntaxhighlight lang="php">"

[[File:Triage.png|200px|right|alt Triage image]]
Triage is medical term referring to the process of prioritising patients based on the severity of their condition so as to maximise benefit (help as many as possible) when resources are limited.

Bug triage is a process where tracker issues are screened and prioritised. Triage should help ensure we appropriately manage all reported issues - bugs as well as improvements and feature requests.

Triage initially happens shortly after the issue was reported but it can be repeated later if the initial assumptions were wrong, issue was resolved otherwise, affected versions need updating or there are other reasons to review the issue.

==Get involved==

Anybody can do triage in form of correcting the components and/or affected versions, linking to related issues, and of course commenting asking for clarification, confirming bug, redirecting to forum, etc. Users in ''jira-developers'' and ''moodle-triage'' groups can edit any issue, ''jira-users'' can comment on any issue or edit issues they reported. Please see MDLSITE-3592 if you are not a developer but would like to help with triage process.

Adding ''triaged'' label and placing the issue on the backlog should only be done by component lead or HQ developer. At the same time other users can remove ''triaged'' label from the old issues or replace it with ''triaging_in_progress'' if they want to request an additional triage.

==The triage process==

===Initial screening===

First of all, identify the issues that should be closed or placed under investigation. Ask the following questions:

* '''Is the issue a request for support/help?''' If so, the reporter should be directed to the forums to seek help and the issue should be closed as "Not a bug". Sometimes improvement requests can be phrased as a question, though; if this is the case, ask the reporter to reword the description to describe an improvement.
* '''Have the reporter mistaken the Moodle Tracker with their own support desk?''' Sometimes people mistake the Moodle Tracker as a place to request help about their own Moodle instance, often about logging in. We need to refer the user to their instance administrators and close the issue as "Not a bug".
* '''Has the issue been reported previously?''' If so, link to a duplicate issue and close the newly reported issue as a "Duplicate" with no fix version set. Encourage the reporter to search before reporting. If a newer issue has a patch or more voters/watchers, consider closing the older issue. Checking for duplicates first will save you having to check the rest of the issue. See [[Tracker tips]] for help with effective search of tracker.
* '''Does the problem affect only unsupported versions?''' If so, the issue should be closed using "Fixed" (preferred as it sounds better) when the issue is resolved in current versions or "Not a bug" when the issue has disappeared due to changes leading to current versions. See [Releases] to find currently supported versions
* '''Did the problem arise because of mistake in documentation or lack thereof?''' If it appears that the reporter does not understand a particular feature in Moodle and the documentation is lacking, ask the reporter where would he expect to find documentation about it. Then simply edit the relevant pages in the documentation wiki and close the issue. If required change is significant, add ''Documentation'' component and ''docs_required'' label.
* '''Is the problem a language string change?''' Language string problems can be corrected by [[Contributing a translation|contributing a translation]] or by contacting the language pack maintainer as listed in the [https://lang.moodle.org/local/amos/credits.php Translation credits]. English language string typo fixes and suggested improvements can be [[Improving English language strings|contributed to the English (fixes) (en_fix) language pack]] or given the component 'Language' for fixing by the Language component lead. Such issues should be closed in the Tracker using "Deferred".
* '''Is it a usability issue?''' If so, add the component "Usability" in addition to the component(s) specifying the area of Moodle.
* '''Was the problem caused by additional code or 3rd party plugins?''' If you can identify the plugin, move the issue to the respective component of CONTRIB project. Otherwise comment and close as "Not a bug".
* '''Can this be implemented as a plugin?''' And maybe the plugin already exists in the plugins directory. Explanation should be given to the reporter that Moodle provides the framework but does not work on any possible plugin. Add label "addon_candidate" but do not close the issue. This can also apply to the requests to significantly redesign existing plugins and it would be more preferable to create a new alternative plugin.
* '''Does the problem seem rational?''' If not, then the problem may simply be an misunderstanding on the part of the reporter. It might be a problem exclusive to the reporter's server set-up. If you can replicate the problem quickly, do so. If you can't replicate the problem, ask the reporter to attempt to replicate the problem on http://demo.moodle.net. If the problem seems persistent but strange, consider asking a developer with experience working in the area to consider the problem and determine if it could be a real problem.
* '''Can the problem be replicated?''' If not, or information on the issue is insufficient, ask the reporter to add error messages, screenshots, environment information (OS, web server, browser) and exact replication instructions

As a result of initial screening up to 20% of new issues may be closed. When closing the issues make sure to set the correct resolution and write a polite comment with explanation, refer to the templates below. If you have doubts, ask the questions and always add label [https://tracker.moodle.org/issues/?jql=labels%20in%20%28triaging_in_progress%29 triaging_in_progress]. Subscribe to the filter [https://tracker.moodle.org/issues/?jql=labels%20in%20%28triaging_in_progress%29%20AND%20project%20%3D%20MDL%20AND%20resolution%20%3D%20Unresolved%20AND%20Participants%20%3D%20currentUser%28%29%20AND%20updatedDate%20%3C%20-30d My old issues in triage] and you will receive notifications after 30 days of inactivity on such issues. See [[Tracker tips]] about how to subscribe to filter. Very often the reporter never follows up on their own issues and this is a good way to find such issues and ping reporter again or make a final decision about closing.

===Confirming the issue===

When you confirm that issue is indeed a bug or a reasonable improvement request that was not reported previously, make sure that the following is accurate:

* '''Security level.''' Security level must be set as soon as possible if the reported bug discloses vulnerability in Moodle that can be exploited to access information without appropriate level, create an attack on the site, embed XSS or forge a request. In some rare cases Improvements may be also marked as security
* '''Summary.''' Summary of the issue should clearly describe the problem or improvement area, rephrase such summaries as "Some improvements in xxx" or "Error in Moodle", etc.
* '''Issue Type.''' The following issue types are used in Moodle:
** Bug - represents an actual bug and should be fixed in all supported versions. Very often when reporter expects something to be better than it actually is they call it a bug when it's in fact an improvement.
** Improvement - improvement to existing functionality. If addressed, will be integrated in the following major release only
** New feature - completely new feature, also will not be applied to the released versions (unless implemented as a plugin and submitted to plugins directory)
** Task - usually created by developers themselves and can not be classified as Bug or Improvement, for example, adding automated tests, improving documentation, etc.
** Epic - created by HQ developers or component leads to collect together issues that represents parts of one project. META issues and sub-tasks should not be used any more
* '''Priority.''' Some reporters over-state an issue's priority. Some reporters don't know they can set a priority. Priority is used as one of the criteria when sorting issues in the backlog, so it should reflect the position of this issue comparing to the others. Usually Improvements have Minor or Major priority and Bugs can have any priority up to Blocker. Priority levels have specific criteria. Please see [https://docs.moodle.org/dev/Tracker_guide#When_editing_an_issue the Tracker guide]
* '''Component/s.''' Listing components correctly is important as they are the primary variable used for searching for issues, also adding a component automatically include the component lead as a watcher. Issue may have several components when needed
* '''Affects version.''' This field should include one or more released *and supported* versions of Moodle that are affected by the issue, with the following exceptions:
** The issue is a bug in code that is present in the Master branch only, in which case the next major version should be used. (The next major version should not be used in conjunction with previous released versions, this won't make sense later.)
** The issue is a new feature and is unrelated to any existing code in Moodle, in which case the 'Future dev' version should be used.
* '''Labels.'''
** Remove functionality tags that some reporters add as labels, only [https://docs.moodle.org/dev/Tracker_issue_labels standard] labels or partner-specific labels are used in Moodle
** Issues with proposed fixes are labelled ''patch'' so that they can be found easily and given attention. When this is the case, consider whether moving the issue to the 'Waiting for peer review' state in the workflow might be more appropriate
** Add ''addon_candidate'' label if the functionality can be implemented as a plugin;
** If you are component lead or HQ developer you may also add ''triaged'' label to indicate that triage process is completed. Use it only when the issue has actually been added to the backlog

''Note that "Fix version" is no longer used during triage. If you are in "moodle-triage" group, you can use the '''Triage screen''' to edit only aforementioned fields, see MDLSITE-3592.''

When commenting on the issue give more details on replication, environment or testing. Ask questions, add watchers, modify description if needed. Link to as many related issues as possible. Do everything that will make the issues scope more clear and attract opinions, discussions and patches.

Don't forget to show '''Gratitude and encouragement'''. After triaging many issues, it's easy to lose sight of the fact that the reporter has contributed their time and energy to report an issue for the benefit of the community.

It is easy to become defensive of Moodle if reports are seen as criticism (and sometimes reporters may use phrasing that suggests this), however the triagers response must always be one of sincere gratitude.

It is also important to encourage reporters to continue being involved with the issue after it is triaged. We must not give the sense that we are taking the issue ownership away from the reporter. Instead the reporter should be encouraged to discover the cause of the problem and present a solution; this is appropriate in an open-source project. It is amazing that such a challenge can lead to a sense of purpose for the reporters.

=== Following up on issues ===

Tracker is set up by default so as soon as you comment on any issue or edit it, you become an automatic watcher and any following change on the issue will be emailed to you.

If you have encouraged the reporter well, they may '''submit a patch''' or somebody else may do it. Make sure that the ''patch'' label is added or issue is sent to peer review. On the contrary, if ''patch'' label was added by somebody else but you clearly see that patch is far from ready, remove the label and leave a comment explaining it.

Users may also comment with additional details, screenshots, replicating instructions. It may happen that the issue gets re-evaluated and priority or summary changed.

=== Revisiting old issues ===

While searching the tracker you may come over issues that were reported long time ago but still remain open. Again, ask the following questions

* '''Is this still an issue?''' If it is not applicable any more either close it or comment about it on the issue and recommend to close. Very few tracker users actually have permission to close issues but the component lead or watchers will see your comment and revisit issue. Another good practice is to replace ''triaged'' label with ''triaging_in_progress'' and add a comment asking if the issue can be closed. If users confirm that it was resolved or nobody replies in 30 days, issue should be closed.
* '''Do affected versions need correction?''' If the issue is still applicable, make sure to add missing current affected versions or comment about it on the issue if you can't edit it.
* '''Does the issue have patch and if yes, is it still applicable?''' If the issue has patch that still works but ''patch'' label is missing, look through comments or history to see if the ''patch'' label was removed after reviewing the current patch. If you find that label was never added, do it yourself. On contrary if the issue has ''patch'' label but the patch is no longer applicable or not sufficient, remove the label.
* '''Are there any duplicating issues?''' When finding duplicates among the old issues it might not be obvious which issue to close as a duplicate. Usually we should leave the first reported issue but if the later issues have more watchers, better description, more votes, useful comments, attached patch, etc. you may decide to close the earlier issue and leave the later. Sometimes both issues have lots of watchers and they both remain open. In any case, always create links between duplicates or related issues.
* '''Does the issue have assignee who forgot about it or misleading status "Development in process"?''' Due to some [[Changes_to_issue_assignment|process changes]] in May 2013 some issues still have a real user in the ''Assignee'' field but this user actually does not work on the issue. Sometimes ''Assignee'' remains filled after failing peer review, sometimes developers simply forget that the issue was assigned to them. If you suspect that ''Assignee'' does not actually work on the issue, comment asking they about it and in some cases remove the ''Assignee'' completely. Allow somebody else to work on the issue without feeling that the issue is "taken". Please also note that for some time tracker had a restriction that ''Assignee'' could not be empty so you can find lots of issues assigned to ''moodle.com'' or ''Nobody''. Do not modify such issues as this creates unnecessary activity, emails to watchers and irrelevant change in the "Last update date".

=== Comments templates ===
====Redirecting someone with a support request====

Thanks for taking the time to create an issue. However, the problem you describe seems to be specific to your site, since I am unable to reproduce it on http://demo.moodle.net/. Thus I suggest you post asking for help in one of our community forums https://moodle.org/community/. 
I'm going to close this issue now. If you find that your problem can indeed be reproduced on http://demo.moodle.net/ or you have a suggestion for an improvement, please create a new issue providing as much detail as you can.

====Redirecting someone making a 'feature request' that is actually already possible====

Thank you for taking the time to request a new feature / suggest an improvement. However, what you ask for is already possible. I suggest you post asking for help about how to set up what you want in one of our community forums https://moodle.org/community/. 
I'm going to close this issue now.

====Refer the user to their instance administrators====
You have posted an issue on the Moodle Tracker, which relates to the improvement of Moodle code, not the Moodle site you are using at your institution. I recommend you contact the administrators of your Moodle site.

====Closing duplicate====

Thanks for your report. 
It seems you're not the only one to have come across this bug, as it's been reported previously - see MDL-xyz. I'm going to close this issue now so we can focus on MDL-xyz. Please watch, vote or comment on MDL-xyz if there is any additional information you can provide.


====Issue affects only unsupported versions====

Thanks for your report and apologies for it not being looked at before now. I tried but couldn't reproduce the problem in the latest stable version of Moodle. Thus, it seems it has been fixed as part of another issue and so I am closing this issue with resolution 'Cannot Reproduce'. If you find that the problem can indeed be reproduced in the latest stable version of Moodle (for example on the [Moodle sandbox demo|https://sandbox.moodledemo.net]) please create a new issue with clear steps to reproduce and link it to this one.

====Requesting more information====

Thanks for reporting this. 
Could you please add more information to your report such as replication instructions, error messages and screenshots. If you are able to suggest a workaround, that would be immediately helpful to others experiencing this problem. If you can determine the cause of the problem or even determine a solution, that will be very valuable.


====Request to correct translation====

Thanks for reporting this. 
<nowiki>The problem that you are describing refers to the translation in another language. Language string problems can be corrected by [Contributing a translation|https://docs.moodle.org/dev/Contributing_a_translation] or by contacting the language pack maintainer as listed in the [Translation credits|http://lang.moodle.org/local/amos/credits.php]. I'm going to close this issue because Moodle does not include translations in the standard download package.</nowiki> 


====Correction to English language strings====

Thanks for reporting this. 
Please note that English language string typo fixes and suggested improvements can be <nowiki>[contributed to the English (fixes) (en_fix) language pack|https://docs.moodle.org/dev/Improving_English_language_strings]</nowiki>


====Bug in contributed plugin (plugin can be identified)====

You have created an issue under MDL project in the tracker. However the problem that you are describing refers to contributed plugin xxx. 
<nowiki>I have moved your issue in the appropriate component of the CONTRIB project in tracker. I will also recommend you to leave a comment on the plugin page in the [Moodle plugins directory|https://moodle.org/plugins/]</nowiki>


====Triaging a bug report====
Thanks for reporting this issue.

You can help us resolve it as quickly as possible by:

* Adding further information in a comment or attaching a screenshot if requested by a developer investigating the issue.
* Posting the issue number in a moodle.org forum discussion about it.
* If you are able to provide a patch or links to your Git repository branch, please add a patch label so we will spot it.

====Triaging an improvement or new feature====

Thanks for suggesting an improvement or new feature. 
<nowiki>Please try [searching moodle.org|http://moodle.org/public/search/] to check whether someone else has had the same idea, then either join an existing discussion or start a new discussion in [Moodle in English|http://moodle.org/course/view.php?id=5]. Comment here with the link to the discussion, and mention this issue number in the discussion to encourage others to watch, vote or comment on it.</nowiki> 
<nowiki>If you can propose a code solution, please [create a patch|https://docs.moodle.org/dev/How_to_create_a_patch] or provide links to your Git repository branch, then add the patch label to the issue. </nowiki> 
<nowiki>For more ways to maximize the chance of your idea being implemented, see the guide [New feature ideas|https://docs.moodle.org/dev/New_feature_ideas].</nowiki>


==Creating a filter and gadget for triaging==

If you are a component lead you are responsible for triaging issues that involve your component. A good way to monitor newly created issues is to create a filter in the Tracker and add a gadget on your dashboard to show the results of the filter.

===Adding a filter===

In Tracker...
# Select ''Issues'' > ''Search for Issues''.
# Create a search for untriaged issues in your component, for example...
#: <syntaxhighlight lang="php">component in (Assignment) AND resolution = Unresolved AND (labels is EMPTY OR labels not in (triaged)) ORDER BY created DESC</syntaxhighlight>
# Run the search query by pressing ''Enter'' or clicking the magnifying glass icon to the right of the search box.
# When the search query results are displayed, click the ''Save as'' button.
# Save the search query with an appropriate name, like "Untriaged Assignment issues".

===Adding a filter in a gadget to your dashboard===

In Tracker...
# Click ''Dashboards'' > ''Dashboard for XXX'' (where ''XXX'' is your name).
# Click ''+ Add Gadget''.
# Find the ''Filter Results'' gadget.
# Click ''Add it Now''.
# Click ''Finished''.
# In the ''Saved Filter'' input, search for and select your newly created filter.
# Click ''Save''.

The most recent untriaged issues should appear in reverse-date order.

==Triaging priorities and the Triaging Dashboard==

The following are the priorities for ordering issues to be triaged that are reflected on the [http://tracker.moodle.org/secure/Dashboard.jspa?selectPageId=11153 Triaging dashboard].

# Security issues - should always be reduced to 0
# High-priority issue - aim for blockers and critical issues to be reduced to 0
# Partner issues - aim for partner issues to be reduced to 0
# Patched issues - aim to triage as soon as possible
# Developer-reported issues (HQ and non-HQ) - should be quick to triage
# Recent community bugs - should be triaged last-in-first-out

==See also==

*[[Tracker guide]]
*[[Process]]
*[[Talk:Bug triage]]
*[[Tracker tips]]

[[Category:Processes]]
[[Category:Quality Assurance]]
[[Category:Tracker]]

QA testing

2021-08-11T14:54:19Z

Moodlebot: Text replacement - "</code>" to "</syntaxhighlight>"

'''Quality Assurance''' tests look at the functionality of Moodle from a user's point of view.

Real users systematically try each feature in Moodle and test that it works in the current version of the Moodle code. These tests are repeated in series of cycles, usually 4 weeks before a major release, once all major features have landed.

'''QA testing latest''': ''A 100% pass rate was obtained in Moodle 3.11 QA testing. Many thanks to all our [[Testing credits|QA testers]].''
==Getting involved==

Would you like to help with QA testing? If so, please make sure you have created an account in the [[Tracker_introduction|Moodle tracker]] and you're subscribed to the [https://moodle.org/mod/forum/view.php?id=56 Testing and QA forum] in order to receive QA testing news updates.

==Running tests==

# Go to the [https://tracker.moodle.org/secure/Dashboard.jspa?selectPageId=11454 Moodle QA testing dashboard] and choose a test from the list of current QA cycle open issues. When viewing a test, if you wish, you can click the 'Assign to me' link on the right, so that nobody else chooses the same test to run. (If you then find you are unable to run the test, you can click the Assign button and set the assignee as 'Unassigned'.) Please note:
#* Only assign an issue to yourself which no one else is testing (Assignee = Unassigned).
#* Only assign one issue at a time unless you plan to test a number of related issues within the next 24 hours. In other words, don't assign several issues to yourself then do nothing for several days. ;-)
#* The label ''test_server_required'' indicates issues that can't be tested on the QA testing site. The label ''credentials_required'' indicates that credentials such as an OAuth 2 service client ID and secret are required.
# Using either the [https://qa.moodledemo.net/ Moodle QA Testing Site] or your own test site running the latest Moodle 4.0dev (available from Git on the integration/MOODLE_400_STABLE branch ''<nowiki>git://git.moodle.org/integration.git</nowiki>'') with [[:en:Debugging|debugging]] set to developer, perform each of the steps listed in the test.
# ''Please attach screenshots of the steps where you verify or check something.''
# If it makes sense, please test using the currently supported themes, Boost and Classic.
# Choose an appropriate workflow action:
#* ''Pass'' - Test runs perfectly. Add comment such as feedback about a new feature, browsers used for testing (if applicable; example: "This test passes on Q&A site with Teacher role using Boost theme"), or simply "This test passes - yippee!"
#* ''Fail'' - Something doesn't work, or you obtain debugging messages. Add comment describing the step that doesn't work. If in doubt whether to pass a test, give it a fail and add a comment describing your doubts.
#* ''Obsolete'' - Test is no longer relevant in the current Moodle version. Add comment explaining why.

If you notice that the test description is out-of-date, add a comment mentioning that it needs updating. Alternatively, if you'd like to help with updating the test yourself, see below.

==Any questions?==

If there is anything you are unsure of, such as whether to mark a test as failed, or you have any other questions, please ask in one of the following places:

* [https://t.me/moodleqa Moodle QA Telegram chat room] *new*
* [https://moodle.org/mod/forum/view.php?id=56 Testing and QA forum]

==Moodle QA Testing Site==

The [https://qa.moodledemo.net/ Moodle QA Testing Site] is updated daily at around 13:00 UTC with the latest bug fixes to enable you to re-run QA tests.

To prevent the site being used for sending spam, no emails are sent from it. Thus, tests involving email cannot be run using the Moodle QA Testing Site. (If such tests are attempted, an email debug message is displayed. This is not a bug but rather expected behaviour.)

Teacher and student accounts are provided. Please contact [https://moodle.org/user/profile.php?id=24152&course=1 Helen] if you would like admin or manager access to the Moodle QA Testing Site for running certain tests.

==<div id="failedTests">Failed tests</div>==

So you ran a test and it failed? Congratulations on finding a bug! Please do the following.

# Click the Fail button at the top of the page.
# Add a comment to the QA test stating that there was a problem and that you will report it as a Moodle bug.
# Note the MDLQA number; it will be something like <nowiki>MDLQA-448</nowiki>.
# Try searching for whether the bug has been reported previously, and if not create a new issue for it (as described in [[Tracker introduction]]).
# In the new Moodle (MDL) issue select 'Link' from the 'More actions' dropdown menu. [[Image:LinkIssue.png|150px|Linking to the QA issue in the tracker]]
# Link to the QA test by selecting 'blocks' as the link type, entering the MDLQA number that you noted earlier, and optionally adding a comment. [[Image:LinkDetails.png|150px|Adding details for a link to the QA issue]]
# Give the issue the label 'mdlqa'.
# (Optional) Add yourself as a watcher to the MDL issue so that you receive email notification when the issue is fixed.
# When the MDL issue is fixed, hopefully within a day or two, the QA test can be reset and can then be run again.

==Resetting tests==

''Note for integrators:''

After integrating a fix,

# Reset the MDLQA test, adding a comment.
# Remove the 'mdlqa' label from the MDL issue.
# If the issue doesn't have testing instructions, pass it with message "Will be tested by MDLQA-XXXX".

The tester will then receive email notification that the bug is fixed and will hopefully decide to run the test again soon.

==Fixing existing bugs==

At the beginning of the QA cycle, all bugs identified (both new and existing) are investigated promptly and hopefully fixed.

When we are close to the scheduled release date (1-2 weeks prior), developers must focus on fixing new bugs (which affect the upcoming release version) only.

Thus, at this point in the QA cycle, any bugs which also affect existing versions of Moodle are labelled qa_identified (and the label mdlqa removed) for investigation after the release.

==Testing tips==

When entering text into a form, try things like:

* <code>&</syntaxhighlight> (ampersand), <code>></syntaxhighlight> (greater than) or <code><</syntaxhighlight> (less than) e.g. <code>x < 1 && x > 0</syntaxhighlight>
* <code>0</syntaxhighlight> (the single digit 0)
* <code>'</syntaxhighlight> (single quote) e.g. <code>Fergal.O'Brien@example.com</syntaxhighlight>
* special characters e.g. <code>café</syntaxhighlight> or <code>囲碁</syntaxhighlight>
* very long strings
* different languages, such as a RTL language

==New QA tests required==

''Note for developers:''

If an issue fix cannot be covered by automated tests,

# Add the label 'qa_test_required' to the issue.
# Add a comment explaining why it can't be covered by automated tests and suggesting which steps of the testing instructions should be included in a QA test e.g. steps 6-10 or all steps.

QA tests will then be written and included in the next QA cycle. For issues with long testing instructions, several QA tests will be written to cover the issue. If appropriate, activities etc. will be set up on the [https://qa.moodledemo.net/ Moodle QA Testing Site] to enable the issue to be easily tested in future.

Similarly, for new features and improvements which would benefit from exploratory testing,

# Add the label 'qa_test_required' to the issue.
# Add a comment mentioning that exploratory testing is required.

Exploratory QA tests will then be written and included in the next QA cycle and then removed.

==Updating tests==

QA tests often become out-of-date due to new developments. If you would like to help with updating tests, you'll need to be a member of the test writers group in the Tracker. Please contact Helen about being added.

To update a QA test:

# Search for the master copy of the test - with affects version as 'Master copy' and MDLQA-1 as parent.
# Edit the test description.
# Optional: Add a comment describing your edit.

==Writing new tests==

Would you like to help with writing new QA tests? If so, as for updating tests, you'll need to be a member of the test writers group in the Tracker. Please contact Helen about being added.

To create a new QA test:

# Choose an issue from the [https://tracker.moodle.org/issues/?jql=labels%20%3D%20qa_test_required%20AND%20status%20%3D%20Closed closed qa_test_required-labelled issues]
# Do a quick search of MDLQA-1 to check if there is an existing test which can be updated
# If not, create a sub-task of MDLQA-1
# Select 'Original' as affected version
# Select appropriate components
# Set assignee as unassigned
# Write the test (usually between 3 and 10 steps). It's a good idea to try doing the steps yourself as you write the test.
# Add the label ''new''
# For tests which can’t be run on the QA site, label ''test_server_required''. For OAuth 2 tests and any other tests which require a client ID or secret to be entered, label ''credentials_required''.
# For issues which specifically mention in the testing instructions to test in different browsers, use the phrase "Test in as many browsers as possible and mention in a comment which ones you’ve used."
# For an exploratory test, begin the test description with "This is an exploratory test of a new feature or improvement, so please feel free to try anything you like and not just the test steps!"
# For a test requiring admin access which can be run on the QA site, add:
This test requires admin access. If you would like to use the [QA testing site|https://qa.moodledemo.net/] for running it, please see the [QA testing guide|https://docs.moodle.org/dev/QA_testing] for details of how to request admin access. Begin just after the hourly reset to give yourself plenty of time to complete the test!

13. Go to the MDL issue and create a ‘has a QA test’ link to the new QA test, adding a comment “Thanks for this improvement which is now covered by the QA test MDLQA....”, and remove the qa_test_required label. ''Make sure that all QA tests are linked back to a corresponding MDL issue.''

New tests will be included in the next QA cycle.

==Feedback==

Feedback on all aspects of our QA testing process is welcome. If you have any questions or comments, please post in the [https://moodle.org/mod/forum/view.php?id=56 Testing and QA forum].

==See also==

* [https://tracker.moodle.org/secure/Dashboard.jspa?selectPageId=11454 QA testing dashboard]
* [[Testing credits]]
* [[MDLQA-features]]
* [https://moodle.org/mod/forum/discuss.php?d=351302 Useful tips for QA testing]

Comments on tests from previous QA cycles:
* [https://tracker.moodle.org/browse/MDLQA-150 Moodle 2.0 QA Cycle 1]
* [https://tracker.moodle.org/browse/MDLQA-328 Moodle 2.0 QA Cycle 2]
* [https://tracker.moodle.org/browse/MDLQA-540 Moodle 2.0.2 QA]
* [https://tracker.moodle.org/browse/MDLQA-944 Moodle 2.1 QA Cycle 1]
* [https://tracker.moodle.org/browse/MDLQA-1190 Moodle 2.2 QA]
* [https://tracker.moodle.org/browse/MDLQA-1814 Moodle 2.3 QA]
* [https://tracker.moodle.org/browse/MDLQA-4602 Moodle 2.4 QA]
* [https://tracker.moodle.org/browse/MDLQA-5267 Moodle 2.5 QA]
* [https://tracker.moodle.org/browse/MDLQA-5740 Moodle 2.6 QA]
* [https://tracker.moodle.org/browse/MDLQA-6693 Moodle 2.7 QA]
* [https://tracker.moodle.org/browse/MDLQA-7170 Moodle 2.8 QA]
* [https://tracker.moodle.org/browse/MDLQA-7660 Moodle 2.9 QA]
* [https://tracker.moodle.org/browse/MDLQA-8205 Moodle 3.0 QA]
* [https://tracker.moodle.org/browse/MDLQA-9267 Moodle 3.1 QA]
* [https://tracker.moodle.org/browse/MDLQA-9827 Moodle 3.2 QA]
* [https://tracker.moodle.org/browse/MDLQA-10403 Moodle 3.3 QA]
* [https://tracker.moodle.org/browse/MDLQA-10999 Moodle 3.4 QA]
* [https://tracker.moodle.org/browse/MDLQA-11698 Moodle 3.5 QA]
* [https://tracker.moodle.org/browse/MDLQA-12282 Moodle 3.6 QA]
* [https://tracker.moodle.org/browse/MDLQA-12911 Moodle 3.7 QA]
* [https://tracker.moodle.org/browse/MDLQA-13517 Moodle 3.8 QA]
* [https://tracker.moodle.org/browse/MDLQA-14131 Moodle 3.9 QA]
* [https://tracker.moodle.org/browse/MDLQA-14813 Moodle 3.10 QA]
* [https://tracker.moodle.org/browse/MDLQA-15457 Moodle 3.11 QA]

[[Category:Quality Assurance]]

Languages subsystem improvements 2.0

2021-08-11T14:54:19Z

Moodlebot: Text replacement - "</code>" to "</syntaxhighlight>"

{{Infobox Project
|name = Languages subsystem improvements
|state = Complete
|tracker = MDL-18797 MDL-15252
|discussion = [http://moodle.org/mod/forum/discuss.php?d=118707]
|assignee = [[User:David Mudrak|David Mudrak]]
}}
{{Moodle 2.0}}

{{Warning|This page was once used as an initial specification of the project. Only parts of it were finally implemented. It is kept for archive purposes only.}}

This is a specification of changes to the language strings processing in Moodle 2.0 and 2.1. You should start looking at the [http://www.mindmeister.com/41382366/proposed-changes-for-moodle-2-x-languages-machinery overview of proposed changes] mindmap.

== Current issues ==

Why the changes in the current tools and process are needed:

; String files are not branched : We must keep all strings from all branches in place for backwards compatibility and we are unable to easily clean up language packs. Some say the branching and merging is too much work for our translators (see MDL-15252).
; Plural forms, gender forms and other grammar : We are unable to handle plurals at all. For example, handling [http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html plural forms in gettext] is traditional, well tested and robust way (see MDL-4790). MDL-12433 by Sam Marshall shows alternative approach based on logical expressions.
; Strings can't be modified : It is difficult to notify translators that some string was modified (expanded, fixed, changed) - as in [http://git.moodle.org/gw?p=moodle.git;a=commit;h=d033b1288713625a733ce5fcbce5e7b5a1f6d5d1 this case], for example. The current work around is the policy of adding another string with the same suffixed name (like 'license2'). It would be nice if such strings were tagged/highlighted in the translation UI.
; We do not use standard formats : Translators can't use specialized tools for translation (PO/gettext editors, community translation portals). Also, I (David) am not aware of any benchmarking showing the performance differences between out native $string[] format compared to, for example, standard .po format.
; More syntax checks are required : So the translators do not brake Moodle functionality (see MDL-12433)
; Language packs are PHP code, but stored in moodledata : This increases the severity of some security exploits. It means that any exploit that lets you write files to an arbitrary location in moodledata suddenly lets you execute arbitrary PHP code on the server. On the other hand, it would be nice to be able to allow complex logic when evaluating dynamic strings (ie such containing $a param/params).
; Right-to-left languages : There are problems reported in RTL languages when using online tools (including the our current one) which lead to putting placeholders like a$ and a$->lastname into the string definition.

== Goals ==

# Fix all the issues listed above
# Do not reinvent the wheel
# Keep "do one thing and do it well" principle
# Keep it simple and stupid.
# Have the translation process as simple as possible - translators are not geeks
# Make simple things easy and hard things possible
# Make most of this available for Moodle 2.0

== Key design questions ==

When working on the specification, these were the key questions to keep in mind:

; What is the data structure for storing the master copies of the lang packs : At the moment, strings are defined in plain PHP associative arrays, editable via translation UI or directly. These arrays are stored in PHP files in Moodle CVS. We are going to change it. According to the original Petr Skoda's proposal, the primary place for keeping all translated strings will be a central database at one of moodle.org servers. Together with the translation itself, usefule meta-data are kept in the database: the timestamp of the last modifications, links to the revision of the English string that the translation is based on, the author name, proposed alternatives, comments etc (see rosetta translation tool at launchpad for the example of possible metadata).
; What is the UI for translators, what are the processes of contributing and how the translations are redistributed to Moodle sites : Thanks to storing all strings in a database, we will be able to produce their list in various standardised formats (like PO or XLIFF). Therefore, the translators will not be forced to use the only one possible tool but can use their favourite advanced tool with its own translation memory, connected with dictionaries, i18n portals etc. Our central strings repository will support data export and import from/into various formats.
; What is the data structure that get_string() uses at runtime : This is just a performance optimization (implementation detail), should be independent on the native format that humans work with so it could be modified anytime in the future. For example, see the system proposed by Tim based on calling class methods (inspired by Perl's Maketext).
; What is the format of a lang string, and how are placeholders substituted : It is strongly tied together with the runtime format, it can be changed any time. On the other hand, both the UI and storage format must support it.

== Use cases ==

# Developers add new strings to the code and commit their work into CVS (core or contrib)
# Developers can add a comment to the string, eg. "this string is used for ..."
# Developers add new string and link it with a current one with an explanation eg "this string replaces ...". Such links are available to translators and help them to decide the correct translation.
# Developers moves the string from one component (like enrol.php) into another (like enrol_manual.php). The current translations are re-used.
# Developers change the string identificator, for example from configfoobar to foobar_desc.
# Translators translate strings on several Moodle branches and do not need to worry about branching, commiting and merging
# Translators can see the list of untranslated strings and translate them
# Translators can see the list of outdated translated strings (aka English string was changed) and update the translation
# Admins can locally modify the language pack for their site
# Community members can propose alternative translations. They are reviewed by the lang pack maintainer and may be approved.

== Research ==

This is the list of projects, resources and tools that were explored before writing this spec

* [http://search.cpan.org/~ferreira/Locale-Maketext-1.13_82/lib/Locale/Maketext/TPJ13.pod Great CPAN article about software localization]. Plain string based lexicon is not enough. Strings can be translated by functions only. "A phrase is a function; a phrasebook is a bunch of functions."
* [http://en.wikipedia.org/wiki/XLIFF XLIFF] - XML Localization Interchange File Format
* [http://translate.sourceforge.net/wiki/virtaal/index Virtaal] - promising, we could have XLIFF <-> .php conversion
* [http://launchpad.net/+tour/translation Launchpad] - translation portal used by Ubuntu and many other projects. Would require BSD licensing, therefore IMO not suitable as we could not import our current GPL'ed translation. Seems to be quite slow during the process.
* [http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html Plural forms in gettext]
* [http://framework.zend.com/manual/en/zend.translate.html Zend_Translate reference guide]
* MDL-12433 - Sam Marshal's proposal
* MediaWiki approach: [http://www.mediawiki.org/wiki/Manual:$wgGrammarForms Grammar forms] and plurals: <code>{{plural:1|is|are}} {{plural:2|is|are}}</syntaxhighlight> (Example of how mediawiki outputs the correct given pluralization form depending on the count. Plural transformations are used for languages like Russian based on "count mod 10").

== Functional proposals ==

=== Overall strings processing flow ===

(Follow the attached UML flow diagram) [[Image:languages20_overview1.png|thumb|right|UML: Overall string processing flow]]

* All string definitions are kept in a central database togeteher with other all meta-data (branch, where does the string come from, what was its history etc.). Officially maintained language packs are referred to as ''master'' in this proposal. Every language pack can have its ''parent'' defined. The English language pack can be seen as the greatest common parent of all language packs.
* During upgrade or on demand, the relevant branch of master language packs are fetched (downloaded) automatically from the central database. Together with the selected language, all its parents, grandparent, great-grandparents, ... etc are downloaded, too.
* Administrators can keep local modifications (customizations) of any master pack. We call them ''local'' language packs.
* Immediately after upgrade (or again, on demand), the string definitions are merged from all available sources. The merge logic is so that the sources for any given string are evaluated in the order like: fr_ca_local, fr_ca, fr_local, fr, en_local, en. Strings are merged for the performance reasons so that the searching for the string to use (local, parent, master, English etc.) is done just once and we do not need to load all possible sources on runtime. After the merge, we have a single place to look for the string definition for every installed language. By default, the location for these merged strings will be $CFG->dataroot/cache/lang/XX/component.php where XX is the language code (fr_ca, fr, en in this example). The benefit is that get_string() can rely on always having the string defined in this file, no other seeking and I/O is needed in runtime.
* Together with the merge, strings are compiled into a runtime format that may be optimised in the future. Humans do not modify the compiled format. Strings must be re-merged and re-compiled after any update of master or local packs. During the compilation, syntax checks are performed.
* The runtime format we will start with will be very similar with the current one. Strings are defined as array elements indexed by the string identifier. The arrays are defined in separate files for every module. We can, however, modify this in the future. For example, we can divide string definitions into files not by the module name but by the real usage frequency. Strings that are used very often (like at every page) would go into common file which can be loaded during bootstrap. This would reduce memory usage and number of I/O operations.
* There will be a way how to let get_string() call a PHP function/method to actually return the translated string instead of a static string definition. This will allow advanced translators to deal with many grammar issues they have in their languages (notably singular v plural forms).

=== Naming and locations ===

* Languages will be reffered to as "en", "cs", "en_us" or "fr_local" etc. Directories will be renamed.
* Downloaded lang packs are stored in $CFG->langpacks, which is by default $CFG->datadir/lang. Paranoid admins can change this to a different location that is normally read-only for the web server. Then they will manually switch to read-write when they are performing an upgrade, doing lang editing, or installing a lang pack. The UI should therefore check whether $CFG->langpacks is writable before starting any of these operations, and explain the situation to admins if it is not.
* After mergin and compiling, the strings in runtime format are stored in $CFG->dataroot/cache/lang/ (see above).
* All core plugins will have their language files in their own scope as the contrib plugins have. So for example workshop strings will be defined in '/mod/workshop/lang/en/workshop.php' instead of legacy '/lang/en_utf8/workshop.php'

=== HTML help files replaced with ordinary strings ===

Help should consist of a paragraph or two of a static HTML only, the rest goes to wiki. We will drop help files indices (index of all help files) as well as other dynamically generated helps in favour of wiki. This will make the translation easier as we do not need to have other tools to translate help files.

Help strings are kept together with other workshop strings as in <code>$string['intro'] = 'Workshop intro'; $string['intro_help'] = 'This is the ...';</syntaxhighlight>. It allows to keep the string and their help together which helps translators to keep translation consistency.

See [[Help strings]] for further information.

=== Other changes ===

* The only valid placeholder in runtime format is <code>{$a}</syntaxhighlight> for strings and numbers and <code>{$a->foobar}</syntaxhighlight> for objects MDL-18841.
* Around 90% of our strings do not contain any placeholder and they will be immediately returned by get_string().
* If the string contains one or more placeholders, they are replaced with their eval()-uated result. We can safely eval() the whole string definition because the string compiler makes sure that the placeholders are the only executable/evaluable code. All other malicious code and $variables are properly quoted/escaped/htmlentitled.
* Valid format of string identifier must be defined. These identifiers may be used as associative array keys (as in <code>$string['identifier']</syntaxhighlight>), function names, HTML form field names, file names etc. No characters like '*' can be used (as happened in MDL-21375).
* Some string identifiers are not hardcoded (explicitly referenced) in the code but computed, eg. <code>get_string('level' . $level, 'arcade')</syntaxhighlight> with strings 'level1', 'level2', 'level3' etc being defined. It is difficult to automatically search for the usage of such strings. Therefore, I (David) propose the following guideline (rule): String identifiers must follow our convention for naming $variables: single lowercase word, no underscore. The colon (:) sign can be used only in strings with the names of capabilities and nowhere else. The minus sign (-) can be used only in string identifiers witch are partially computed, as in <code>get_string('region-' . $regionid, 'theme_example')</syntaxhighlight> so that is a sign that we should be careful when trying to find an usage of such string in the code. The underscore is reserved for special _help and _desc suffixes.

=== Central web-based translation tool ===

See [[Automated_Manipulation_of_Strings_2.0]]

== Implementation proposals ==

Read [http://moodle.org/mod/forum/discuss.php?d=118707#p542197 Petr's proposal] to store strings in one central database and to disable direct commits. That is roughly valid with the exception that the "no change meaning" rule is not forced. AMOS is able to track changes and inform translators that their translation is outdated. So we will be able to fix/update/extend English string as needed. Together with branching, this will lead to a nice "reduced" packs without redundancy.

=== Translation tools and the process ===

See MDL-15252 (Cleanup of English language pack) and the discussion at http://moodle.org/mod/forum/discuss.php?d=118707 for Koen's proposition. Branching issue, the translation process and other aspects discussed there.

Some notes:

From Martin in Dev chat: ''if you want crazy ideas, how about get_string returns some special tags and those tags get converted to ajax on the GUI so that translators can translate directly in the main Moodle GUI?''

What a cool idea. Could be a special mode you have to turn on in the admin screens. Perhaps even if you turned this mode on, it would still only be active for people with certain roles, or perhaps when it was turned on, it would have to apply to all roles, so that you could edit strings for not-logged-in users. Anyway, when this mode was on, it would:

# Adds Language editing around each string on the page - to use one example.
# $PAGE->requires->js an extra JS file that adds an on-click handler to all such spans, so that when you click on it, it pops up the language editing UI in a YUI dialogue.

:: [[User:David Mudrak|David Mudrak]] 14:07, 23 November 2009 (UTC): the solution based on wrapping around every string was already considered and dropped. It may badly break XHTML as the string itself may appear as a value of an HTML tag's attribute: <code><img title=". We are unable to say the scope where the string will appear.
:: David's contra-proposal: get_string() could track all strings used at the current page and the AJAX form to edit them all could be rendered before the footer(). Or 'Edit system text on this page' link would appear there.

=== Getting the history of strings into database ===

Source code management systems can't show us how the given string evolved during the time. Translators on the other hand need to know "personal history" of any given string, each with the author of the change, date, comment etc. String timeline will be populated from DB. To let it work, we will need to load all the strings history into DB. That can be done using our git mirror. This conversion is done:

# Regularly for the master English strings that are part of Moodle source code. David already has a prototype of script to track commits into languages files and updates the database.
# Once for all other languages. When we have the new translation portal prepared, we will stop supporting direct CVS commits into languages. The history of all commits into all lang packs will be transferred into the database and further translations will be recorded there.

David is writing these migration script as a part of his [[Languages/AMOS]] tool.

== Design decisions and voting ==

* MDL-21690 Central master database of all strings and their translations
* MDL-21635 Decide how to implement information in langconfig.php in AMOS
* MDL-21693 Drop _utf8 suffix from language codes and folder names
* MDL-21694 Move language files to the plugin space
* MDL-21695 Replace built-in HTML help files with proper strings

== See also ==
* [http://live.gnome.org/TranslationProject/GitHowTo How to use Git for GNOME translators]
* [http://translate.sourceforge.net/wiki/ Nice site with tools, localisation problems and alternatives...]
* [[Languages:Tim's crazy proposal based on maketext]]

[[Category:Language]]

How to fix gradebook issues

2021-08-11T14:54:17Z

Moodlebot: Text replacement - "</code>" to "</syntaxhighlight>"

==How to fix Grade book issues==

There has been a policy decision that any fixes to the grade book must not result in any changes to grades. Some fixes may result in grades being changed and in these situations we need to freeze the grade book and let the teacher / admin / higher power agree to applying the change.

For future fixes to the grade book we will be putting revision numbers and nested code into the grade book libraries.

===Fixing the issue===

Choose a freeze number that is greater than the current build number but will be less than the next build number.

When making changes wrap your code in an if statement.

example:
<syntaxhighlight lang="php">
$gradebookcalculationsfreeze = get_config('core', 'gradebook_calculations_freeze_' . $courseid);
// Stick with the original code if the grade book is frozen.
if ($gradebookcalculationsfreeze && (int)$gradebookcalculationsfreeze <= {your code freeze number}) {
{original code goes here}
} else {
{new fixed code goes here}
}
</syntaxhighlight>
Enter in details about your fix at https://docs.moodle.org/29/en/Gradebook_calculation_changes

===Upgrade code===

Code will be required to determine if the site being upgraded is affected. If so then it should be flagged to be frozen.

example (lib/db/upgrade.php):
<syntaxhighlight lang="php">
if ($oldversion < 2015062500.01) {
// MDL-48239. Changed calculated grade items so that the maximum and minimum grade can be set.

// If the changes are accepted and a regrade is done on the gradebook then some grades may change significantly.
// This is here to freeze the gradebook in affected courses.

// This script is included in each major version upgrade process so make sure we don't run it twice.
if (empty($CFG->upgrade_calculatedgradeitemsignored)) {
upgrade_calculated_grade_items();

// To skip running the same script on the upgrade to the next major release.
set_config('upgrade_calculatedgradeitemsignored', 1);
}

// Main savepoint reached.
upgrade_main_savepoint(true, 2015062500.01);
}
</syntaxhighlight>
The code for doing this check should be located in lib/db/upgradelib.php so that it can also be run when a course is being restored.

===New installations===

Make sure to not run the upgrade step with the new installation

example (lib/db/install.php:: xmldb_main_install() line 135):
<syntaxhighlight lang="php">
'upgrade_calculatedgradeitemsignored' => 1, // New installs should not run this upgrade step.
</syntaxhighlight>

===Restoration code===

Code should be generated so that a regrading of the gradebook will fix the problem. Any solution that requires direct alteration of the grades in the database will result in an extremely complex set of restore code.

example (backup/moodle2/restore_stepslib.php):
<syntaxhighlight lang="php">
// Calculated grade items need recalculating for backups made between 2.8 release (20141110) and the fix release (20150627).
if (!$gradebookcalculationsfreeze && $backupbuild >= 20141110 && $backupbuild < 20150627) {
require_once($CFG->libdir . '/db/upgradelib.php');
upgrade_calculated_grade_items($this->get_courseid());
}
</syntaxhighlight>
===Tests===

Create a behat test to make sure that when the gradebook is frozen that grades are not changed.
Create a behat test to make sure that when the gradebook is not frozen that the issue is solved.

Create unit tests to check functions in the upgradelib.php file.

Global search (GSoC2013)

2021-08-11T14:54:17Z

Moodlebot: Text replacement - "</code>" to "</syntaxhighlight>"

{{obsolete}}
{{Infobox Project
|name = Global search
|state = Coding period
|tracker = MDL-31989
|discussion = [https://moodle.org/mod/forum/discuss.php?d=227805 Writing Moodle's Global Search]
|assignee = [https://moodle.org/user/view.php?id=1565904&course=5 Prateek Sachan]
}}

GSOC
 '13


== Introduction ==
Global Search will have the feature of searching keywords within the entire Moodle site across modules keeping the security intact having full-text advance search capabilities.
*It will display results based on relevance weightage.
*Security will be preserved throughout the search.
*Search Modules will enable chosen search engine integration with ease. Admins will have the option for selecting the modules that could be made "searchable"
*It will include keywords from other files types (like PDFs, PPTs, HTML content and others).
*Following are the features that I'm considering in implementing in the first version of Global Search:
# Groupings of boolean operators:<code>AND</syntaxhighlight>, <code>OR</syntaxhighlight>, <code>NOT</syntaxhighlight>. Eg.: <code>("query1" AND "query2") OR ("query3" NOT "query4")</syntaxhighlight>
# Highlighting: All matched keywords will be highlighted. For long content, only a short part will be displayed alongwith the highlighted keyword.
# Searching for phrases. Results with matched phrase will have higher priority and hence will be shown higher in the results.
# Wildcard (<code>*</syntaxhighlight>) (<code>?</syntaxhighlight>) feature.
# Stemming. Eg.: <code>bag</syntaxhighlight> will return results both from <code>bag</syntaxhighlight> and <code>bags</syntaxhighlight>
# Proximity Searches:
:*"mood"~2 returns "moodle". (2 alphabets away from the searched term).
:*"moodle australia"~3 returns results containing "moodle hq at perth australia" (the queried terms were within 3 words of each other)

== Requirements ==
*Moodle 2.5 and above.
*PHP Solr extension.

==Design==
'''Adding a Global Search Block'''

[[File:Add_Global_Search_Block.png]]

'''Search through Global Search Block'''

[[File:Global_Search_Block.png]]

'''Global Search Results UI'''

[[File:Global_Search_Results_UI.png|900px]]

'''Global Search Admin Solr settings'''

[[File:Global_Search_Admin_Solr_Settings.png|900px]]

'''Global Search Admin Modules Activation'''

[[File:Global_Search_Admin_Module_Activation.png|900px]]

'''Global Search Admin Indexing Statistics'''

[[File:Global_Search_Admin_Indexing_Statistics.png|900px]]

== Admin Controls ==
These controls appear under Site Administration > Global Search. (Please refer the screenshots above).
=== Search Engine ===
This will enable you to choose your preferred Search Engine. Currently, Global Search only supports Apache Solr.
=== Solr Settings ===
This section lists down the various server connection settings that you'll need to configure for your server.
=== Activated Modules ===
This section lists down the modules that are enabled in Global Search for indexing and searching of the content within them. You may activate/deactivate modules.
=== Indexing Statistics ===
*This lists down the indexing statistics of Global Search.
*It also gives you the control for deleting index from specific modules or deleting the entire index in one go. (Deleting "Entire Index" deletes the entire Solr index irrespective of whether a module is activated/deactivated).
*The content will have to be re-indexed through cron.

== Installing PHP Solr extension==
=== UNIX ===
*You may download pecl-php-solr extension version <code>1.0.3-alpha</syntaxhighlight> by <code>git clone https://github.com/lukaszkujawa/php-pecl-solr.git</syntaxhighlight> or official versions <code><=1.0.2</syntaxhighlight> from http://pecl.php.net/package/solr. (Extract the contents in a directory)
*Install the extension dependencies by executing <code>apt-get install libxml2-dev libcurl4-openssl-dev libpcre3-dev</syntaxhighlight>
*Restart apache server. <code>sudo service apache2 restart</syntaxhighlight>
*Assuming you cloned or downloaded the extension in a directory, you'll have to compile the downloaded extension.
*<code>cd /your-downloaded-or-cloned-php-solr-extension-directory/</syntaxhighlight>
*<code>phpize</syntaxhighlight>
**This a shell script used to prepare the build environment for a php extension to be compiled. If you don't have <code>phpize</syntaxhighlight>, you can install it by executing <code>sudo apt-get install php5-dev</syntaxhighlight>
<code>sudo ./configure</syntaxhighlight>
*sudo make
*sudo make install

The above procedure will compile and install it in the <code>extension_dir</syntaxhighlight> directory in the <code>php.ini</syntaxhighlight> file. To enable, the installed extension, you could follow any of the following two steps:

1. Navigate to the directory <code>/etc/php5/conf.d</syntaxhighlight> and create a new <code>solr.ini</syntaxhighlight> file with the following line:
extension=solr.so

OR

2. Open your <code>php.ini</syntaxhighlight> file and include the following line:
extension=solr.so

You may follow any of the above two steps. You will need to restart your apache server after that by executing <code>sudo service apache2 restart</syntaxhighlight>

You can now view the '''solr''' extension details by clicking '''PHP info''' from Site administration > Server in browser or <code>php -m</syntaxhighlight> in Terminal (<code>Ctrl+Alt+T</syntaxhighlight>)

=== OSX using macports ===
This method provides an easy install of php solr extension without any downloads.(php solr extension version: <code><=1.0.2</syntaxhighlight>)
- sudo port install apache-solr4
- sudo port install php54-solr

you can choose your relevant available versions @ http://www.macports.org/ports.php?by=name&substr=solr

== Setting up Global Search for Moodle ==

After installing the php-pecl-solr extension, users will have to download the required [http://lucene.apache.org/solr/ Apache Solr] release (version 4.x for solr-php extension <code>1.0.3-alpha</syntaxhighlight> or 3.x for solr-php extension version <code><=1.0.2</syntaxhighlight>), unzip it and keep it in an external directory of Moodle.

Users will have to replace <code>solconfig.xml</syntaxhighlight> and <code>schema.xml</syntaxhighlight> inside the downloaded directory <code>example/solr/collection1/conf/</syntaxhighlight> with the ones that Global Search will provide in <code>/search/solr/conf/</syntaxhighlight> directory.

Once the files have been copied and replaced, users will have to start the java jetty server <code>start.jar</syntaxhighlight> located in <code>/example/</syntaxhighlight> directory by executing <code>java -jar start.jar</syntaxhighlight>. For the production setup you may prefert to [http://jmuras.com/blog/2012/setup-solr-4-tomcat-ubuntu-server-12-04-lts run solr on tomcat 6 or 7] and Ubuntu server.

Admins will then have to Enable Global Search in Site Administration > Plugins > Global Search > Manage Global Search

== Searchable content in Global Search==
Following are the modules/resources covered so far in Global Search. I'll be continuing my work, including other modules shortly as well.

All the contents of the following modules including all uploaded rich document media(PDFs, PPTXs, .TXTs, etc.) will be indexed and made searchable taking proper care of security through Moodle capabilities.

*Book Resource
*Forum Module
*Glossary Module
*Label Resource
*Lesson Module
*Page Resource
*File Resource
*Url Resource
*Wiki Module

The search results will display highlighted matched queries alongwith context links/direct links to the corresponding record.

== Implementation and Milestones ==
*Writing cron jobs:(17th June - 21st June)
**Addition of records.
**Deletion of records.[shouldn't be focused upon just now]
**Update of records.
*Design the solr schema and solconfig files. (22nd June - 26th June)
**These files will be embedded in the in a separate directory under the Global Search directory. Users will have to copy these two files to the Apache Solr example directory that they will download which will run the Solr jetty server. See Installation for more.
**<code>schema.xml</syntaxhighlight> contains all the properties about the documents fields which are being indexed. There may be different fields pertaining to different modules.
**<code>solrconfig.xml</syntaxhighlight> contains the configurational parameters for solr.
*Writing the core search API for all searchable modules. (27th June - 3rd July)
**_SEARCH_ITERATOR($from=0)
**_SEARCH_DOCUMENTS($id)
*Adding proper security to the search API.(4th July - 8th July)
**_SEARCH_ACCESS($id)
***Use of Access API
****ACCESS_DENIED
****ACCESS_GRANTED
***ACCESS_DELETED: Situations where the records may have been deleted-hence not viewable.
*Reviewing all the above once. (9th July - 10th July)
*Integrating Apache Tika to handle indexing from external files (<code>PDFs</syntaxhighlight>, <code>PPTX</syntaxhighlight> etc.) (11th July - 13th July)
*Writing the search functions for querying. (Just a basic search UI to be used at this moment). (14th July - 17th July)
**Input for query.
**Input for filter fields for filtering the search results.
**Input for AND/OR.
**Phrase searches.
**Stemming.
**Support for wildcards.
*Admin page for search configuration options. (18th July - 21st July) (The UI page here will be the default type as being currently used. For example, Site Administration>Advance features)
**Deletion of index.
***Deletion of entire index in one go.
***Deletion of index by specific modules only.(For example, only the index of records belonging to 'forum' module is to be deleted).
**configurational options for cron
***Time of cron run.
*Implementing and releasing the first prototype <code>version: 1.0</syntaxhighlight> for developers' feedback. (22nd July - 28th July)
**See the '''Prototype''' section.
*Preparing for mid-term evaluation. (29th July - 1st August)
*MID_TERM EVALUATION (2nd August)
*Re-designing the search page. (2nd August - 7th August) (Taking ideas from community+discussion in [https://moodle.org/mod/forum/discuss.php?d=227805 forum])
*Improving the prototype after feedback from developers.(8th August - 15th August)
**Bug-fixing.
**Fixing security leaks.
**Improving relevance & speed of search results.
*Running Test cases and performance testing. (16th August - 21st August) (Performance testing will be good at this point as the code would have been optimized to some level as instructed by the developers above)
*Debugging. (22nd August - 29th August)
*Finalizing the Global Search documentation. (30th August - 6th September)
**Discussing it with my mentors whether everything has been properly covered or not.
*Buffer Period. (7th September - 8th September)
**Making sure everything above has been implemented correctly and efficiently.
*Submitting my code to Moodle and Google. (9th September - 15th September)
*Suggested Pencils Down Period. (16th September)
*Performing edits to the documentation after feedback from the Moodle community. (17th September - 22nd September)
*Firm Pencils Down and Final Evaluation. (23rd September)

== Quick setup for testing ==
This covers the features and procedure to install Global Search plugin. It would be very good if developers may come forward to test it and give their feedback which would be very crucial for improving it.
Developers may check out the cases in the '''Testing''' section. Developers may add their own preferred test cases and results (pass/fail) in that section which would be helpful for the other developers or you may comment on [https://moodle.org/mod/forum/discuss.php?d=227805 Global Search] discussion on Developer Forum.
*Here are some things that I've summarized that may be focused upon:
**Finding out any security leaks that I may have missed out.
**Relevance/speed of displaying search results.
**Taking ideas to optimize the [https://github.com/prateeksachan/moodle/tree/gs2rebased source code] wherever possible.
**Getting feedback.
**Addition/deletion of any search features that you may feel would be useful.
*Features included in this prototype:
**Indexing/Searching of content in all the above mentioned modules/resources.
**Support for indexing/searching rich documents.
**Admin configuration options.
**Support for advanced search queries as stated above.
*Steps to install and test Global Search plugin:
**Make sure you've installed your preferred PHP Solr extension (see sections above).
**You can simply clone my Github branch and checkout <code>gs2rebased</syntaxhighlight> branch.
:<code language="text">
git clone https://github.com/prateeksachan/moodle.git
git checkout gs2rebased
</syntaxhighlight>
**Go to '''Setting up Global Search in Moodle after installing PHP Solr extension''' section above.
**Open <code>../moodle/admin</syntaxhighlight> in your browser, and update the admin Global Search settings.
**Indexing is through cron. You will have to run the cron script to index content.

==Search workflow==
===Simple version===
# Moodle sends a query to standard solr handler.
# solr returns 1000 results. Results include all fields required to render search result row. Results are ordered by relevancy.
# Moodle checks each result in order to establish if it should be visible for current user or not
# Once 100 visible results are found, Moodle stops checking the rest and displays 100 results

The best case scenario is that Moodle needs to check only 100 returned results (first 100 are accessible for the current user).
The worst case scenario is that out of 1000 returned documents, none of them is available for the current user. In this case Moodle performs 1000 checks and displays "no results found" message.

===Advanced version===
More advanced version will use a logic on solr side to pre-filter some of the results.

== Testing ==
A list of test cases.
===New content===
* index
* add new forum post
* re-index

* make sure new content is searchable

===Updated content===
* index
* edit existing forum post
* re-index

* make sure new content is searchable
* make sure old content is not searchable

===Deleted content===
* index
* delete existing forum post
* re-index

* make sure deleted content is not searchable

===Backup restored===
* index
* restore whole course from a backup
* re-index

* make sure restored content is searchable

===Access Tests===
====Common Access====
*Add courses.
*Create activity modules/resources that are supported by Global Search (See section '''Searchable content in Global Search''').
*Insert content or attach files (wherever possible)
*Index
*Make sure the results are visible only to those who have access to the respective course's activity/resource.
*Set Common Module Settings of activities/resources as Hidden.
*Make sure those activities/resources do not appear in search results.

====Forum Activity Module Access====
*Create a course.
*Create groups in it.
*Create a Forum Activity.
*Post in the forum discussions from members of different groups. (+you may also attach files)
*Index.
*Make sure members see posts only from those groups which they are a member of.

====Lesson Activity Module Access====
*Create a course.
*Create a Lesson Activity.
1. Type 1
*Assign Availability
**Available From only
**Deadline only
**Time limit
**Password Protection
**Combinations of the above
*Index.
*Make sure there are no access leaks when searching as a student.
*Make sure the teacher, manager are able to see the searches.

2. Type 2
*Assign Prerequisite Lesson
**Set Dependent On Prerequisite feature.
**Set Time spent Prerequisite feature.
**Toggle completed Prerequisite feature.
**Set Grade Prerequisite feature.
**Combinations of the above.
*Index
*Make sure there are no access leaks when searching as a student.
*Make sure the teacher, manager are able to see the searches.

====Wiki Activity Module Access====
*Create a course.
*Create Groups.
*Create a Wiki Activity.
*Set Group Mode On
1. Type 1
*Group Mode: Separate Groups
*Add Wikipages. (+you may also attach files)
*Index
*Make sure there are no access leaks: A group shouldn't see results from other groups.
2. Type 2
*Group Mode: Visible Groups
*Add Wikipages.(+you may also attach files)
*Index
*Make sure there are no access leaks: A group shouldn't see results from other groups.

====Results====
#
#
#
#

== Credits ==
*My Mentors:[https://moodle.org/user/view.php?id=353008&course=5 Tomasz Muras] & [https://moodle.org/user/view.php?id=1146834&course=5 Aparup Banerjee]
*[http://lucene.apache.org/solr/ Apache Solr Community]
*[https://github.com/ecaron/php-pecl-solr PHP-Solr extension for Solr 4.x]

== See also ==
* [[GSOC/2013|Moodle GSoC projects for 2013]]
* [[GSOC|Moodle GSoC Overview page]]
* [https://moodle.org/mod/forum/discuss.php?d=227805 Writing Moodle's Global Search Discussion]

[[Category:GSOC]]
[[Category:Project]]

Git for developers

2021-08-11T14:54:16Z

Moodlebot: Text replacement - "</code>" to "</syntaxhighlight>"

This document is for helping you get started on Moodle development with Git. For further details of Git, see [[:Category:Git]].

== General workflow ==

'''A reasonable knowledge of the Git basics is a good idea before you start to use it for development. If you are new to Git, you are encouraged to go to 'See also' for some more general reading.'''

[[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]]
Detailed explanation of the workflow can be found in the [[Process]] page. In short, the Moodle development with Git looks like this:

* You as the contributor commit changes into your personal repository at your computer
* You push the changes into your public repository and publish links to your changes in the Moodle Tracker
* You request a peer review of your code from another developer
* When peer reviewer is happy they submit issue for integration
* Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
* The integrated change is tested and finally pushed into Moodle production repository
* You update your local repository with all changes from the production repository and the next cycle may start again

This workflow runs in roughly weekly cycles. The integration happens on Monday and Tuesday and the testing on Wednesday. On Thursday (or Friday if testing takes too long), the production repository moodle.git is usually updated with changes from the last development week.

Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github.

When you first register on tracker you can not assign issues to yourself or send them for peer review. You will be added to the developers group after your first bug fix is integrated. Before that just comment on the issue with a link to your branch and component lead or another developer will send issue for peer review for you.

== Installing Git on your computer ==

Install Git on your computer. Most Linux distributions have Git available as a package to install. On Debian/Ubuntu, type ''''sudo apt-get install git'''' on the terminal. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in a few clicks.

Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".

git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld

Unless you are the repository maintainer, it is wise to set your Git to not push changes in file permissions:

git config --global core.filemode false

Also, it's recommended to verify that the your git installation is not performing any transformation between LFs and CRLFs. All Moodle '''uses only LFs''' and you should '''fetch/edit and push''' it that way (may need to configure your editor/IDE too). Note that having any "magic" enabled is known to cause [[Common unit test problems#The_test_file_.22evolution.test.22_should_not_contain_section_named_.22.5Blots_of_content.5D.22|problems with unit tests]] execution. So we recommend you to set:

git config --global core.autocrlf false

== Setting-up the public repository ==

1. Go to [http://github.com/ Github] and create an account.

2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository.

3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!

4. If you want, you can set up [[Travis integration]] with your GitHub repository so that when you push your code, Travis will automatically run a suite of tests for you against your changes. This way you can quickly catch issues without having to set up a testing environment locally (and before you share your code with other Moodle developers!). Another option to automate the execution of the Moodle test suite is to setup [[Github actions integration]].

== Setting-up the local repository at your computer ==

Create a local clone repository of your Github repository. In a terminal:

git clone git://github.com/YOUR_GITHUB_USERNAME/moodle.git LOCALDIR

(or: git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git LOCALDIR)

This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.

Note that the format of the URL here is important. In the first example, the URL starts "git://github.com" and this will give read-only access to the repository at github.com. If you use this URL, the "git push origin" command that appears later in this document will not work. Therefore, if you want to be able to update the "origin" repository, you should use the URL that starts "git@github.com", i.e. the second of the two "git clone" commands given above. This will give you read and write access to the repository on github.com.

== Keeping your public repository up-to-date ==

[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]]
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.

To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.

To register the upstream remote:

cd moodle
git remote add upstream git://git.moodle.org/moodle.git

The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.

#!/bin/bash
git fetch upstream
for BRANCH in MOODLE_{19..39}_STABLE MOODLE_{310..311}_STABLE master; do
git push origin refs/remotes/upstream/$BRANCH:refs/heads/$BRANCH
done

=== How it works ===

The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.

Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.

=== New branches ===

Occasionally, moodle.org will create a new branch that does not exist in your public (e.g. Github.com) repository. If you try to push this new branch, you will see an error such as the following:

error: unable to push to unqualified destination: MOODLE_99_STABLE
The destination refspec neither matches an existing ref on the remote
nor begins with refs/, and we are unable to guess a prefix based on the source ref.
error: failed to push some refs to 'git@github.com:YOUR_GITHUB_USERNAME/moodle.git'

In the above example, "MOODLE_99_STABLE", is the name of the new branch that does not exist in your public repository. To fix the error, you need to create the new branch on your public repository, using the following commands, replacing "MOODLE_99_STABLE" with the name of the new branch you wish to create:

git checkout MOODLE_99_STABLE
git push origin MOODLE_99_STABLE:MOODLE_99_STABLE

The above code will create a new copy of the "MOODLE_99_STABLE" branch in your local repository. If you do not need to keep a local copy of the new branch - and probably you do not need it, you then can remove it from your local repository as follows:

git checkout master
git branch -D MOODLE_99_STABLE

== Preparing a patch ==

As said earlier at this page, you never work on standard Moodle branches directly. Every time you are going to edit something, switch to a local branch. Fork the local branch off the standard branch you think it should be merged to. So if you are working on a patch for 1.9 or 2.0, fork the branch off MOODLE_19_STABLE or MOODLE_20_STABLE, respectively. Patches for the next [[Moodle versions|major version]] should be based on the master branch.

git checkout -b MDL-xxxxx-master_brief_name origin/master

Note that if you forget to specify the starting point, the branch is based on the currently checked-out branch. It may not be what you want. It is recommended to always specify the starting point.

To check the current branch, run

git branch

The current branch is highlighted.

Now go and fix the issue with your favorite IDE. Check the status of the files, view the change to be committed and finally commit the change:

vim filename.php
git status
git diff
git commit -a

For the commit message, please do respect the guidelines given on in the article [[Coding style#Git_commits|Coding_style]].

Note that this is safe as the commit is recorded just locally, nothing is sent to any server yet (as it would in CVS). To see history of the commits, use

git log

Once your local branch contains the change (note that it may consists of several patches) and you are happy with it, publish the branch at your public repository:

git push origin MDL-xxxxx-master_brief_name

Now as your branch is published, you can ask Moodle core developers to review it and eventually integrate it into the standard Moodle repository.

=== Changing commit message, reordering and squashing commits ===

It often happens that you made a mistake in your patch or in the commit message and helpful CiBot pointed it out for you. You can "rewrite the history" and change the existing commits.

Option 1. Reset all the changes in the branch and commit again.

git reset --mixed origin/master

Now all your changes are still present but all commits on top of "master" branch are gone. You can create a new commit

Option 2. Discover '''git rebase --interactive''' - this is a powerful tool to change the sequence of commit, change the commit messages, squash commits, etc. We will not cover it here, there are many articles in the Internet about it, for example: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History.

Whatever option you chose, you have "rewritten the history" and you can not simply push the changes to github again because they would need to overwrite the commits that were already pushed. If you try "git push MDL-xxxxx-master_brief_name" you will get an error message suggesting you to force push.
To force push the changed commits use:

git push -f origin MDL-xxxxx-master_brief_name

If an error occurs because you are still using the git protocol (read only), use this command :

git remote set-url origin https://github.com/<user.name>/moodle.git

A prompt will ask for your credentials, if you previously setup your SSH public key you can also use this one :

git remote set-url origin git@github.com:<user.name>/moodle.git

=== Checking if a branch has already been merged ===

After some time contributing to Moodle you would have a lot of branches both in your local repository and in your public repository. To prune their list and delete those that were accepted by upstream, use the following

git fetch upstream (1)
git branch --merged upstream/master (2)
git branch --merged upstream/MOODLE_20_STABLE (3)

The command (1) fetches the changes from your upstream repository at git.moodle.org (remember that git-fetch does not modify your working dir so it is safe to run it whenever). Command (2) and (3) print all branches that are merged into the upstream master branch and MOODLE_20_STABLE branch, respectively. To delete these local branches, use

git branch -d MDL-xxxxx-master_accepted_branch

The similar approach can be used to check the branches published at your origin repository at github.com

git fetch origin (1)
git fetch upstream
git branch -r --merged upstream/master (2)
git branch -r --merged upstream/MOODLE_20_STABLE (3)

The command (1) makes sure that you have all your branches from github.com recorded as the remote tracking branch locally. Commands (2) and (3) work the same as in the previous example but they list remote tracking branches only ([http://www.kernel.org/pub/software/scm/git/docs/git-branch.html see -r param]). To delete a branch at github.com, use

git push origin :MDL-xxxxx-master_branch_to_delete

This syntax may look weird to you. However it is pretty logical. The general syntax of the git-push command is

git push <repository> <source ref>:<target ref>

so deleting a remote branch can be understood as pushing an "empty (null) reference" to it.

== Peer-reviewing someone else's code ==

To review a branch that someone else pushed into their public repository, you do not need to register a new remote (unless you work with such repository frequently, of course). Let us imagine your friend Alice pushed a work-in-progress branch called 'wip-feature' into her Github repository and asked you to review it. You need to know the read-only address of the repository and the name of the branch.

git fetch git://github.com/alice/moodle.git wip-feature

This will download all required data and will keep the pointer to the tip of the wip-feature branch in a local symbolic reference FETCH_HEAD. To see what's there on that branch, use

git log -p FETCH_HEAD

To see how a particular file looks at Alice's branch

git show FETCH_HEAD:admin/blocks.php

To create a new local branch called 'alice-wip-feature' containing the work by Alice, use

git checkout -b alice-wip-feature FETCH_HEAD

To merge Alice's work into your current branch:

git merge FETCH_HEAD

To see what would be merged into the current branch without actually modifying anything:

git diff ...FETCH_HEAD

Once you are all set and reviewing code, this [[Peer_reviewing_checklist|checklist]] should prove to be useful.

== Rebasing a branch ==

Rebasing is a process when you cut off the branch from its current start point and transplant it to another point. Let us assume the following history exists:

A---B---C topic
/
D---E---F---G master

From this point, the result of the command:

git rebase master topic

would be:

A'--B'--C' topic
/
D---E---F---G master

and would end with 'topic' being your current branch.

You may be asked to rebase your branch submitted for the integration if the submitted branch was based on an outdated commit. The typical case is if you create a new branch as a fork off the upstream master branch on Tuesday. Then on Wednesday, the upstream master branch grows as all changes from the last integration cycle are merged to it. To make diff easy on Github for next weekly pull request review, you want to rebase your branch against the updated master.

git rebase master MDL-xxxxx-master_topic_branch

Note that rebasing effectively rewrites the history of the branch. '''Do not rebase the branch if there is a chance that somebody has already forked it and based their own branch on it.''' For this reason, many Git tutorials discourage from rebasing any branch that has been published. However in Moodle, all branches submitted for integration are potential subject of rebase (even though we try to not to do it often) and you should not base your own branches on them.

=== Conflicts during rebase ===

During the rebase procedure, conflicts may appear. git-status commands reports the conflicted files. Explore them carefully and fix them in your editor (like you would do with CVS). Then add the files with 'git add' command and continue.

vim conflicted.php
git add conflicted.php
git rebase --continue

== Applying changes from one branch to another ==

Most bugs are fixed at a stable branch (like MOODLE_20_STABLE) and the fix must be prepared for other branches, too (like MOODLE_21_STABLE and the main development branch - master). In Moodle, we do not merge stable branches into the master one. So usually the contributor prepares at least two branches - with the fix for the stable branch(es) and with the fix for the master branch.

If you have a patch prepared on a local branch (let us say MDL-xxxxx-20_brief_name), it is possible to re-apply it to another branch.

=== Cherry-picking a single commit ===

Let us have two local Git repositories ~/public_html/moodle21 containing local installation of Moodle 2.1 and ~/public_html/moodledev with the local installation of most recent development version of Moodle. They both use your public repository at github.com as the origin. You have a branch in moodle21 called MDL-xxxxx-21_topic that was forked off MOODLE_21_STABLE. It contains one commit. Now you want to re-apply this commit to a branch MDL-xxxxx-master_topic in moodledev.

cd ~/public_html/moodledev
git checkout -b MDL-xxxxx-master_topic origin/master (1)
git fetch ../moodle21 MDL-xxxxx-21_topic (2)
git cherry-pick FETCH_HEAD (3)

The command (1) creates new local branch forked off the master. The command (2) fetches all data needed to re-apply the topic branch and stores the pointer to the tip of that branch to FETCH_HEAD symbolic reference. The command (3) picks the tip of the branch (the top-most commit on it) and tries to apply it on the current branch.
There is also a variant of the cherry-pick command that supports multiple commits, shortly (see its man page for details): <code bash>$ git cherry-pick A^..B</syntaxhighlight> if you want to include from A - see '''^''' - to B, A should be older than B. We will use another approach for cherry-picking multiple commits.

=== Applying a set of patches ===

If the branch MDL-xxxxx-21_topic from the previous example consists of several commits, it may be easier to use git-format-patch and git-am combo to re-apply the whole set of patches (aka patchset). Firstly you will export all commits from the topic branch to files.

cd ~/public_html/moodle21
mkdir .patches
git format-patch -o .patches MOODLE_21_STABLE..MDL-xxxxx-21_topic (1)

The command (1) takes all commits from the topic branch that are not in MOODLE_21_STABLE and exports them one by one to the output directory .patches. Look at the generated files. They contain the patch itself (in diff format) and additional information about the commit. You could eg send these files by email to a friend of yours for peer-review. We will use them in another repository.

cd ~/public_html/moodledev
git checkout -b MDL-xxxxx-master_topic origin/master
git am -3 ../moodle21/.patches/* (1)

The command (1) applies all the files from the .patches directory. When a patch does not apply cleanly, the command tries fall back on 3-way merge (see the -3 parameter). If conflicts occur during the procedure, you can either deal with them and then use `git am --continue` or abort the whole procedure with `git am --abort`.

== See also ==

* [[Git tips]]

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183409 Git help!! I don't understand rebase enough...]
* [http://moodle.org/mod/forum/discuss.php?d=217617 add MOODLE_24_STABLE to github.com repository]

; External resources
* [https://mirrors.edge.kernel.org/pub/software/scm/git/docs/giteveryday.html Everyday GIT With 20 Commands Or So]
* [https://git-scm.com/book/en/v2 'Pro Git' complete book]
* [http://vimeo.com/14629850 Getting git by Scott Chacon] - an recording of an excellent 1-hour presentation that introducing git, including a simple introduction to what is going on under the hood.
* [http://tjhunt.blogspot.co.uk/2012/03/fixing-bug-in-moodle-core-mechanics.html Tim Hunt's blog: Fixing a bug in Moodle core: the mechanics]
* [https://github.com/k88hudson/git-flight-rules/blob/master/README.md#flight-rules-for-git Flight rules for Git]

[[Category:Git]]

[[ja:開発者用Git]]

CodeSniffer

2021-08-11T14:54:16Z

Moodlebot: Text replacement - "</code>" to "</syntaxhighlight>"

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Installing PHP CS===

'''Using pear installer'''

1. Install the Pear package for PHP CS, pear install PHP_CodeSniffer

2. Download the standard: PHPCompatibility and moodle directories from https://github.com/moodlehq/moodle-local_codechecker

3. Copy the previous directories to the PHP CS standard path:
* in Mac with Macports is /opt/local/lib/php/PHP/CodeSniffer/Standards/
* In Mac with Homebrew is /usr/local/share/pear\@7.0/PHP/CodeSniffer/Standards/
* in Linux is /usr/share/php/PHP/CodeSniffer/Standards/ or /usr/share/php/PHP/CodeSniffer/src/Standards

4. If they are installed properly, moodle and PHPCompatibility will show up in the output of `phpcs -i`. Here is a typical example:
<code>
The installed coding standards are MySource, PHPCompatibility, Squiz, PSR2, moodle, PEAR, PSR1, PSR12 and Zend
</syntaxhighlight>

5. Optionally, you can set the default standard in a configuration file:
<code>
phpcs --config-set default_standard moodle
</syntaxhighlight>

'''Install using composer'''

1. Run the following in your terminal from your moodle folder:
<code>
composer global require "squizlabs/php_codesniffer=3.*"
</syntaxhighlight>

2. Download the standard: PHPCompatibility and moodle directories from https://github.com/moodlehq/moodle-local_codechecker
to an accessible location on your computer - it doesn't have to be your project folder.

Note: "blackboard-open-source/moodle-coding-standard" is no longer being maintained.

3. Tell phpcs about where to find the Moodle code checker
<code>
phpcs --config-set installed_paths /path/to/moodle-local_codechecker # adds moodle's standard to phpcs
</syntaxhighlight>

4. If they are installed properly, moodle and PHPCompatibility will show up in the output of `phpcs -i`. Here is a typical example:
<code>
The installed coding standards are MySource, PHPCompatibility, Squiz, PSR2, moodle, PEAR, PSR1, PSR12 and Zend
</syntaxhighlight>

5. Optionally, you can set the default standard in a configuration file:
<code>
phpcs --config-set default_standard moodle
</syntaxhighlight>

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

====Windows set up====

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will not include Moodle. To install the moodle standard, copy the"moodle" and "phpcompatibility" folders from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

====Linux set up====

After installing codesniffer and codechecker, copy the moodle and phpcompatibility standard folders from (assuming you have the code in /local/codechecker)

/var/www/moodle/local/codechecker/

to

/usr/share/pear/PHP/CodeSniffer/Standards/

There is an option to set the default standard in a configuration file:

phpcs --config-set default_standard moodle

Then restart Netbeans and it should now work. You can also switch between coding standards.

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<code>
lib/pear/PHP/runsniffer index.php
</syntaxhighlight>

You will get a report that looks like this:

<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</syntaxhighlight>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<code>
lib/pear/PHP/runsniffer -n index.php
</syntaxhighlight>

Resulting output:
<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</syntaxhighlight>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<code>
lib/pear/PHP/runsniffer --report=summary files
</syntaxhighlight>

Report:
<code>
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</syntaxhighlight>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<code>
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</syntaxhighlight>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===

When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle core, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

For using the thirdpartylibs.xml in your plugins, please see [[Plugin files#thirdpartylibs.xml]].

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]

Bug triage

2021-08-11T14:54:16Z

Moodlebot: Text replacement - "</code>" to "</syntaxhighlight>"

[[File:Triage.png|200px|right|alt Triage image]]
Triage is medical term referring to the process of prioritising patients based on the severity of their condition so as to maximise benefit (help as many as possible) when resources are limited.

Bug triage is a process where tracker issues are screened and prioritised. Triage should help ensure we appropriately manage all reported issues - bugs as well as improvements and feature requests.

Triage initially happens shortly after the issue was reported but it can be repeated later if the initial assumptions were wrong, issue was resolved otherwise, affected versions need updating or there are other reasons to review the issue.

==Get involved==

Anybody can do triage in form of correcting the components and/or affected versions, linking to related issues, and of course commenting asking for clarification, confirming bug, redirecting to forum, etc. Users in ''jira-developers'' and ''moodle-triage'' groups can edit any issue, ''jira-users'' can comment on any issue or edit issues they reported. Please see MDLSITE-3592 if you are not a developer but would like to help with triage process.

Adding ''triaged'' label and placing the issue on the backlog should only be done by component lead or HQ developer. At the same time other users can remove ''triaged'' label from the old issues or replace it with ''triaging_in_progress'' if they want to request an additional triage.

==The triage process==

===Initial screening===

First of all, identify the issues that should be closed or placed under investigation. Ask the following questions:

* '''Is the issue a request for support/help?''' If so, the reporter should be directed to the forums to seek help and the issue should be closed as "Not a bug". Sometimes improvement requests can be phrased as a question, though; if this is the case, ask the reporter to reword the description to describe an improvement.
* '''Have the reporter mistaken the Moodle Tracker with their own support desk?''' Sometimes people mistake the Moodle Tracker as a place to request help about their own Moodle instance, often about logging in. We need to refer the user to their instance administrators and close the issue as "Not a bug".
* '''Has the issue been reported previously?''' If so, link to a duplicate issue and close the newly reported issue as a "Duplicate" with no fix version set. Encourage the reporter to search before reporting. If a newer issue has a patch or more voters/watchers, consider closing the older issue. Checking for duplicates first will save you having to check the rest of the issue. See [[Tracker tips]] for help with effective search of tracker.
* '''Does the problem affect only unsupported versions?''' If so, the issue should be closed using "Fixed" (preferred as it sounds better) when the issue is resolved in current versions or "Not a bug" when the issue has disappeared due to changes leading to current versions. See [Releases] to find currently supported versions
* '''Did the problem arise because of mistake in documentation or lack thereof?''' If it appears that the reporter does not understand a particular feature in Moodle and the documentation is lacking, ask the reporter where would he expect to find documentation about it. Then simply edit the relevant pages in the documentation wiki and close the issue. If required change is significant, add ''Documentation'' component and ''docs_required'' label.
* '''Is the problem a language string change?''' Language string problems can be corrected by [[Contributing a translation|contributing a translation]] or by contacting the language pack maintainer as listed in the [https://lang.moodle.org/local/amos/credits.php Translation credits]. English language string typo fixes and suggested improvements can be [[Improving English language strings|contributed to the English (fixes) (en_fix) language pack]] or given the component 'Language' for fixing by the Language component lead. Such issues should be closed in the Tracker using "Deferred".
* '''Is it a usability issue?''' If so, add the component "Usability" in addition to the component(s) specifying the area of Moodle.
* '''Was the problem caused by additional code or 3rd party plugins?''' If you can identify the plugin, move the issue to the respective component of CONTRIB project. Otherwise comment and close as "Not a bug".
* '''Can this be implemented as a plugin?''' And maybe the plugin already exists in the plugins directory. Explanation should be given to the reporter that Moodle provides the framework but does not work on any possible plugin. Add label "addon_candidate" but do not close the issue. This can also apply to the requests to significantly redesign existing plugins and it would be more preferable to create a new alternative plugin.
* '''Does the problem seem rational?''' If not, then the problem may simply be an misunderstanding on the part of the reporter. It might be a problem exclusive to the reporter's server set-up. If you can replicate the problem quickly, do so. If you can't replicate the problem, ask the reporter to attempt to replicate the problem on http://demo.moodle.net. If the problem seems persistent but strange, consider asking a developer with experience working in the area to consider the problem and determine if it could be a real problem.
* '''Can the problem be replicated?''' If not, or information on the issue is insufficient, ask the reporter to add error messages, screenshots, environment information (OS, web server, browser) and exact replication instructions

As a result of initial screening up to 20% of new issues may be closed. When closing the issues make sure to set the correct resolution and write a polite comment with explanation, refer to the templates below. If you have doubts, ask the questions and always add label [https://tracker.moodle.org/issues/?jql=labels%20in%20%28triaging_in_progress%29 triaging_in_progress]. Subscribe to the filter [https://tracker.moodle.org/issues/?jql=labels%20in%20%28triaging_in_progress%29%20AND%20project%20%3D%20MDL%20AND%20resolution%20%3D%20Unresolved%20AND%20Participants%20%3D%20currentUser%28%29%20AND%20updatedDate%20%3C%20-30d My old issues in triage] and you will receive notifications after 30 days of inactivity on such issues. See [[Tracker tips]] about how to subscribe to filter. Very often the reporter never follows up on their own issues and this is a good way to find such issues and ping reporter again or make a final decision about closing.

===Confirming the issue===

When you confirm that issue is indeed a bug or a reasonable improvement request that was not reported previously, make sure that the following is accurate:

* '''Security level.''' Security level must be set as soon as possible if the reported bug discloses vulnerability in Moodle that can be exploited to access information without appropriate level, create an attack on the site, embed XSS or forge a request. In some rare cases Improvements may be also marked as security
* '''Summary.''' Summary of the issue should clearly describe the problem or improvement area, rephrase such summaries as "Some improvements in xxx" or "Error in Moodle", etc.
* '''Issue Type.''' The following issue types are used in Moodle:
** Bug - represents an actual bug and should be fixed in all supported versions. Very often when reporter expects something to be better than it actually is they call it a bug when it's in fact an improvement.
** Improvement - improvement to existing functionality. If addressed, will be integrated in the following major release only
** New feature - completely new feature, also will not be applied to the released versions (unless implemented as a plugin and submitted to plugins directory)
** Task - usually created by developers themselves and can not be classified as Bug or Improvement, for example, adding automated tests, improving documentation, etc.
** Epic - created by HQ developers or component leads to collect together issues that represents parts of one project. META issues and sub-tasks should not be used any more
* '''Priority.''' Some reporters over-state an issue's priority. Some reporters don't know they can set a priority. Priority is used as one of the criteria when sorting issues in the backlog, so it should reflect the position of this issue comparing to the others. Usually Improvements have Minor or Major priority and Bugs can have any priority up to Blocker. Priority levels have specific criteria. Please see [https://docs.moodle.org/dev/Tracker_guide#When_editing_an_issue the Tracker guide]
* '''Component/s.''' Listing components correctly is important as they are the primary variable used for searching for issues, also adding a component automatically include the component lead as a watcher. Issue may have several components when needed
* '''Affects version.''' This field should include one or more released *and supported* versions of Moodle that are affected by the issue, with the following exceptions:
** The issue is a bug in code that is present in the Master branch only, in which case the next major version should be used. (The next major version should not be used in conjunction with previous released versions, this won't make sense later.)
** The issue is a new feature and is unrelated to any existing code in Moodle, in which case the 'Future dev' version should be used.
* '''Labels.'''
** Remove functionality tags that some reporters add as labels, only [https://docs.moodle.org/dev/Tracker_issue_labels standard] labels or partner-specific labels are used in Moodle
** Issues with proposed fixes are labelled ''patch'' so that they can be found easily and given attention. When this is the case, consider whether moving the issue to the 'Waiting for peer review' state in the workflow might be more appropriate
** Add ''addon_candidate'' label if the functionality can be implemented as a plugin;
** If you are component lead or HQ developer you may also add ''triaged'' label to indicate that triage process is completed. Use it only when the issue has actually been added to the backlog

''Note that "Fix version" is no longer used during triage. If you are in "moodle-triage" group, you can use the '''Triage screen''' to edit only aforementioned fields, see MDLSITE-3592.''

When commenting on the issue give more details on replication, environment or testing. Ask questions, add watchers, modify description if needed. Link to as many related issues as possible. Do everything that will make the issues scope more clear and attract opinions, discussions and patches.

Don't forget to show '''Gratitude and encouragement'''. After triaging many issues, it's easy to lose sight of the fact that the reporter has contributed their time and energy to report an issue for the benefit of the community.

It is easy to become defensive of Moodle if reports are seen as criticism (and sometimes reporters may use phrasing that suggests this), however the triagers response must always be one of sincere gratitude.

It is also important to encourage reporters to continue being involved with the issue after it is triaged. We must not give the sense that we are taking the issue ownership away from the reporter. Instead the reporter should be encouraged to discover the cause of the problem and present a solution; this is appropriate in an open-source project. It is amazing that such a challenge can lead to a sense of purpose for the reporters.

=== Following up on issues ===

Tracker is set up by default so as soon as you comment on any issue or edit it, you become an automatic watcher and any following change on the issue will be emailed to you.

If you have encouraged the reporter well, they may '''submit a patch''' or somebody else may do it. Make sure that the ''patch'' label is added or issue is sent to peer review. On the contrary, if ''patch'' label was added by somebody else but you clearly see that patch is far from ready, remove the label and leave a comment explaining it.

Users may also comment with additional details, screenshots, replicating instructions. It may happen that the issue gets re-evaluated and priority or summary changed.

=== Revisiting old issues ===

While searching the tracker you may come over issues that were reported long time ago but still remain open. Again, ask the following questions

* '''Is this still an issue?''' If it is not applicable any more either close it or comment about it on the issue and recommend to close. Very few tracker users actually have permission to close issues but the component lead or watchers will see your comment and revisit issue. Another good practice is to replace ''triaged'' label with ''triaging_in_progress'' and add a comment asking if the issue can be closed. If users confirm that it was resolved or nobody replies in 30 days, issue should be closed.
* '''Do affected versions need correction?''' If the issue is still applicable, make sure to add missing current affected versions or comment about it on the issue if you can't edit it.
* '''Does the issue have patch and if yes, is it still applicable?''' If the issue has patch that still works but ''patch'' label is missing, look through comments or history to see if the ''patch'' label was removed after reviewing the current patch. If you find that label was never added, do it yourself. On contrary if the issue has ''patch'' label but the patch is no longer applicable or not sufficient, remove the label.
* '''Are there any duplicating issues?''' When finding duplicates among the old issues it might not be obvious which issue to close as a duplicate. Usually we should leave the first reported issue but if the later issues have more watchers, better description, more votes, useful comments, attached patch, etc. you may decide to close the earlier issue and leave the later. Sometimes both issues have lots of watchers and they both remain open. In any case, always create links between duplicates or related issues.
* '''Does the issue have assignee who forgot about it or misleading status "Development in process"?''' Due to some [[Changes_to_issue_assignment|process changes]] in May 2013 some issues still have a real user in the ''Assignee'' field but this user actually does not work on the issue. Sometimes ''Assignee'' remains filled after failing peer review, sometimes developers simply forget that the issue was assigned to them. If you suspect that ''Assignee'' does not actually work on the issue, comment asking they about it and in some cases remove the ''Assignee'' completely. Allow somebody else to work on the issue without feeling that the issue is "taken". Please also note that for some time tracker had a restriction that ''Assignee'' could not be empty so you can find lots of issues assigned to ''moodle.com'' or ''Nobody''. Do not modify such issues as this creates unnecessary activity, emails to watchers and irrelevant change in the "Last update date".

=== Comments templates ===
====Redirecting someone with a support request====

Thanks for taking the time to create an issue. However, the problem you describe seems to be specific to your site, since I am unable to reproduce it on http://demo.moodle.net/. Thus I suggest you post asking for help in one of our community forums https://moodle.org/community/. 
I'm going to close this issue now. If you find that your problem can indeed be reproduced on http://demo.moodle.net/ or you have a suggestion for an improvement, please create a new issue providing as much detail as you can.

====Redirecting someone making a 'feature request' that is actually already possible====

Thank you for taking the time to request a new feature / suggest an improvement. However, what you ask for is already possible. I suggest you post asking for help about how to set up what you want in one of our community forums https://moodle.org/community/. 
I'm going to close this issue now.

====Refer the user to their instance administrators====
You have posted an issue on the Moodle Tracker, which relates to the improvement of Moodle code, not the Moodle site you are using at your institution. I recommend you contact the administrators of your Moodle site.

====Closing duplicate====

Thanks for your report. 
It seems you're not the only one to have come across this bug, as it's been reported previously - see MDL-xyz. I'm going to close this issue now so we can focus on MDL-xyz. Please watch, vote or comment on MDL-xyz if there is any additional information you can provide.


====Issue affects only unsupported versions====

Thanks for your report and apologies for it not being looked at before now. I tried but couldn't reproduce the problem in the latest stable version of Moodle. Thus, it seems it has been fixed as part of another issue and so I am closing this issue with resolution 'Cannot Reproduce'. If you find that the problem can indeed be reproduced in the latest stable version of Moodle (for example on the [Moodle sandbox demo|https://sandbox.moodledemo.net]) please create a new issue with clear steps to reproduce and link it to this one.

====Requesting more information====

Thanks for reporting this. 
Could you please add more information to your report such as replication instructions, error messages and screenshots. If you are able to suggest a workaround, that would be immediately helpful to others experiencing this problem. If you can determine the cause of the problem or even determine a solution, that will be very valuable.


====Request to correct translation====

Thanks for reporting this. 
<nowiki>The problem that you are describing refers to the translation in another language. Language string problems can be corrected by [Contributing a translation|https://docs.moodle.org/dev/Contributing_a_translation] or by contacting the language pack maintainer as listed in the [Translation credits|http://lang.moodle.org/local/amos/credits.php]. I'm going to close this issue because Moodle does not include translations in the standard download package.</nowiki> 


====Correction to English language strings====

Thanks for reporting this. 
Please note that English language string typo fixes and suggested improvements can be <nowiki>[contributed to the English (fixes) (en_fix) language pack|https://docs.moodle.org/dev/Improving_English_language_strings]</nowiki>


====Bug in contributed plugin (plugin can be identified)====

You have created an issue under MDL project in the tracker. However the problem that you are describing refers to contributed plugin xxx. 
<nowiki>I have moved your issue in the appropriate component of the CONTRIB project in tracker. I will also recommend you to leave a comment on the plugin page in the [Moodle plugins directory|https://moodle.org/plugins/]</nowiki>


====Triaging a bug report====
Thanks for reporting this issue.

You can help us resolve it as quickly as possible by:

* Adding further information in a comment or attaching a screenshot if requested by a developer investigating the issue.
* Posting the issue number in a moodle.org forum discussion about it.
* If you are able to provide a patch or links to your Git repository branch, please add a patch label so we will spot it.

====Triaging an improvement or new feature====

Thanks for suggesting an improvement or new feature. 
<nowiki>Please try [searching moodle.org|http://moodle.org/public/search/] to check whether someone else has had the same idea, then either join an existing discussion or start a new discussion in [Moodle in English|http://moodle.org/course/view.php?id=5]. Comment here with the link to the discussion, and mention this issue number in the discussion to encourage others to watch, vote or comment on it.</nowiki> 
<nowiki>If you can propose a code solution, please [create a patch|https://docs.moodle.org/dev/How_to_create_a_patch] or provide links to your Git repository branch, then add the patch label to the issue. </nowiki> 
<nowiki>For more ways to maximize the chance of your idea being implemented, see the guide [New feature ideas|https://docs.moodle.org/dev/New_feature_ideas].</nowiki>


==Creating a filter and gadget for triaging==

If you are a component lead you are responsible for triaging issues that involve your component. A good way to monitor newly created issues is to create a filter in the Tracker and add a gadget on your dashboard to show the results of the filter.

===Adding a filter===

In Tracker...
# Select ''Issues'' > ''Search for Issues''.
# Create a search for untriaged issues in your component, for example...
#: <code>component in (Assignment) AND resolution = Unresolved AND (labels is EMPTY OR labels not in (triaged)) ORDER BY created DESC</syntaxhighlight>
# Run the search query by pressing ''Enter'' or clicking the magnifying glass icon to the right of the search box.
# When the search query results are displayed, click the ''Save as'' button.
# Save the search query with an appropriate name, like "Untriaged Assignment issues".

===Adding a filter in a gadget to your dashboard===

In Tracker...
# Click ''Dashboards'' > ''Dashboard for XXX'' (where ''XXX'' is your name).
# Click ''+ Add Gadget''.
# Find the ''Filter Results'' gadget.
# Click ''Add it Now''.
# Click ''Finished''.
# In the ''Saved Filter'' input, search for and select your newly created filter.
# Click ''Save''.

The most recent untriaged issues should appear in reverse-date order.

==Triaging priorities and the Triaging Dashboard==

The following are the priorities for ordering issues to be triaged that are reflected on the [http://tracker.moodle.org/secure/Dashboard.jspa?selectPageId=11153 Triaging dashboard].

# Security issues - should always be reduced to 0
# High-priority issue - aim for blockers and critical issues to be reduced to 0
# Partner issues - aim for partner issues to be reduced to 0
# Patched issues - aim to triage as soon as possible
# Developer-reported issues (HQ and non-HQ) - should be quick to triage
# Recent community bugs - should be triaged last-in-first-out

==See also==

*[[Tracker guide]]
*[[Process]]
*[[Talk:Bug triage]]
*[[Tracker tips]]

[[Category:Processes]]
[[Category:Quality Assurance]]
[[Category:Tracker]]

Backup 2.0 for developers

2021-08-11T14:54:09Z

Moodlebot: Text replacement - "</code>" to "</syntaxhighlight>"

{{Template:Backup 2.0}}{{Moodle_2.0}}{{Work in progress}}

== Introduction ==

This page tries to explain, from a development perspective, '''how to implement''' the backup feature for various Moodle 2.x plugins, mainly, modules and blocks.

Note that, at the time of writing this, the backup & restore subsystem itself is '''under development''', so still there are some missing bits, specially about the way to handle '''subplugins''' (question types, data fields...) under the new backup infrastructure, so any module using such artifacts, like data, assignment, quiz, workshop, aren't good candidates right now. This will be addressed (and this Docs updated) once we have determined how each subplugin is expected to work (from a DB / backup perspective).

Everything in backup '''is about tasks and steps''' (see [[Backup 2.0 general architecture|Backup 2.0 general architecture]] for more information), all them conforming one backup plan. Each module instance and each block instance will be backup by one backup task instance that is, basically, one collection of backup steps. How steps are organized within the task will dictate to the backup system what to do and in which order.

Another important point is that Moodle backup 2.0, supports '''multiple backup formats''' ("moodle2", "imscc"...) each one having its own tasks/steps, completely unrelated between them. In any case, for now, we are focusing all the explanations below in the "moodle2" format, that is the one required in order to keep any module/block '''transportable between Moodle instances''' without any loss of data. Surely, for the rest of formats, we'll end with other documents describing them, since each one can have its own particularities.

Talking about backup steps we must differentiate '''two type of steps''':

* '''Execution steps''': That, simply, execute arbitrary PHP code. They are useful to prepare different structures, create directories, whatever have to be done not involving the generation of XML files. Normally you won't need them.
* '''Structure steps''': That, using one PHP API (detailed below) define completely the XML structure to be exported and its contents. Hopefully, "normal" modules only will have to use one step of this type in order to have the backup functionality 100% implemented.

Said that, in the next steps we are going through all the steps necessary to create the backup of one simple module and one block, in order to get all the possibilities covered.

== How to backup one module ==

For this section, we have selected one simple module (choice) that requires practically all the backup "machinery" to be used, so it will get explained as we progress in the development. The only point not covered here are the "subplugin" facilities, covered later in a separate section.

=== Prerequisites ===

In order to achieve the backup implementation for the module, some prerequisites should be fulfilled. They are default recommendations that are especially helpful while getting used to the backup process.

# '''Learn about the module'''. If you aren't the creator of the module, spend some time playing with the module, creating and using it, exploring each one of its functionalities. By doing this you will end with some "real" data in the module instances that will be really useful when testing / debugging how the module backup is being generated.
# '''Draw one schema of the module''' DB structures. While you are playing with the module, look continuously to the DB, how records are saved and what the relationships are between the module's tables. Since a backup is, basically, one "selective dump" of those tables, knowing the maximum about them is highly recommended. At the end, you must end with one tree structure will be the basis for the generated XML file.
# '''Annotate which tables contain user-related info''' and which ones don't. One of the core functionalities that must be present on each module is the ability to include user related information or skip it, as you will need that information later.

'''Tip''': If the module already existed before Moodle 2.0, it can be a '''good idea''' to look at its 1.9 backuplib.php file, since the structure is already defined there and can help to understand the organization better and, at the same time, '''keeping the XML structure as similar as possible''', that will, definitively, '''make things easier''' when converting 1.9 backup files to the new backup 2.0 format.

'''Note''': It's important to highlight that the structure schema, should be as stable as possible moving forward, because any change in the structure makes restore much more complex to implement. There aren't problems with adding/deleting fields, nor adding new elements to the structure. '''The structure (tree) itself must persist as stable as possible''', so be careful when deciding it, as it will have implications on future maintenance.

Applying these pre-requisites to our candidate module (choice), here it's the corresponding schema. We'll use it along the whole process.

=== Schema ===

In the schema, you must try to put as much information as possible, so that will produce the coding process later to be quicker and easier while keeping the final results free from errors and missing bits. So, once more, don't start coding immediately, instead spend some time with the requisites above, understanding how the module works and designing the final structure that represents it better.

==== The (correct) candidate ====

[[Image:Backup20 choice alt.png‎|left|Alternative choice backup structure]]

The tree on the left shows the ER/DB structure of the choice module, where one choice have one or more options and each option is answered by users one or more times (note: ignore cardinality accuracy in the previous phrase).

And that's the best schema representing the structure of the module, with each element properly nested so, we won't have any problem with restore since the order required by restore (1, 2, 3) are naturally given.

Looks easy, cool, but continue reading… you will get surprised! :-) 

==== The (chosen) candidate ====

Instead we are going to use the (complete this time) diagram below. See the rationale about that after the image.

[[Image:Backup20 choice.png‎|center|Used choice backup structure]]

The main reason to use this tree (instead of the "correct" one) is that this is the structure that has been used by Moodle 1.9 backup since ages ago for the choice module and, of course have done its work ok. As commented above we must '''try to reduce the number of structural changes''' in one module backup in order to keep the restore operations working along the time (the same is applicable for the conversion of 1.9 backup files to the new 2.0 format). Finally, this is a good example about how one module '''can have different XML representations''' and we need to try to get that best one (this is not the case) on each case. So, once more, '''spending some time analyzing''' the activity is worth it.

Let's analyze the schema with some detail:

* '''Detecting user information''': We must be able to define the entities (tables) in the diagram that are used to store user information. One of the core features of the backup subsystem since its early days have been the ability to produce backup with and without user information. So we need that info. Hence, the "no user info" in the choice and choice_options elements (they are configuration, user-independent), while the choice_answers is marked as "user info" (contains user's answers to the choice).

* '''Determining the correct order of backup''': This, while simple, is critical too (especially from a restore perspective). Since the restore reads progressively the xml file and performs actions in that order, we '''must guarantee that the "read order" is the correct''' one, fulfilling any possible dependency. Back to our schema it's clear that we need to backup the "choice" element at first, and then the "choice_options" and "choice_answers" ones. Moreover, the "choice_options" must be backup before "choice_answers", since the later needs to save the values of the former (the "optionid" information). Note that, as commented some paragraphs above, the "correct" alternative really gave us that order information easily. Doesn't matter, since we have been able to establish it also in the "chosen" schema.

* '''Attributes and elements''': Now it's time to decide which fields will be considered attributes in the resulting XML file and which ones will be child elements (tags). The rule is simple: '''All the "id" fields must (should) be defined as attributes'''. Note this is just one arbitrary rule without much rationale behind it since, from a restore perspective, everything (attributes and child tags) will be handled in the same way (object attributes). So, in our schema, all the "id" fields have been marked as "attr".

* '''Not needed elements''': If we have designed the schema properly, we'll find that some fields aren't necessary, since such information is already included in some parent element. In our schema, the field "choiceid", pointing to the "choice->id", both in the options and in the answer elements, have been marked as "not needed" since their parent "choice" already contains it. Something similar happens with the "course" field in the choice element. It doesn't need to be included in the backup file since something above it (course element, outside the module scope) already has it defined. Finally, there is one element marked as "needed" that shows us, once more, that the schema we are using is not the best. Since "choice_answers" isn't nested under "choice_options", we must keep the "choice_answers->optionid" field in the backup, or restore won't know to which option each answer belongs to. Instead, with the "correct" schema, where answers are nested under options, that field is not needed. Summarizing, '''any field except those already existing in parent elements must be included in backup'''.

* '''Detecting file areas used by the module''': Along the module we can be using various file areas in different elements and fields. We need to know exactly which file area is handled by which element and the (optional) itemid information used for that file area. In general, '''anything being one text field, or anything looking like one attachment''' has high chances to have one (hidden) file area associated. In our schema, we have one file area (choice_intro) corresponding to the introduction of the module and available to put any images or whatever in that field. Also, in general, all the "xxx_intro" file areas use to have no itemid, since the module's context is enough to define them without ambiguities. So, we mark the choice->intro as "choice_intro" file area and "no itemid"). From our expertise playing with the module we know there are no more file areas associated with this module.

* '''Annotating some important bits''': Due to the modularity of the backup and in order to know exactly which information must be saved (because it's used) and which one can be skipped, '''it's important to annotate some important elements along the whole backup''' process. So, back to our schema, we have marked the "choice_answer->userid" field as "annotation" (so backup will, automatically, add all the information for that user). Here it's the list of elements that we must not forget to annotate (or we could end with non-restorable backups). Note that we must, always, be annotating "id" values and not other types of data:
** '''user''': Any field pointing to one user->id present along the schema (as said above, our schema has one).
** '''grouping''': Any field pointing to one grouping->id
** '''group''': Any field pointing to one group->id
** '''role''': Any field pointing to one role->id
** '''scale''': Any field pointing to one scale->id
** '''outcome''': Any field pointing to one outcome->id

And this is all the information we need to know, before starting to code. Surely, once used to backup and restore, you will be able to start coding sooner, but '''don't forget about the importance of choosing one good and stable structure''' before anything else. It's really the critical part of any module's backup.

That said, let's see how to code all this information in order to get one cool backup for our beloved module.

=== Coding ===

Already here? Have you read, at least once, all the explanations and comments in the previous sections? Yes? Sure? I can imagine it's hard to read so much text, just imagine how hard is to write it! Go, go, go and read it!

Jokes aside, in this section we are going to code the module's (choice, in our example) backup code. As you'll see soon, all the information gathered in previous steps is really important and will make the coding task easier and less prone to errors.

==== Setting up the environment ====

By default, any backup operation will end with one .zip file stored in some course / section / activity area. That means that, each time you execute one backup, you'll need to go across the web interface to that file area, download the generated .zip file, uncompress it, and then see how things have been generated. And you will be executing a bunch of backup files until you get everything working as expected, so the whole develop / test process isn't really "agile". To improve things a bit, there is one $CFG setting that you should consider using '''in your development environment'''. Just put this in your config.php:

<syntaxhighlight lang="php">
$CFG->keeptempdirectoriesonbackup = true;
</syntaxhighlight>

With this setting enabled, backup won't delete the temporary directory where everything is calculated, so you will be able to access to it directly, skipping all the ui / download / unzip steps above. Those temp directories are under $CFG->dataroot/temp/backup. Note that, for each backup invocation, a new directory is created.

Also, in order to be able to execute backups quickly (instead of navigating along the UI), you can, simply, put one script like this in your $CFG->dirroot directory:

<syntaxhighlight lang="php">
<?php

define('CLI_SCRIPT', 1);
require_once('config.php');
require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');

$course_module_to_backup = XX; // Set this to one existing choice cmid in your dev site
$user_doing_the_backup = YY; // Set this to the id of your admin account

$bc = new backup_controller(backup::TYPE_1ACTIVITY, $course_module_to_backup, backup::FORMAT_MOODLE,
backup::INTERACTIVE_NO, backup::MODE_GENERAL, $user_doing_the_backup);
$bc->execute_plan();
</syntaxhighlight>

Just set proper values for XX and YY above and execute it from the command line. If you get one error about one not found class (with the name of your module) everything is ok.

To get the analogous restore code please see: https://docs.moodle.org/dev/Restore_2.0_for_developers#Automatically_triggering_restore_in_code

==== Required stuff ====

The first thing you need to make is to, explicitly, declare that your module (choice in our example) is going to support the MOODLE2 backup format, to do so, you need to go to mod/choice/lib.php and, in the choice_supports() function add one new feature by adding this line:

<syntaxhighlight lang="php">
case FEATURE_BACKUP_MOODLE2: return true;
</syntaxhighlight>

If you execute another backup (with the script provided above, you will continue getting one error, since we haven't still coded anything related to backup, that's ok.

Next step is to create the directory where all the backup code for the choice module will be. Just create the directory(s) mod/choice/backup/moodle2

At this point, we have all the required stuff ready and all the pending tasks will be done under that recently created directory.

==== Settings, Steps and Tasks ====

In the introduction of the tutorial, we commented about backup being structured into tasks, each one being one collection of steps (and potentially using some custom settings). Those are, exactly, the objects that we need to create to achieve the backup functionality in our module.

First of all, lets' create the settings file, where all the custom settings to be used by our module will be defined and implemented. It must be named '''mod/choice/backup/moodle2/backup_choice_settingslib.php''' and their contents are really meaningful:

<syntaxhighlight lang="php">
<?php

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

/**
* @package moodlecore
* @subpackage backup-moodle2
* @copyright 2010 onwards YOUR_NAME_GOES_HERE {@link YOUR_URL_GOES_HERE}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// This activity has not particular settings but the inherited from the generic
// backup_activity_task so here there isn't any class definition, like the ones
// existing in /backup/moodle2/backup_settingslib.php (activities section)
</syntaxhighlight>

Looks simple, isn't it? Nothing but a few comments. This is looking really easy. For now, we aren't going to introduce any custom setting for any module, only the "core activity settings" will be used. Once backup and Moodle 2.0 is stable we can start analyzing useful settings to customize how the module's backup is performed. For now, just leave it blank, please. In fact, if it's empty,''' you can safely not create it''' at all. It's here just for explanation purposes.

Side note: To save some space, we only will be showing the © message/license in the code above. Just add it to each file created.

Now we are going to create the steps file, where all the steps to be executed by our backup activity task will be defined and implemented. It must be named '''mod/choice/backup/moodle2/backup_choice_stepslib.php''' and their contents are these:

<syntaxhighlight lang="php">
<?php

/**
* Define all the backup steps that will be used by the backup_choice_activity_task
*/
</syntaxhighlight>

Yes, it's another empty file. No worries we'll fill it later.

Finally we need to create the task file, where our just created settings and steps files will be included and used. It must be named '''mod/choice/backup/moodle2/backup_choice_activity_task.class.php''' and their contents are these:

<syntaxhighlight lang="php">
<?php

require_once($CFG->dirroot . '/mod/choice/backup/moodle2/backup_choice_stepslib.php'); // Because it exists (must)
require_once($CFG->dirroot . '/mod/choice/backup/moodle2/backup_choice_settingslib.php'); // Because it exists (optional)

/**
* choice backup task that provides all the settings and steps to perform one
* complete backup of the activity
*/
class backup_choice_activity_task extends backup_activity_task {

/**
* Define (add) particular settings this activity can have
*/
protected function define_my_settings() {
// No particular settings for this activity
}

/**
* Define (add) particular steps this activity can have
*/
protected function define_my_steps() {
// Choice only has one structure step
}

/**
* Code the transformations to perform in the activity in
* order to get transportable (encoded) links
*/
static public function encode_content_links($content) {
return $content;
}
}
</syntaxhighlight>

This is the main file (class) of the choice backup and it will be used to define any setting (define_my_settings() method) and any step (define_my_steps() method) to be executed in the backup process. It also contains one 3rd method (encode_content_links($content)) that will allow manually URLs pointing to the choice to be properly converted when the choice is moved to other site / course using the backup / restore functionality.

As you see, for now, the three required methods are doing nothing. Just execute the backup again. Wow, no errors anymore. We have already fulfilled all the minimum coding needs in order to have the choice backup working.

Now you should go to your $CFG->dataroot/temp/backup/xxxx directory (the more recent) and spend some time looking what has been created under the activities/choice_XX directory. There is already a lot of stuff that backup has generated for you: comments, blocks, logs, grades, module info, roles... some of them empty and others already showing real information.

In any case, now, we need to add one important file there, the "choice.xml" where the real information for your module will be present, following the specs given by the schema we decided some sections above.

So, let's go, it's time to create our choice structure step. To do so, we edit the '''mod/choice/backup/moodle2/backup_choice_stepslib.php''' file and add this code after the existing comments:

<syntaxhighlight lang="php">
/**
* Define the complete choice structure for backup, with file and id annotations
*/
class backup_choice_activity_structure_step extends backup_activity_structure_step {

protected function define_structure() {

// To know if we are including userinfo
$userinfo = $this->get_setting_value('userinfo');

// Define each element separated

// Build the tree

// Define sources

// Define id annotations

// Define file annotations

// Return the root element (choice), wrapped into standard activity structure

}
}
</syntaxhighlight>

So, we have defined one structure step that will be the responsible, using one PHP API to provide backup with all the information needed to generate the choice.xml file. Now, go back to the task file and add these contents in the define_my_steps() methods:

<syntaxhighlight lang="php">
$this->add_step(new backup_choice_activity_structure_step('choice_structure', 'choice.xml'));
</syntaxhighlight>

That way, our choice task knows it must execute one new step, the one involving the generation of the choice.xml file. Let's execute one new backup and see results.You should be getting one new error with something like that "backup_structure_step_wrong_structure". It means that everything is ok up to now, the task has tried to execute the structure step, but this is not properly defined.

===== Defining each element =====

So, next step is about to define the choice structure. Going back to our step, under the ''// Define each element separate'' comment we'll add this code:

<syntaxhighlight lang="php">
$choice = new backup_nested_element('choice', array('id'), array(
'name', 'intro', 'introformat', 'publish',
'showresults', 'display', 'allowupdate', 'allowunanswered',
'limitanswers', 'timeopen', 'timeclose', 'timemodified'));

$options = new backup_nested_element('options');

$option = new backup_nested_element('option', array('id'), array(
'text', 'maxanswers', 'timemodified'));

$answers = new backup_nested_element('answers');

$answer = new backup_nested_element('answer', array('id'), array(
'userid', 'optionid', 'timemodified'));
</syntaxhighlight>

===== Return the root element =====

And also, in order to get it working, let's define the return element, so, after the ''// Return the root element'' comment, add this code:

<syntaxhighlight lang="php">
return $this->prepare_activity_structure($choice);
</syntaxhighlight>

Now we can execute the backup again and, as long as we have already defined the root element of the module, should have now one choice.xml file created (without proper contents but must be there).

About the code above, all we have done is to define, separately each element that will be part of the choice.xml file. Special note about the $options and $answers elements. Since Moodle 1.9 we use to enclose real elements (the singular ones) inside one extra plural element, hence we create them here (as empty elements without attributes nor child tags). About the rest (the singular ones) we use 3 params in the instantiation:
* The name of the element
* One array of attributes of the element
* One array of child tags (fields) of the element.
And we include all the fields that previously we had defined in our schema '''but''' the ones marked as '''not needed'''.

===== Building the tree =====

Now it's time to declare the relations between all those elements, so, after the ''// Build the tree'' comment we'll add this code:

<syntaxhighlight lang="php">
$choice->add_child($options);
$options->add_child($option);

$choice->add_child($answers);
$answers->add_child($answer);
</syntaxhighlight>

Self explanatory, using $choice as root element, we define the whole tree using the add_child() method. And, of course, we respect '''the order''' that we had decided, so $options will be '''physically''' before $answers in the tree (and in the generated XML).

===== Defining the sources =====

After this, it's the moment to instruct our tree about how to fetch information from DB in order to generate the choice.xml file, so after the ''// Define sources'' comment, we'll add this code:

<syntaxhighlight lang="php">
$choice->set_source_table('choice', array('id' => backup::VAR_ACTIVITYID));

$option->set_source_sql('
SELECT *
FROM {choice_options}
WHERE choiceid = ?',
array(backup::VAR_PARENTID));

// All the rest of elements only happen if we are including user info
if ($userinfo) {
$answer->set_source_table('choice_answers', array('choiceid' => '../../id'));
}
</syntaxhighlight>

So we define the source for the $choice element as the information present in the 'choice' table for the id that is being backup (backup::VAR_ACTIVITYID). Or we define the source for the $option element like one SQL (could have been one table too, just to show more possibilities of the API, using the parent (the choice one) as value for the query (backup::VAR_PARENTID).

And finally, conditionally, if user information is going to be included, we define the source for the $answer (note we had already annotated in our schema that this element was dependent of that).

And we define the source condition as having the 'choiceid' field matching the value of the 'id' field two levels above (../../id). If you follow the tree created in the previous code section, that's exactly the choice->id (remember we have introduced one extra level (the plural one between the 'choice' and the 'answer' singular elements). Note this is 100% equivalent to use backup::VAR_PARENTID (as we have done in the $option source) just used to show possibilities of the API.

Summarizing, with the API, we have these 3 method for defining sources:

* '''set_source_table($tablename, array $conditions)''': When the information is get straight from one table (vast majority of cases in backup)
* '''set_source_sql($sql, array $params)''': When the information doesn't map one table directly and we need something more complex
* '''set_source_array($array)''': When we have some fixed information to backup. Not really useful in nested information, but used by core here and there.

Note that both the $conditions and $params above only accept one limited number of constants or values (not all available in all backups!), mainly:

* '''backup::VAR_COURSEID''': The id of the course this activity belongs to / the course id being backup
* '''backup::VAR_SECTIONID''': The id of the section this activity belongs to / the section id being backup
* '''backup::VAR_ACTIVITYID''': The id of the activity id being backup
* '''backup::VAR_MODID''': The id of the course_module being backup
* '''backup::VAR_MODULENAME''': The name of the module being backup
* '''backup::VAR_BLOCKID''': The id of the block being backup
* '''backup::VAR_BLOCKNAME''': The name of the block being backup
* '''backup::VAR_CONTEXTID''': The context id of the activity / course being backup
* '''backup::VAR_PARENTID''': The value of the first parent id found in the structure.
* '''../some/path/to/parent''': To manually point to other value of any parent.

Is important to note that, in 99% of the case we should be using, exclusively, some of the constants above, and backup, automatically will handle them properly. In case we have any other condition or param to be added like, for example, the number 23, or the string 'user', we cannot add them directly, but enclose them with the helper '''backup_helper::is_sqlparam(23)''' or '''backup_helper::is_sqlparam('user')'''. That way backup will know they are raw SQL params not needing any special handling, like the constants above.

Well, now it's time to run backup again and take a look to our activities/choice_XX/choice.xml file. Now everything should be there, properly nested, the choice, the options and the answers. We are really near finishing now.

===== Annotating IDs =====

Now it's time to perform all the annotations that we had already detected in our analysis of the module. So, after the ''// Define id annotations'' comment we'll be adding:

<syntaxhighlight lang="php">
$answer->annotate_ids('user', 'userid');
</syntaxhighlight>

It simply means, annotate for each $answer element, the value of the 'userid' field as one 'user' to be backup. In other words we are instructing backup that there is one new user to include later, when generating the users information and, at the same time, we are determining that those users are needed for the choice XX, so, if on restore we decide to skip that choice and such user isn't necessary for any other module / subsystem, it won't be restored. All this "uses" information is handled by the "inforef.xml" files within each activity backup, just in case you're interested to take a look to them. Else, just consider them, "dark magic".

'''Note''': If you're not sure about which elements must be annotated, review [[Backup 2.0 for developers #annotate_is_important|"Annotating some important bits"]] above for details about '''must-be-done''' annotations.

===== Annotating files =====

And, finally, reviewing our elaborate and detailed schema, the last thing we need to take care of are the file areas used, so, after the ''// Define file annotations'' comment we'll add:

<syntaxhighlight lang="php">
$choice->annotate_files('mod_choice', 'intro', null, $contextid = null); // This file area does not have an itemid.
</syntaxhighlight>

That means that, within the $choice element we have one file area in use, of course belonging to the 'mod_choice' component (where all the choice module files belong to), named 'intro' and not using itemid (null). Note that, since it is possible to have multiple file areas in the same element (table), you may end up having multiple calls to the annotate_files() method, one for each filearea to be added to backup. The third parameter, if it is needed, must be the name of one of the attributes or fields of the $choice element (usually, in the vast majority of cases, the 'id' of the element), otherwise we'll use null. The fourth parameter is optional and will default to the context id of the backup, but if you want to specify the context id you do so here.

=== One encoded wor(l)d ===

Already out from the step definition, that should be working ok now, with the choice.xml file being generated and all the annotations being processed and added to the inforef.xml file, there is one more point to fulfill before considering choice's backup 100% finished.

And it's about how to provide the ability to transform some links to the choice module when the backup file is restored into another server / course. That is automatically handled by a two-step approach:
# On backup, we transform as many well-know URLs as possible to one encoded form.
# On restore, we transform those encoded URLS back to their original form, but pointing to their new targets.

So, in backup, we must provide services for the point 1 above, and that is done by adding some "encoding" conversions to the '''encode_content_links()''' method in our '''backup_choice_activity_task'''. So, define it to look like this

<syntaxhighlight lang="php">
/**
* Code the transformations to perform in the activity in
* order to get transportable (encoded) links
*/
static public function encode_content_links($content) {
global $CFG;

$base = preg_quote($CFG->wwwroot,"/");

// Link to the list of choices
$search="/(".$base."\/mod\/choice\/index.php\?id\=)([0-9]+)/";
$content= preg_replace($search, '$@CHOICEINDEX*$2@$', $content);

// Link to choice view by moduleid
$search="/(".$base."\/mod\/choice\/view.php\?id\=)([0-9]+)/";
$content= preg_replace($search, '$@CHOICEVIEWBYID*$2@$', $content);

return $content;
}
</syntaxhighlight>

Básically, it gets any URL (manually written) in any content of the backup being generated and transform some (well-known) URLs to one encoded alternative. In this case we are encoding:
* Any URL pointing to the list of choices in a course == is changed to ==> $@CHOICEINDEX*XX@$
* Any URL pointing to one exact choice == is changed to ==> $@CHOICEVIEWBYID*YY@$

In restore, well have the opposite conversions happening, replacing the XX and YY above to their new equivalents, so those links will be transportable via backup/restore without any need to edit them manually later.

Tip: Don't forget to look to the module's 1.9 backup code, as far as there you'll find which conversions must be considered to be added here.

=== Final notes ===

* Don't get stressed, it's really more difficult / longer to explain than to do it. 100% guaranteed, else we'll return your money. :-P
* If you've become lost, or your code is not working properly, you always can [https://github.com/moodle/moodle/tree/master/mod/choice/backup/moodle2 see the complete choice working code in git]. Or, alternatively, look to other well known modules, like [https://github.com/moodle/moodle/blob/master/mod/forum/backup/moodle2/ forum] or also the [https://github.com/moodle/moodle/blob/master/backup/moodle2/backup_stepslib.php big core library of steps], where you will find all sort of uses of the API.
* If you are going to implement backup for module XXXX, just copy this document, replace any "choice" occurrence within it by XXXX and follow it from the beginning to the end. Should work.
* If the module already existed in Moodle 1.x, try to follow the same structure if possible, that will make things easier for restore / conversion.
* Right now there are some pending tasks related with different exceptions that will be thrown if you code something wrongly (bad nesting, incorrect field names, bad constant/sql param uses...) and how they are shown. Fix for that will be coming soon.
* Also, as stated at the beginning of this tutorial, we are still missing "subplugins" final support in modules, so try to avoid implementing backup on them for now. Once ready, there will be one new section in this document about them.
* Any question / improvement / comment, feel free to contact with Moodle HQ, better if using the Tracker or, alternatively, forums / email / direct contact with your very-best-developer-friend. Note this is version x.0 (dot zero) of the backup API, so sure there are possibilities to improve it along the time.

== Other components that can be backed up ==

Most plugins which can be added to a course can also include data in a course backup. Some examples:

* Course formats
* Themes: [[ Backup 2.0 theme data| Backup 2.0 theme data]]
* Plagiarism plugins

How to fix gradebook issues

2021-08-11T14:53:40Z

Moodlebot: Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

==How to fix Grade book issues==

There has been a policy decision that any fixes to the grade book must not result in any changes to grades. Some fixes may result in grades being changed and in these situations we need to freeze the grade book and let the teacher / admin / higher power agree to applying the change.

For future fixes to the grade book we will be putting revision numbers and nested code into the grade book libraries.

===Fixing the issue===

Choose a freeze number that is greater than the current build number but will be less than the next build number.

When making changes wrap your code in an if statement.

example:
<syntaxhighlight lang="php">
$gradebookcalculationsfreeze = get_config('core', 'gradebook_calculations_freeze_' . $courseid);
// Stick with the original code if the grade book is frozen.
if ($gradebookcalculationsfreeze && (int)$gradebookcalculationsfreeze <= {your code freeze number}) {
{original code goes here}
} else {
{new fixed code goes here}
}
</code>
Enter in details about your fix at https://docs.moodle.org/29/en/Gradebook_calculation_changes

===Upgrade code===

Code will be required to determine if the site being upgraded is affected. If so then it should be flagged to be frozen.

example (lib/db/upgrade.php):
<syntaxhighlight lang="php">
if ($oldversion < 2015062500.01) {
// MDL-48239. Changed calculated grade items so that the maximum and minimum grade can be set.

// If the changes are accepted and a regrade is done on the gradebook then some grades may change significantly.
// This is here to freeze the gradebook in affected courses.

// This script is included in each major version upgrade process so make sure we don't run it twice.
if (empty($CFG->upgrade_calculatedgradeitemsignored)) {
upgrade_calculated_grade_items();

// To skip running the same script on the upgrade to the next major release.
set_config('upgrade_calculatedgradeitemsignored', 1);
}

// Main savepoint reached.
upgrade_main_savepoint(true, 2015062500.01);
}
</code>
The code for doing this check should be located in lib/db/upgradelib.php so that it can also be run when a course is being restored.

===New installations===

Make sure to not run the upgrade step with the new installation

example (lib/db/install.php:: xmldb_main_install() line 135):
<syntaxhighlight lang="php">
'upgrade_calculatedgradeitemsignored' => 1, // New installs should not run this upgrade step.
</code>

===Restoration code===

Code should be generated so that a regrading of the gradebook will fix the problem. Any solution that requires direct alteration of the grades in the database will result in an extremely complex set of restore code.

example (backup/moodle2/restore_stepslib.php):
<syntaxhighlight lang="php">
// Calculated grade items need recalculating for backups made between 2.8 release (20141110) and the fix release (20150627).
if (!$gradebookcalculationsfreeze && $backupbuild >= 20141110 && $backupbuild < 20150627) {
require_once($CFG->libdir . '/db/upgradelib.php');
upgrade_calculated_grade_items($this->get_courseid());
}
</code>
===Tests===

Create a behat test to make sure that when the gradebook is frozen that grades are not changed.
Create a behat test to make sure that when the gradebook is not frozen that the issue is solved.

Create unit tests to check functions in the upgradelib.php file.

Backup 2.0 for developers

2021-08-11T14:53:37Z

Moodlebot: Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

{{Template:Backup 2.0}}{{Moodle_2.0}}{{Work in progress}}

== Introduction ==

This page tries to explain, from a development perspective, '''how to implement''' the backup feature for various Moodle 2.x plugins, mainly, modules and blocks.

Note that, at the time of writing this, the backup & restore subsystem itself is '''under development''', so still there are some missing bits, specially about the way to handle '''subplugins''' (question types, data fields...) under the new backup infrastructure, so any module using such artifacts, like data, assignment, quiz, workshop, aren't good candidates right now. This will be addressed (and this Docs updated) once we have determined how each subplugin is expected to work (from a DB / backup perspective).

Everything in backup '''is about tasks and steps''' (see [[Backup 2.0 general architecture|Backup 2.0 general architecture]] for more information), all them conforming one backup plan. Each module instance and each block instance will be backup by one backup task instance that is, basically, one collection of backup steps. How steps are organized within the task will dictate to the backup system what to do and in which order.

Another important point is that Moodle backup 2.0, supports '''multiple backup formats''' ("moodle2", "imscc"...) each one having its own tasks/steps, completely unrelated between them. In any case, for now, we are focusing all the explanations below in the "moodle2" format, that is the one required in order to keep any module/block '''transportable between Moodle instances''' without any loss of data. Surely, for the rest of formats, we'll end with other documents describing them, since each one can have its own particularities.

Talking about backup steps we must differentiate '''two type of steps''':

* '''Execution steps''': That, simply, execute arbitrary PHP code. They are useful to prepare different structures, create directories, whatever have to be done not involving the generation of XML files. Normally you won't need them.
* '''Structure steps''': That, using one PHP API (detailed below) define completely the XML structure to be exported and its contents. Hopefully, "normal" modules only will have to use one step of this type in order to have the backup functionality 100% implemented.

Said that, in the next steps we are going through all the steps necessary to create the backup of one simple module and one block, in order to get all the possibilities covered.

== How to backup one module ==

For this section, we have selected one simple module (choice) that requires practically all the backup "machinery" to be used, so it will get explained as we progress in the development. The only point not covered here are the "subplugin" facilities, covered later in a separate section.

=== Prerequisites ===

In order to achieve the backup implementation for the module, some prerequisites should be fulfilled. They are default recommendations that are especially helpful while getting used to the backup process.

# '''Learn about the module'''. If you aren't the creator of the module, spend some time playing with the module, creating and using it, exploring each one of its functionalities. By doing this you will end with some "real" data in the module instances that will be really useful when testing / debugging how the module backup is being generated.
# '''Draw one schema of the module''' DB structures. While you are playing with the module, look continuously to the DB, how records are saved and what the relationships are between the module's tables. Since a backup is, basically, one "selective dump" of those tables, knowing the maximum about them is highly recommended. At the end, you must end with one tree structure will be the basis for the generated XML file.
# '''Annotate which tables contain user-related info''' and which ones don't. One of the core functionalities that must be present on each module is the ability to include user related information or skip it, as you will need that information later.

'''Tip''': If the module already existed before Moodle 2.0, it can be a '''good idea''' to look at its 1.9 backuplib.php file, since the structure is already defined there and can help to understand the organization better and, at the same time, '''keeping the XML structure as similar as possible''', that will, definitively, '''make things easier''' when converting 1.9 backup files to the new backup 2.0 format.

'''Note''': It's important to highlight that the structure schema, should be as stable as possible moving forward, because any change in the structure makes restore much more complex to implement. There aren't problems with adding/deleting fields, nor adding new elements to the structure. '''The structure (tree) itself must persist as stable as possible''', so be careful when deciding it, as it will have implications on future maintenance.

Applying these pre-requisites to our candidate module (choice), here it's the corresponding schema. We'll use it along the whole process.

=== Schema ===

In the schema, you must try to put as much information as possible, so that will produce the coding process later to be quicker and easier while keeping the final results free from errors and missing bits. So, once more, don't start coding immediately, instead spend some time with the requisites above, understanding how the module works and designing the final structure that represents it better.

==== The (correct) candidate ====

[[Image:Backup20 choice alt.png‎|left|Alternative choice backup structure]]

The tree on the left shows the ER/DB structure of the choice module, where one choice have one or more options and each option is answered by users one or more times (note: ignore cardinality accuracy in the previous phrase).

And that's the best schema representing the structure of the module, with each element properly nested so, we won't have any problem with restore since the order required by restore (1, 2, 3) are naturally given.

Looks easy, cool, but continue reading… you will get surprised! :-) 

==== The (chosen) candidate ====

Instead we are going to use the (complete this time) diagram below. See the rationale about that after the image.

[[Image:Backup20 choice.png‎|center|Used choice backup structure]]

The main reason to use this tree (instead of the "correct" one) is that this is the structure that has been used by Moodle 1.9 backup since ages ago for the choice module and, of course have done its work ok. As commented above we must '''try to reduce the number of structural changes''' in one module backup in order to keep the restore operations working along the time (the same is applicable for the conversion of 1.9 backup files to the new 2.0 format). Finally, this is a good example about how one module '''can have different XML representations''' and we need to try to get that best one (this is not the case) on each case. So, once more, '''spending some time analyzing''' the activity is worth it.

Let's analyze the schema with some detail:

* '''Detecting user information''': We must be able to define the entities (tables) in the diagram that are used to store user information. One of the core features of the backup subsystem since its early days have been the ability to produce backup with and without user information. So we need that info. Hence, the "no user info" in the choice and choice_options elements (they are configuration, user-independent), while the choice_answers is marked as "user info" (contains user's answers to the choice).

* '''Determining the correct order of backup''': This, while simple, is critical too (especially from a restore perspective). Since the restore reads progressively the xml file and performs actions in that order, we '''must guarantee that the "read order" is the correct''' one, fulfilling any possible dependency. Back to our schema it's clear that we need to backup the "choice" element at first, and then the "choice_options" and "choice_answers" ones. Moreover, the "choice_options" must be backup before "choice_answers", since the later needs to save the values of the former (the "optionid" information). Note that, as commented some paragraphs above, the "correct" alternative really gave us that order information easily. Doesn't matter, since we have been able to establish it also in the "chosen" schema.

* '''Attributes and elements''': Now it's time to decide which fields will be considered attributes in the resulting XML file and which ones will be child elements (tags). The rule is simple: '''All the "id" fields must (should) be defined as attributes'''. Note this is just one arbitrary rule without much rationale behind it since, from a restore perspective, everything (attributes and child tags) will be handled in the same way (object attributes). So, in our schema, all the "id" fields have been marked as "attr".

* '''Not needed elements''': If we have designed the schema properly, we'll find that some fields aren't necessary, since such information is already included in some parent element. In our schema, the field "choiceid", pointing to the "choice->id", both in the options and in the answer elements, have been marked as "not needed" since their parent "choice" already contains it. Something similar happens with the "course" field in the choice element. It doesn't need to be included in the backup file since something above it (course element, outside the module scope) already has it defined. Finally, there is one element marked as "needed" that shows us, once more, that the schema we are using is not the best. Since "choice_answers" isn't nested under "choice_options", we must keep the "choice_answers->optionid" field in the backup, or restore won't know to which option each answer belongs to. Instead, with the "correct" schema, where answers are nested under options, that field is not needed. Summarizing, '''any field except those already existing in parent elements must be included in backup'''.

* '''Detecting file areas used by the module''': Along the module we can be using various file areas in different elements and fields. We need to know exactly which file area is handled by which element and the (optional) itemid information used for that file area. In general, '''anything being one text field, or anything looking like one attachment''' has high chances to have one (hidden) file area associated. In our schema, we have one file area (choice_intro) corresponding to the introduction of the module and available to put any images or whatever in that field. Also, in general, all the "xxx_intro" file areas use to have no itemid, since the module's context is enough to define them without ambiguities. So, we mark the choice->intro as "choice_intro" file area and "no itemid"). From our expertise playing with the module we know there are no more file areas associated with this module.

* '''Annotating some important bits''': Due to the modularity of the backup and in order to know exactly which information must be saved (because it's used) and which one can be skipped, '''it's important to annotate some important elements along the whole backup''' process. So, back to our schema, we have marked the "choice_answer->userid" field as "annotation" (so backup will, automatically, add all the information for that user). Here it's the list of elements that we must not forget to annotate (or we could end with non-restorable backups). Note that we must, always, be annotating "id" values and not other types of data:
** '''user''': Any field pointing to one user->id present along the schema (as said above, our schema has one).
** '''grouping''': Any field pointing to one grouping->id
** '''group''': Any field pointing to one group->id
** '''role''': Any field pointing to one role->id
** '''scale''': Any field pointing to one scale->id
** '''outcome''': Any field pointing to one outcome->id

And this is all the information we need to know, before starting to code. Surely, once used to backup and restore, you will be able to start coding sooner, but '''don't forget about the importance of choosing one good and stable structure''' before anything else. It's really the critical part of any module's backup.

That said, let's see how to code all this information in order to get one cool backup for our beloved module.

=== Coding ===

Already here? Have you read, at least once, all the explanations and comments in the previous sections? Yes? Sure? I can imagine it's hard to read so much text, just imagine how hard is to write it! Go, go, go and read it!

Jokes aside, in this section we are going to code the module's (choice, in our example) backup code. As you'll see soon, all the information gathered in previous steps is really important and will make the coding task easier and less prone to errors.

==== Setting up the environment ====

By default, any backup operation will end with one .zip file stored in some course / section / activity area. That means that, each time you execute one backup, you'll need to go across the web interface to that file area, download the generated .zip file, uncompress it, and then see how things have been generated. And you will be executing a bunch of backup files until you get everything working as expected, so the whole develop / test process isn't really "agile". To improve things a bit, there is one $CFG setting that you should consider using '''in your development environment'''. Just put this in your config.php:

<syntaxhighlight lang="php">
$CFG->keeptempdirectoriesonbackup = true;
</code>

With this setting enabled, backup won't delete the temporary directory where everything is calculated, so you will be able to access to it directly, skipping all the ui / download / unzip steps above. Those temp directories are under $CFG->dataroot/temp/backup. Note that, for each backup invocation, a new directory is created.

Also, in order to be able to execute backups quickly (instead of navigating along the UI), you can, simply, put one script like this in your $CFG->dirroot directory:

<syntaxhighlight lang="php">
<?php

define('CLI_SCRIPT', 1);
require_once('config.php');
require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');

$course_module_to_backup = XX; // Set this to one existing choice cmid in your dev site
$user_doing_the_backup = YY; // Set this to the id of your admin account

$bc = new backup_controller(backup::TYPE_1ACTIVITY, $course_module_to_backup, backup::FORMAT_MOODLE,
backup::INTERACTIVE_NO, backup::MODE_GENERAL, $user_doing_the_backup);
$bc->execute_plan();
</code>

Just set proper values for XX and YY above and execute it from the command line. If you get one error about one not found class (with the name of your module) everything is ok.

To get the analogous restore code please see: https://docs.moodle.org/dev/Restore_2.0_for_developers#Automatically_triggering_restore_in_code

==== Required stuff ====

The first thing you need to make is to, explicitly, declare that your module (choice in our example) is going to support the MOODLE2 backup format, to do so, you need to go to mod/choice/lib.php and, in the choice_supports() function add one new feature by adding this line:

<syntaxhighlight lang="php">
case FEATURE_BACKUP_MOODLE2: return true;
</code>

If you execute another backup (with the script provided above, you will continue getting one error, since we haven't still coded anything related to backup, that's ok.

Next step is to create the directory where all the backup code for the choice module will be. Just create the directory(s) mod/choice/backup/moodle2

At this point, we have all the required stuff ready and all the pending tasks will be done under that recently created directory.

==== Settings, Steps and Tasks ====

In the introduction of the tutorial, we commented about backup being structured into tasks, each one being one collection of steps (and potentially using some custom settings). Those are, exactly, the objects that we need to create to achieve the backup functionality in our module.

First of all, lets' create the settings file, where all the custom settings to be used by our module will be defined and implemented. It must be named '''mod/choice/backup/moodle2/backup_choice_settingslib.php''' and their contents are really meaningful:

<syntaxhighlight lang="php">
<?php

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

/**
* @package moodlecore
* @subpackage backup-moodle2
* @copyright 2010 onwards YOUR_NAME_GOES_HERE {@link YOUR_URL_GOES_HERE}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// This activity has not particular settings but the inherited from the generic
// backup_activity_task so here there isn't any class definition, like the ones
// existing in /backup/moodle2/backup_settingslib.php (activities section)
</code>

Looks simple, isn't it? Nothing but a few comments. This is looking really easy. For now, we aren't going to introduce any custom setting for any module, only the "core activity settings" will be used. Once backup and Moodle 2.0 is stable we can start analyzing useful settings to customize how the module's backup is performed. For now, just leave it blank, please. In fact, if it's empty,''' you can safely not create it''' at all. It's here just for explanation purposes.

Side note: To save some space, we only will be showing the © message/license in the code above. Just add it to each file created.

Now we are going to create the steps file, where all the steps to be executed by our backup activity task will be defined and implemented. It must be named '''mod/choice/backup/moodle2/backup_choice_stepslib.php''' and their contents are these:

<syntaxhighlight lang="php">
<?php

/**
* Define all the backup steps that will be used by the backup_choice_activity_task
*/
</code>

Yes, it's another empty file. No worries we'll fill it later.

Finally we need to create the task file, where our just created settings and steps files will be included and used. It must be named '''mod/choice/backup/moodle2/backup_choice_activity_task.class.php''' and their contents are these:

<syntaxhighlight lang="php">
<?php

require_once($CFG->dirroot . '/mod/choice/backup/moodle2/backup_choice_stepslib.php'); // Because it exists (must)
require_once($CFG->dirroot . '/mod/choice/backup/moodle2/backup_choice_settingslib.php'); // Because it exists (optional)

/**
* choice backup task that provides all the settings and steps to perform one
* complete backup of the activity
*/
class backup_choice_activity_task extends backup_activity_task {

/**
* Define (add) particular settings this activity can have
*/
protected function define_my_settings() {
// No particular settings for this activity
}

/**
* Define (add) particular steps this activity can have
*/
protected function define_my_steps() {
// Choice only has one structure step
}

/**
* Code the transformations to perform in the activity in
* order to get transportable (encoded) links
*/
static public function encode_content_links($content) {
return $content;
}
}
</code>

This is the main file (class) of the choice backup and it will be used to define any setting (define_my_settings() method) and any step (define_my_steps() method) to be executed in the backup process. It also contains one 3rd method (encode_content_links($content)) that will allow manually URLs pointing to the choice to be properly converted when the choice is moved to other site / course using the backup / restore functionality.

As you see, for now, the three required methods are doing nothing. Just execute the backup again. Wow, no errors anymore. We have already fulfilled all the minimum coding needs in order to have the choice backup working.

Now you should go to your $CFG->dataroot/temp/backup/xxxx directory (the more recent) and spend some time looking what has been created under the activities/choice_XX directory. There is already a lot of stuff that backup has generated for you: comments, blocks, logs, grades, module info, roles... some of them empty and others already showing real information.

In any case, now, we need to add one important file there, the "choice.xml" where the real information for your module will be present, following the specs given by the schema we decided some sections above.

So, let's go, it's time to create our choice structure step. To do so, we edit the '''mod/choice/backup/moodle2/backup_choice_stepslib.php''' file and add this code after the existing comments:

<syntaxhighlight lang="php">
/**
* Define the complete choice structure for backup, with file and id annotations
*/
class backup_choice_activity_structure_step extends backup_activity_structure_step {

protected function define_structure() {

// To know if we are including userinfo
$userinfo = $this->get_setting_value('userinfo');

// Define each element separated

// Build the tree

// Define sources

// Define id annotations

// Define file annotations

// Return the root element (choice), wrapped into standard activity structure

}
}
</code>

So, we have defined one structure step that will be the responsible, using one PHP API to provide backup with all the information needed to generate the choice.xml file. Now, go back to the task file and add these contents in the define_my_steps() methods:

<syntaxhighlight lang="php">
$this->add_step(new backup_choice_activity_structure_step('choice_structure', 'choice.xml'));
</code>

That way, our choice task knows it must execute one new step, the one involving the generation of the choice.xml file. Let's execute one new backup and see results.You should be getting one new error with something like that "backup_structure_step_wrong_structure". It means that everything is ok up to now, the task has tried to execute the structure step, but this is not properly defined.

===== Defining each element =====

So, next step is about to define the choice structure. Going back to our step, under the ''// Define each element separate'' comment we'll add this code:

<syntaxhighlight lang="php">
$choice = new backup_nested_element('choice', array('id'), array(
'name', 'intro', 'introformat', 'publish',
'showresults', 'display', 'allowupdate', 'allowunanswered',
'limitanswers', 'timeopen', 'timeclose', 'timemodified'));

$options = new backup_nested_element('options');

$option = new backup_nested_element('option', array('id'), array(
'text', 'maxanswers', 'timemodified'));

$answers = new backup_nested_element('answers');

$answer = new backup_nested_element('answer', array('id'), array(
'userid', 'optionid', 'timemodified'));
</code>

===== Return the root element =====

And also, in order to get it working, let's define the return element, so, after the ''// Return the root element'' comment, add this code:

<syntaxhighlight lang="php">
return $this->prepare_activity_structure($choice);
</code>

Now we can execute the backup again and, as long as we have already defined the root element of the module, should have now one choice.xml file created (without proper contents but must be there).

About the code above, all we have done is to define, separately each element that will be part of the choice.xml file. Special note about the $options and $answers elements. Since Moodle 1.9 we use to enclose real elements (the singular ones) inside one extra plural element, hence we create them here (as empty elements without attributes nor child tags). About the rest (the singular ones) we use 3 params in the instantiation:
* The name of the element
* One array of attributes of the element
* One array of child tags (fields) of the element.
And we include all the fields that previously we had defined in our schema '''but''' the ones marked as '''not needed'''.

===== Building the tree =====

Now it's time to declare the relations between all those elements, so, after the ''// Build the tree'' comment we'll add this code:

<syntaxhighlight lang="php">
$choice->add_child($options);
$options->add_child($option);

$choice->add_child($answers);
$answers->add_child($answer);
</code>

Self explanatory, using $choice as root element, we define the whole tree using the add_child() method. And, of course, we respect '''the order''' that we had decided, so $options will be '''physically''' before $answers in the tree (and in the generated XML).

===== Defining the sources =====

After this, it's the moment to instruct our tree about how to fetch information from DB in order to generate the choice.xml file, so after the ''// Define sources'' comment, we'll add this code:

<syntaxhighlight lang="php">
$choice->set_source_table('choice', array('id' => backup::VAR_ACTIVITYID));

$option->set_source_sql('
SELECT *
FROM {choice_options}
WHERE choiceid = ?',
array(backup::VAR_PARENTID));

// All the rest of elements only happen if we are including user info
if ($userinfo) {
$answer->set_source_table('choice_answers', array('choiceid' => '../../id'));
}
</code>

So we define the source for the $choice element as the information present in the 'choice' table for the id that is being backup (backup::VAR_ACTIVITYID). Or we define the source for the $option element like one SQL (could have been one table too, just to show more possibilities of the API, using the parent (the choice one) as value for the query (backup::VAR_PARENTID).

And finally, conditionally, if user information is going to be included, we define the source for the $answer (note we had already annotated in our schema that this element was dependent of that).

And we define the source condition as having the 'choiceid' field matching the value of the 'id' field two levels above (../../id). If you follow the tree created in the previous code section, that's exactly the choice->id (remember we have introduced one extra level (the plural one between the 'choice' and the 'answer' singular elements). Note this is 100% equivalent to use backup::VAR_PARENTID (as we have done in the $option source) just used to show possibilities of the API.

Summarizing, with the API, we have these 3 method for defining sources:

* '''set_source_table($tablename, array $conditions)''': When the information is get straight from one table (vast majority of cases in backup)
* '''set_source_sql($sql, array $params)''': When the information doesn't map one table directly and we need something more complex
* '''set_source_array($array)''': When we have some fixed information to backup. Not really useful in nested information, but used by core here and there.

Note that both the $conditions and $params above only accept one limited number of constants or values (not all available in all backups!), mainly:

* '''backup::VAR_COURSEID''': The id of the course this activity belongs to / the course id being backup
* '''backup::VAR_SECTIONID''': The id of the section this activity belongs to / the section id being backup
* '''backup::VAR_ACTIVITYID''': The id of the activity id being backup
* '''backup::VAR_MODID''': The id of the course_module being backup
* '''backup::VAR_MODULENAME''': The name of the module being backup
* '''backup::VAR_BLOCKID''': The id of the block being backup
* '''backup::VAR_BLOCKNAME''': The name of the block being backup
* '''backup::VAR_CONTEXTID''': The context id of the activity / course being backup
* '''backup::VAR_PARENTID''': The value of the first parent id found in the structure.
* '''../some/path/to/parent''': To manually point to other value of any parent.

Is important to note that, in 99% of the case we should be using, exclusively, some of the constants above, and backup, automatically will handle them properly. In case we have any other condition or param to be added like, for example, the number 23, or the string 'user', we cannot add them directly, but enclose them with the helper '''backup_helper::is_sqlparam(23)''' or '''backup_helper::is_sqlparam('user')'''. That way backup will know they are raw SQL params not needing any special handling, like the constants above.

Well, now it's time to run backup again and take a look to our activities/choice_XX/choice.xml file. Now everything should be there, properly nested, the choice, the options and the answers. We are really near finishing now.

===== Annotating IDs =====

Now it's time to perform all the annotations that we had already detected in our analysis of the module. So, after the ''// Define id annotations'' comment we'll be adding:

<syntaxhighlight lang="php">
$answer->annotate_ids('user', 'userid');
</code>

It simply means, annotate for each $answer element, the value of the 'userid' field as one 'user' to be backup. In other words we are instructing backup that there is one new user to include later, when generating the users information and, at the same time, we are determining that those users are needed for the choice XX, so, if on restore we decide to skip that choice and such user isn't necessary for any other module / subsystem, it won't be restored. All this "uses" information is handled by the "inforef.xml" files within each activity backup, just in case you're interested to take a look to them. Else, just consider them, "dark magic".

'''Note''': If you're not sure about which elements must be annotated, review [[Backup 2.0 for developers #annotate_is_important|"Annotating some important bits"]] above for details about '''must-be-done''' annotations.

===== Annotating files =====

And, finally, reviewing our elaborate and detailed schema, the last thing we need to take care of are the file areas used, so, after the ''// Define file annotations'' comment we'll add:

<syntaxhighlight lang="php">
$choice->annotate_files('mod_choice', 'intro', null, $contextid = null); // This file area does not have an itemid.
</code>

That means that, within the $choice element we have one file area in use, of course belonging to the 'mod_choice' component (where all the choice module files belong to), named 'intro' and not using itemid (null). Note that, since it is possible to have multiple file areas in the same element (table), you may end up having multiple calls to the annotate_files() method, one for each filearea to be added to backup. The third parameter, if it is needed, must be the name of one of the attributes or fields of the $choice element (usually, in the vast majority of cases, the 'id' of the element), otherwise we'll use null. The fourth parameter is optional and will default to the context id of the backup, but if you want to specify the context id you do so here.

=== One encoded wor(l)d ===

Already out from the step definition, that should be working ok now, with the choice.xml file being generated and all the annotations being processed and added to the inforef.xml file, there is one more point to fulfill before considering choice's backup 100% finished.

And it's about how to provide the ability to transform some links to the choice module when the backup file is restored into another server / course. That is automatically handled by a two-step approach:
# On backup, we transform as many well-know URLs as possible to one encoded form.
# On restore, we transform those encoded URLS back to their original form, but pointing to their new targets.

So, in backup, we must provide services for the point 1 above, and that is done by adding some "encoding" conversions to the '''encode_content_links()''' method in our '''backup_choice_activity_task'''. So, define it to look like this

<syntaxhighlight lang="php">
/**
* Code the transformations to perform in the activity in
* order to get transportable (encoded) links
*/
static public function encode_content_links($content) {
global $CFG;

$base = preg_quote($CFG->wwwroot,"/");

// Link to the list of choices
$search="/(".$base."\/mod\/choice\/index.php\?id\=)([0-9]+)/";
$content= preg_replace($search, '$@CHOICEINDEX*$2@$', $content);

// Link to choice view by moduleid
$search="/(".$base."\/mod\/choice\/view.php\?id\=)([0-9]+)/";
$content= preg_replace($search, '$@CHOICEVIEWBYID*$2@$', $content);

return $content;
}
</code>

Básically, it gets any URL (manually written) in any content of the backup being generated and transform some (well-known) URLs to one encoded alternative. In this case we are encoding:
* Any URL pointing to the list of choices in a course == is changed to ==> $@CHOICEINDEX*XX@$
* Any URL pointing to one exact choice == is changed to ==> $@CHOICEVIEWBYID*YY@$

In restore, well have the opposite conversions happening, replacing the XX and YY above to their new equivalents, so those links will be transportable via backup/restore without any need to edit them manually later.

Tip: Don't forget to look to the module's 1.9 backup code, as far as there you'll find which conversions must be considered to be added here.

=== Final notes ===

* Don't get stressed, it's really more difficult / longer to explain than to do it. 100% guaranteed, else we'll return your money. :-P
* If you've become lost, or your code is not working properly, you always can [https://github.com/moodle/moodle/tree/master/mod/choice/backup/moodle2 see the complete choice working code in git]. Or, alternatively, look to other well known modules, like [https://github.com/moodle/moodle/blob/master/mod/forum/backup/moodle2/ forum] or also the [https://github.com/moodle/moodle/blob/master/backup/moodle2/backup_stepslib.php big core library of steps], where you will find all sort of uses of the API.
* If you are going to implement backup for module XXXX, just copy this document, replace any "choice" occurrence within it by XXXX and follow it from the beginning to the end. Should work.
* If the module already existed in Moodle 1.x, try to follow the same structure if possible, that will make things easier for restore / conversion.
* Right now there are some pending tasks related with different exceptions that will be thrown if you code something wrongly (bad nesting, incorrect field names, bad constant/sql param uses...) and how they are shown. Fix for that will be coming soon.
* Also, as stated at the beginning of this tutorial, we are still missing "subplugins" final support in modules, so try to avoid implementing backup on them for now. Once ready, there will be one new section in this document about them.
* Any question / improvement / comment, feel free to contact with Moodle HQ, better if using the Tracker or, alternatively, forums / email / direct contact with your very-best-developer-friend. Note this is version x.0 (dot zero) of the backup API, so sure there are possibilities to improve it along the time.

== Other components that can be backed up ==

Most plugins which can be added to a course can also include data in a course backup. Some examples:

* Course formats
* Themes: [[ Backup 2.0 theme data| Backup 2.0 theme data]]
* Plagiarism plugins

Moodle 3.0.1 release notes

2021-08-10T15:11:49Z

Moodlebot: Text replacement - "class="nicetable"" to "class="wikitable""

[[Releases]] > {{FULLPAGENAME}}

Release date: 21 December 2015

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.0.1%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.0.1].

===Highlights===

Moodle 3.0.1 is a special release outside of the normal release schedule. The main highlight is support of PHP 7.0. This is the new major version of the programming language Moodle is written in; it has significantly better performance but at the same time lots of changes in the engine. Please note that Moodle 2.9 will show errors if run on PHP 7.

Before upgrading to PHP 7 version on production servers, you are recommended to '''test all plugins thoroughly'''. See [[Moodle and PHP7]] for developer documentation.

PHP 7 was released on 3 December 2015 and is still very young. Not all libraries and/or drivers are available yet for PHP 7. For example, '''there are no drivers for SQL*Server'''. Other drivers required by your plugins may also be missing.

'''PHP 7 compatibility makes Moodle faster'''
{| class="wikitable"
|-
|[[File:php7 time logging in.png]]
|[[File:course-time-300x177.png]]
|-
|20% faster when logging in*
|59% faster when loading the course page*
|-
|}

'''PHP 7 compatibility significantly reduces memory used'''

{| class="wikitable"
|-
|[[File:php7 memory logging in.png]]
|[[File:php7 memory viewing course.png]]
|-
|42% less memory used when logging in*
|38% less memory used when viewing a course*
|-
|}

: * Test results obtained on a test Moodle instance with one course in topics format with over 100 activities and resources.

===Other fixes and improvements===

* MDL-44330 - When using assignment grading in several tabs the links to individual students grades work correctly
* MDL-37834 - Excel can be used to edit the assignment offline grading worksheet
* MDL-42571 - Edit PDF: Fixed bug with viewing a second PDF on the assignment grading page
* MDL-43069 - Assignment grading: "Submission comments" fail to expand if you hide the "file submissions" column
* MDL-37308 - Uploaded PNG images preserve transparency when resized
* MDL-49490 - Fixed export to portfolio link in assignment with additional files
* MDL-52194 - Fixed Flowplayer not working with insecure configuration of request_order

===For developers===

* MDL-51582 - Switch to grunt to compile LESS as recess is no longer maintained

===Security issues===

There are no security issues in this release. Security issues will be included in Moodle 3.0.2 which is due for release in January 2016.

==See also==
*[[Moodle 3.0 release notes]]

[[Category:Release notes]]
[[Category:Moodle 3.0]]

[[fr:Notes de mise à jour de Moodle 3.0.1]]
[[es:Notas de Moodle 3.0.1]]

Moodle 2.9 release notes

2021-08-10T15:11:48Z

Moodlebot: Text replacement - "class="nicetable"" to "class="wikitable""

[[Releases]] > {{FULLPAGENAME}}

Release date: Monday, 11th May 2015

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%222.9%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 2.9].

See our [https://docs.moodle.org/29/en/New_features New Features page] for a more user-friendly introduction to Moodle 2.9 with screenshots.

If you are upgrading from previous version, make sure to read the [https://docs.moodle.org/29/en/Upgrading Upgrading] documentation.

==Server requirements==

These are just the minimum supported versions. We recommend keeping all of your software up-to-date.

* Moodle upgrade: Moodle 2.2 or later (if upgrading from earlier versions, you must upgrade to 2.2.11 as a first step)
* PHP version: minimum PHP 5.4.4 (always use latest PHP 5.4.x or 5.5.x on Windows - http://windows.php.net/download/), PHP 7 is NOT supported
* Ghostscript should be installed for pdf annotation.

=== Database requirements ===

Moodle supports the following database servers. Again, version numbers are just the minimum supported version. We recommend running the latest stable version of any software.

{| class="wikitable"
|-
! Database
! Minimum version
! Recommended
|-
| [http://www.postgresql.org/ PostgreSQL]
| 9.1
| Latest
|-
| [http://www.mysql.com/ MySQL]
| 5.5.31
| Latest
|-
| [https://mariadb.org/ MariaDB]
| 5.5.31
| Latest
|-
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]
| 2008
| Latest
|-
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]
| 10.2
| Latest
|}

==Client requirements==

=== Browser support ===

{| class="wikitable"
|-
! Browser
! Minimum version
! Recommended version
! Notes
|-
| [https://www.google.com/intl/en_au/chrome/browser/ Google Chrome]
| 30.0
| Latest
|
|-
| [http://www.mozilla.org/en-US/ Mozilla Firefox]
| 25.0
| Latest
|
|-
| [http://www.apple.com/safari/ Apple Safari]
| 6
| Latest
|
|-
| [http://windows.microsoft.com/en-AU/internet-explorer/download-ie Microsoft Internet Explorer]
| 9
| Latest
| Version 10 is required for drag-and-drop upload of content from outside the browser into Moodle
|}

==Major features==

===Navigation improvements===

One of the biggest project was improvements in Navigation and Users pages, see also MDL-45774. It includes:

* MDL-45894, MDL-49634 - [https://docs.moodle.org/29/en/Overview_report Grades page] listing all my courses, and all courses I am teaching in one place (linked from User Menu)
* MDL-48936 - My Home is now [https://docs.moodle.org/29/en/Dashboard Dashboard]
* MDL-48932, MDL-45898 - Redesign [https://docs.moodle.org/29/en/User_profiles profile page], make it pluggable
* MDL-45895 - New [https://docs.moodle.org/29/en/Preferences Preferences] page (linked from user menu)
* MDL-45896 - Consistent header for user pages
* MDL-48931 - Consistent header for user sub pages
* MDL-48935 - Consistent bread crumbs for user pages
* MDL-49635 - Remove redundant nodes from nav tree
* MDL-49983 - Improve consistency of the use of the word "My" in navigation

===User interface improvements===

* MDL-43996 - Drag and drop image into [https://docs.moodle.org/29/en/Text_editor Atto editor] inserts it as a file
* MDL-19670 - Teacher can post the same forum question to all groups at once
* MDL-47172 - “You have assignments that need attention” in the [https://docs.moodle.org/29/en/Course_overview_block course overview block] displays relevant information for teachers
* MDL-48933 - Ajax interface for [https://docs.moodle.org/29/en/Messaging messaging]
* MDL-23296 - Provide search function for [https://docs.moodle.org/29/en/Server_files_repository Server files area] in the file picker
* MDL-48937 - Don't show the category in the breadcrumb if there is only one category
* MDL-26226 - Section names in the navigation can link to the sections
* MDL-49694 - Overview report shows the full course name
* MDL-47527 - Allow access to overview report for users who can view all grades
* MDL-36009, MDL-46662 - Grader report accessibility improvement
* MDL-47562 - UI Fixes and improvements for SingleView report
* MDL-47434 - Do not display 'General' section in navigation block if it's empty

===Course creation improvements===

* MDL-10405 - Added button to quickly delete a whole section on the [https://docs.moodle.org/29/en/Course_homepage course homepage]
* MDL-31500 - Allow backup and restore on the front page
* MDL-5583 - Fields in database module can be set as required
* MDL-28526 - Glossary can export/import embedded images and attached files
* MDL-49006, MDL-49101 - Removed default requirement of activity description and substituted with a single setting
* MDL-13831 - Grade to pass can be set by editing activity without going to gradebook
* MDL-46960 - Completion status is updated immediately for student when activity is graded
* MDL-27074 - Display group name for group events in the calendar
* MDL-48969 - New [https://docs.moodle.org/29/en/Activity_results_block activity results block]
* MDL-18177 - Add option to choose whether groups and/or groupings are included in a back up
* MDL-20053 - Database activity: create ##userpicture## tag to allow the user's profile picture to be displayed
* MDL-49543 - Add a WYSIWYG field to Badges which is displayed on the criteria page
* MDL-46416 - Possible to change / remove picture from group
* MDL-49687 - Adding a single person to multiple groups at the same time
* MDL-21724 - The course edit page needs a way to redirect to some page other than the main course page after saving
* MDL-47628 - When grouping is selected for the activity display a button to quickly create access restriction (helps users who were used to groupmembersonly)
* MDL-23178 - Allow indenting again for activities in the Main Menu block
* MDL-46238 - Add a simple way to go back from enrol/users.php page to the course

===Administrator features===

* MDL-15187 - Assign global roles using CSV upload
* MDL-30937 - Backup report again links to the individual course backup summaries
* MDL-32547 - Configure temporary file deletion, to avoid moodledata/temp/backup filling up the filesystem
* MDL-49684 - Replace custom Moodle timezone stuff with standard PHP date/time code
* MDL-25763 - CLI version of admin/replace.php
* MDL-44874 - Per-request temp directories
* MDL-46064 - Drop support for MyISAM
* MDL-49298 - Make tgz backups standard
* MDL-47834 - New option for restriction of concurrent logins in [https://docs.moodle.org/29/en/Managing_authentication managing authentication]
* MDL-47800 - Logout user when somebody changes their password
* MDL-47830 - Add password rotation restrictions
* MDL-48559 - Web CRON should be disabled by default
* MDL-48080 - Never send mail to domains ending in .invalid
* MDL-48595 - Log exports no longer fails because of memory limit
* MDL-28513 - Allow specification of admin user email in CLI installer
* MDL-49842 - Allow specification of front page summary in CLI installer
* MDL-47803 - New page that shows all [https://docs.moodle.org/29/en/Browser_sessions browser sessions] of current user
* MDL-34684 - New health check to detect incorrect category path order and/or missing parent categories
* MDL-48493 - Automatically detect the plugin type when installing from ZIP
* MDL-48894 - [https://docs.moodle.org/29/en/Site_registration Site registration] page states if site is registered
* MDL-18183 - Option to verify peer and host of MNet peer using HTTPS

===Files and repositories===

* MDL-42616 - New admin tool for [https://docs.moodle.org/29/en/Working_with_files adding custom file types]
* MDL-43752 - [https://docs.moodle.org/29/en/Amazon_S3_repository Amazon S3 repository] allows an endpoint to be set

===Authentication, enrolments and access===

* Several improvements to meta enrolments, such as: populate groups from courses MDL-17929, sorting courses alphabetically MDL-35696, button to quickly add a new method MDL-49439
* MDL-26017 - Keyholder capability in self-enrolment plugin
* MDL-20365 - Salted Crypt passwords option for external database authentication
* MDL-49380 - Chose "Create new group" when synchronising cohort enrolment with a group
* MDL-49677 - Improvement of Custom welcome message in self-enrolment plugin
* MDL-43415 - Custom profile fields should be syncable with external DB auth
* MDL-49638 - reCAPTCHA should be moved below custom profile fields during self registration

===Quiz===

* MDL-40988 - Add section headings to quiz
* MDL-40992 - Option for teachers to allow students to redo a finished question within a quiz attempt
* MDL-40990 - Teachers can require students to complete Question 1 before they can see Question 2
* MDL-25721 - The question bank can be sorted by date
* MDL-348 - Printer-friendly option for quizzes
* MDL-6340 - force unique/unseen questions in retakes
* MDL-35280 - quiz_reset_userdata does not have an option to remove user/group overrides
* MDL-48898 - Quiz time period setting should use admin_setting_configduration

===Lesson===

* MDL-48803 - support for groups
* MDL-48715 - moving “time spent” from prerequisite to the proper completion rule
* MDL-43387 - UI for grading essays
* MDL-48244 - Lessons with no questions show completed after the first page is viewed
* MDL-47587 - Make progress bar available on the very last page of a lesson.
* MDL-49642 - Give time/date extensions to users and groups in lesson
* MDL-40286 - non-editing teacher should see Grade analysis in Lesson
* MDL-48473 - Lesson shortanswer question: add fill in the blank option
* MDL-48984 - Lesson content page jump descriptions, numerical and shortanswer questions answers allow rich html but should be plain text
* MDL-18553 - Removing grade info from lesson pages if lesson grade is 0
* MDL-26689 - in order to prevent interactivity references from being broken move the "Dependent on" feature to the completion/availability subsystem
* MDL-49183 - Page creation, update and delete events added
* MDL-48883 - Content page viewed, Question page viewed and Question page answered events added

===Other modules===

* MDL-48221 - Make forum subscription combinations less confusing with different combinations
* MDL-48822 - Find last visual post in a discussion
* MDL-46755 - Allow teachers to configure the number of discussions displayed using the social course format
* MDL-49069 - Ability to specify default values for Forum RSS
* MDL-48159 - For users without group prevent submissions instead of using "Default team" in group assignments
* MDL-47777 - Convert assignment maximum files per submission maximum to global setting
* MDL-45848 - Possible to assign Marker on a marking guide or rubric assignment without giving a grade
* MDL-49220 - Allow preview of Choice options before activity is opened for submission
* MDL-34375 - Choice module should display information in "Course overview" block
* MDL-43770 - Exclude inactive users' responses from Choice report (with an option to include)
* MDL-32285 - Added "Continue" button under Error notification message (IMS CP)
* MDL-49730 - Workshop: use full page width when displaying contents
* MDL-36874 - Text navigation for Books
* MDL-49563 - Allow glossary entry to be updated from glossary navigation

===Various===

* MDL-46763 - Save user images as JPEG if uploaded in that format.
* MDL-48760 - MathJax library updated to 2.5
* MDL-47232 - Course completion: "Activities to be completed" should not require passing grade
* MDL-48437 - Make Visible/All [https://docs.moodle.org/29/en/Groups groups] selector show own groups first
* MDL-47501 - Add an indication that the [https://docs.moodle.org/29/en/Grade_letters grade letters] have been overridden
* MDL-47159 - Link plugin in Atto should add <nowiki>'http://'</nowiki> prefix when necessary
* MDL-9443 - Run *.xhtml file through the text filters
* MDL-48616 - Add Macrons in Atto character map
* MDL-46665 - ID number filter added to [https://docs.moodle.org/29/en/Browse_list_of_users Browse list of users]
* MDL-48499 - Show which users have not received messages in bulk messaging
* MDL-49333 - Return additional information in WebService core_get_site_info

==Security issues==

* [https://moodle.org/mod/forum/discuss.php?d=313681 MSA-15-0018] Quiz manual-grading is an XSS risk, but does not declare that
* [https://moodle.org/mod/forum/discuss.php?d=313682 MSA-15-0019] Possible phishing when redirecting to external site using referer header
* [https://moodle.org/mod/forum/discuss.php?d=313683 MSA-15-0020] User fullname disclosure through account confirmation link
* [https://moodle.org/mod/forum/discuss.php?d=313684 MSA-15-0021] Any authenticated user can subscribe to site-wide event monitor rules
* [https://moodle.org/mod/forum/discuss.php?d=313685 MSA-15-0022] Potential XSS risk when returning text entered by student from Web Services
* [https://moodle.org/mod/forum/discuss.php?d=313686 MSA-15-0023] Suspended user is able to login when confirming email
* [https://moodle.org/mod/forum/discuss.php?d=313687 MSA-15-0024] User with suspended enrolment can see sections in the navigation tree
* [https://moodle.org/mod/forum/discuss.php?d=313688 MSA-15-0025] Capability to manage own files is not respected in Web Services

==For developers==

* MDL-49046 - Support for Asynchronous Module Definition formatted javascript modules. Developer docs: [[Javascript Modules]]
* MDL-49163 - Support for calling webservice functions directly from javascript. Developer docs: [[AJAX]]
* MDL-49152 - Support for implementing renderers as mustache templates (php and javascript). Developer docs: [[Templates]]
* MDL-44874 - A new per-request directory API has been added, and should be used instead of make_temp_directory wherever possible.
* MDL-49604 - Support for in browser caching (localstorage) of strings and templates
* MDL-49650 - [https://docs.moodle.org/29/en/Template_library Template Library] - tool for displaying templates in the current theme
* MDL-48887 - New auth hook to intercept code before login page is shown.
* MDL-48177 - Allow plugin environment checks to work without defining explicit versions of Moodle
* MDL-46728 - WOFF2 fonts are supported in themes.
* MDL-39752, MDL-49456 - Behat tests runs in parallel
* MDL-49163 - Unified Ajax script handler. Developer docs: [[AJAX]]
* MDL-27548 - The comments table contains the component
* MDL-49269 - Add an AMD log module
* MDL-49534 - Delete pear/HTTP/WebDav
* MDL-48212 - Introduces a new class \core\message\message that should be used instead of \stdClass for creating messages.
* MDL-37477 - html_table API supports caption tag
* MDL-49643 - Deprecate inconsistent API to extend the navigation by local plugins
* MDL-49361 - Ability to provide alternate strings manager
* MDL-44642 - Implemented backend to keep session alive
* MDL-45725 - User preferences for flexible tables can be set persistent across sessions
* MDL-49306 - When copying block instances the instance data is also copied
* MDL-47915 - Theme layout "embedded" uses id='page-content' rather than 'content' to be consistent with other layouts
* MDL-48212 - Implement new message api to support specific text only on a given handler
* MDL-49262 - Delete the yui versions of the bootstrap plugins
* MDL-40864 - Use div.logo instead of a.logo in Bootstrapbase / Clean / More home links
* MDL-48160 - For theme developers: changes to block region layouts when coded for RTL

[[Category:Release notes]]
[[Category:Moodle 2.9]]

[[fr:Notes de mise à jour de Moodle 2.9]]
[[es:Notas de Moodle 2.9]]

Mobile device support

2021-08-10T15:11:48Z

Moodlebot: Text replacement - "class="nicetable"" to "class="wikitable""

{{Moodle 2.6}}
This pages summarizes development efforts being made as part of the development of Moodle 2.6. Specifically, enhancing the experience for users accessing Moodle via a tablet or smartphone. Mobile devices are now extremely common and Moodle must evolve to allow Moodle users to make full use of their devices.

==Priorities==
Mobile device support will be an ongoing priority for Moodle HQ. With additional core development and base theme alterations Moodle should be able to function equally well on desktops, tablets and smartphones. This will enable Moodle sites to be confident that their Moodle installation will be usable on whatever devices are in use by their students and staff.

To enable us to achieve the greatest impact with finite resources we have decided on the following set of priorities.

===Content Before Configuration===
It's extremely important that users be able to easily access course content on their various devices. For the time being it is acceptable to require the user to use a desktop or laptop computer to perform site or course configuration. Once we have ensured that users can easily access course content we will move on to improving the mobile experience for admins and users who are creating courses.

===1. Students===
Students typically outnumber staff by a large margin and have a very high rate of mobile device ownership. "Read only" tasks like checking assignment due dates, retrieving grades and accessing course resources must be painless. "Write" tasks like submitting photos taken with the device camera should be accommodated as much as possible.

===2. Teachers===
Less numerous than students. They should be able to participate in their courses, for example participating in forum discussions, as well as perform some core activities like grading of assignment submissions. Some areas, most notably the gradebook, will likely not be optimized for mobile devices until a later release.

===3. Admins===
Site administration is expected to still be performed primarily on desktop and laptop computers. Mobile optimization of admin tasks may occur in the future but is not a priority for this release.

=== Summary ===

In summary, the following types of use are anticipated:

{| class="wikitable"
|-
! Activity
! Student
! Teacher
! Administrator
|-
! Checking Assignment metadata
| M / T / D
| M / T / D
| M / T / D
|-
! Viewing Gradebook
| M / T / D
| M / T / D
| M / T / D
|-
! Editing Gradebook
| N/A
| T / D
| N/A
|-
! Accessing Course Resources
| M / T / D
| M / T / D
| M / T / D
|-
! Reading forum discussions
| M / T / D
| M / T / D
| M / T / D
|-
! Participating in forum discussions
| M / T / D
| M / T / D
| M / T / D
|-
! Uploading multimedia (images, video, audio)
| M / T / D
| M / T / D
| M / T / D
|-
! Uploading other files
| D
| D
| D
|-
! Site administration
| N/A
| N/A
| D
|}

M = Mobile;
T = Tablet;
D = Desktop (or Laptop).

==Device Support==
Rather than listing or blacklisting devices that do or do not present Moodle correctly, we are aiming to create a list of recommended specifications for a device in order to have an optimum experience with Moodle.

===Android===
We recommend a 1GHz single core, or better device, with 512MB or more RAM. A resolution of 480x320 in Landscape mode is also recommended.

===iOS===
Any device capable of running iOS 4 or greater is recommended.

==Device Testing==
Testing of current Moodle functionality on a range of mobile devices has been performed. iPads, recent iPhones, Android tablets and Android phones have been targeted for thorough testing. This testing will be repeated in the future to detect device specific problems.

Testing is limited by what devices are physically available to HQ staff. As we near the release of 2.6 testing by the community will be required to test additional devices, most notably the iPhone 5.

===High Priority Devices Available to HQ===
{|
! align="right"| Operating System
! align="left"| Device
! Browser
|-
|iOS
|iPad 2
|Safari
|-
|iOS
|iPad 3
|Safari
|-
|iOS
|iPod Touch
|Safari
|-
|iOS
|iPhone 3gs
|Safari
|-
|iOS
|iPhone 4s
|Safari, Chrome and Opera
|-
|Android
|Acer Iconia 10"
|Stock 4.0.3
|-
|Android
|HTC Sensation 4"
|Stock 4.0.2
|-
|Android
|LG Optimus L7
|Stock (Android 4) and Chrome
|-
|Android
|Samsung Tab 2 7"
|Stock (Android 4) and Chrome
|-
|Android
|Nexus 4
|Chrome
|-
|Android
|HTC Desire
|Stock (Android 2.3)
|-
|Android
|Motorola Xoom 10"
|Chrome
|}

==Getting It Done==
Tracker issues have been created as part of device testing and also after discussions about possible improvements. The tracker issues are sub-tasks of MDL-38856 and MDL-39665.

Broadly speaking the issues can be grouped by area. Note that this listing will fall out of date very quickly. It is only intended to provide an approximate sense of where work is to be done. Please consult MDL-38856 and MDL-39665 for a completely up to date summary of the work being done.

===Blocks===
*Navigation - Major improvement could be done here. The hamburger menu icon could display a navigation side bar similar to the current HTML5 mobile app. Also the paddding, font size is too small (Xoom, HTC Desire) MDL-39715
*Calendar - Use ajax to avoid reloading MDL-39818 MDL-38347
*Add New Block - Samsung tab II & LG Optimus L7: Chrome and Stock browsers. Adding new block doesn't automatically added the block to the page. It requires tabbing the select option box to initiate the process. (And Xoom and HTC Desire) MDL-39776

===Front Page===
*Reports - On Front page settings > reports > course participation, improve alignment/layout for the page. MDL-39798

===Course Page===
*Adding activities/resources - Could be improved. Not working on Nexus 4 - 4.2 - Chrome. Selecting 'folder' do not redirect to the folder creation page. However the second time you click on it, the select box automatically trigger the exist choice and this time goes to the 'folder' creation page. Not working on HTC Desire at all (can't trigger select). Not working on Xoom at all - activity chooser locked up. MDL-39750 MDL-39816
*Grading - Smaller screens have a really long scroll before you can start to move horizontally, then a big scroll back to the area you wanted to see MDL-39817

===Activities/Resources===
*Assignment - Using advanced grading: add new criteria and edit the levels - the size of the input boxes for name and points are too wide. Then, add new level for the criteria, input text for the name is smaller than the point input text. The size of input boxes should be consistent and smaller. MDL-39748
*Forum - ipod touch/iphone 4s (potrait view): on discussion page, user name is overlapping with profile picture MDL-39746
*SCORM - <480px screens don't have enough space to display SCORM at present. Semi Working on <768px screens. Totally broken again on <980px and <1200px screens. Doesn't reflow along with the rest of the page. It needs to in order to allow for rotation of the screen. MDL-39736 MDL-39737
*Folders/Files - Mobile friendly. Works well.
*Lesson - At the end of lesson page, add a space between "Return to lesson" and "View grades" MDL-39773
*Chat - Some bugs to fix but it is usable. On an iphone users can currently choose between tiny text or lots of scrolling MDL-39770 MDL-39705 MDL-39704
*Wiki - Fix alignment for required field (red *) on creating new wiki page MDL-39779
*URL - Embedded URLs display at a fixed width that is small on a desktop and too large on a small screen. Embedded URLs do not load on an iphone 3gs. MDL-39766 MDL-39771

==Major Projects==
Several projects are under way to attempt to resolve many of these issues at once. They are...
===Full Screen Popups===
Popups such as the file picker and the message notification popup function poorly on a small screen. Refactoring them could significantly improve the experience throughout Moodle.
* MDL-39851 - Full screen popup for mobile (filepicker./activitychooser)
* MDL-39852 - Adjust file picker / activity chooser forms to full screen popup.

===Relative Scaling===
Text sizing in Moodle is currently often done with hard coded pixel sizes. This makes scaling for different devices difficult. Switching Moodle to using relative scaling based around the html concepts of "em" and "rem" should allow us to make better use of the available screen real estate throughout Moodle.

* MDL-39843 - Use REM on bootstrapbase to make font-size cascade and scalable

===Blocks===
Where and how the blocks should be displayed on small screens is the subject of debate. See MDL-39715.
===Navigation===
Further information is needed about how the navigation tree can be optimized and when it should be displayed in full or at all.

[[Category:Project]]

LTI 2 support

2021-08-10T15:11:48Z

Moodlebot: Text replacement - "class="nicetable"" to "class="wikitable""

{{Infobox Project
|name = LTI 2 support
|state = Implemented
|tracker = MDL-45843
|discussion = [https://moodle.org/mod/forum/discuss.php?d=261527#p1132968 Adding LTI 2.0 support]
|assignee = [[User:Stephen Vickers|Stephen Vickers]]
}}
==Project goals==
The main goal of this project is to implement LTI 2.0 functionality for Moodle which is capable of passing the IMS certification tests. It is not expected that the required changes will have any significant impact on the current LTI 1.1 functionality; indeed it is hoped that the work will also have some beneficial side-effects for the current LTI implementation.

==Background==
[http://vitalsource.com/ Vital Source Technologies] recognises the benefits that the [http://www.imsglobal.org/lti IMS Learning Tools Interoperability (LTI) 2 specification] can deliver to tool providers and has, therefore, agreed to sponsor this project in the interests of the whole community. The work will be undertaken in collaboration with Moodlerooms as an adaptation of the existing LTI (External tool) module which they manage on behalf of the Moodle community.

==Introduction==
Moodle already provides support for LTI 1.1, this project will build on this support to add support for LTI 2.0; it will not remove any existing functionality but it is expected that the LTI 1 support will also be enhanced as a consequence of this work. The main differences between LTI 1.1 and LTI 2.0 are as follows:

; Tool registration : Rather than passing a launch URL, consumer key and shared secret from the tool provider to the tool consumer using some out-of-band communication, LTI 2 uses an interactive registration process; all a tool consumer administrator needs is the URL for initiating this process.
; Tool Consumer Profile : as part of the registration process, a tool consumer makes available to the tool provider a profile describing itself and the capabilities/services it is willing to make available.
; Tool Proxy : when "sealing the deal" between the two parties, the tool provider sends a Tool Proxy to the tool consumer which includes a profile about itself and details of the capabilities/services which it proposes to use. A tool Proxy can be used to register more than one tool (resource handler), all of which are secured using the consumer key and shared secret agreed by the two systems during this process.
; Launch process : whilst the mechanics of launching an LTI tool remain unchanged from LTI 1, the tool proxy allows the data passed on launch to be tailored to specific requirements. The custom parameter substitution variables (available in LTI 1 but not implemented in the current Moodle implementation) are used to enable this functionality.
; Tool Settings service : LTI 2.0 includes a service which allows a tool provider to request a tool consumer to record data (name and value pairs) which are passed back on each launch. Settings may be saved at one of three levels: system-wide (Tool Proxy level), context-wide (Tool Proxy binding level, e.g. course-wide) and resource specific (LTI link level, i.e. specific to an individual link added to a course). This service is helpful as it ensures settings are deleted when a link or course is deleted, and it can also help when a course containing links to a tool provider is copied.
; Discoverable services : the addition of the tool consumer and tool profiles allows each party to declare services which it is willing to offer the other party. These services may be ones included in the IMS LTI specification (e.g. Tool Settings), but may equally be ones written by other parties which have yet to become part of the specification (and perhaps never will). Provided both the tool consumer and tool provider have implemented the service, the trust relationship established using LTI can be leveraged to secure the request messages between the servers. This transforms an LTI tool consumer into an extensible platform for learning tools and resources.

==Current issues with existing LTI functionality==
There are a number of open Moodle Tracker items relating to enhancements to the LTI implementation. Whilst this project is not directly concerned with resolving these issues, it does provide an opportunity to review them and see how they might guide the decisions being taken so they are consistent and may indeed provide solutions as a byproduct. Here is a list of those identified so far (some are from discussion postings or other sources):
# Add support for multi-tenancy sites to permit different LTI credentials for courses in different sites
# MDL-37041: The LTI consumer does not pass the user's profile picture in the user_image launch parameter
# MDL-37445: Add ability to set Maximum Grade for External Tool
# MDL-38120: course reports for external tool misssing
# MDL-39134: Create an LTI filter
# MDL-41202: LTI course identifier is not configurable; relies on shortname exclusively
# MDL-41724 (Fixed, as of Moodle 3.0): Implement the IMS LTI contexts membership service
# MDL-45064 (Fixed, as of Moodle 3.1): Option to add LTI Tool to Activity Chooser
# Visibility of external tools in the activity choose
# Support for both activity and resource types
# [https://moodle.org/mod/forum/discuss.php?d=196469 passing the Username?]
# More flexibility with passing appropriate roles
# Support for success and log messages on return URL
If you know of any missing from this list then please add a comment or get in touch; no promises that it will get included!

==User interface changes==
It is anticipated that the LTI 2 functionality can be added on top of the existing LTI 1.1 support with minimal impact on the current user interface. This section describes the current proposals for the new registration workflows.

===Plugin settings page (existing)===
# Move the "Add external tool configuration" link outside the "Active" tab and place below the tool list (may need to go above to save scrolling when the list of tools is long)
# Add a new link labelled something like "Register new external tool" which can be used to initiate the tool registration process
# Add a new tab set to list enabled and disabled services with icon to toggle their current status (by default a new service would be disabled)
See also "Registration process" section below.

===Register new external tool page (new)===
New page allowing the following data entry:
; registration URL : simple text box
; select capabilities to be offered to the tool provider : textarea of selected capabilities, textarea of potential capabilities, buttons to add and remove capabilities from selection
; select services to be made available for use by the tool provider : textarea of selected services, textarea of potential services, buttons to add and remove services from selection
; option to initiate the registration process : button
; option to cancel the process : button
Initiating the registration would generate a random key and secret and redirect the administrator to the tool provider using a ToolProxyRegistrationRequest message. The next part of the process is dependent upon the implementation by the tool provider based on their business rules. It would, however, depend upon the provision of a Tool Consumer Profile service; the profile provided would be based on the capabilities and services selected on this page (i.e. would be specific to a registration request). On completion the tool provider will call the Tool Proxy service.

===Registration process===
Once initiated a Tool Proxy registration will have one of the following states:
# created
# in process
# completed
# rejected
# cancelled
A rejected or cancelled registration would be logged but not remain visible in the UI. A new tab would be required on the Plugin settings page for any "in process" registrations (initiated but not yet completed by the creation of a tool proxy). An icon would be included next to each link to cancel a registration. A completed registration will generate a tool proxy associated with each of the tools (resource handlers) it specifies (which would be added to the "Pending" tab on the Plugin settings page).

===Managing tools===
Once a Tool Proxy has been accepted its resource handlers will be added as if they were external tools created manually using the current LTI 1 process. Their initial state will be pending; an administrator must enable them to make them available. They will appear to instructors (and learners) just like an LTI 1 external tool - there is no need for them to see any difference. The only difference will be behind the scenes when a launch request is made, the launch parameters will be determined on the basis of the resource handler definition from the tool proxy rather than being a generic LTI 1 launch. Support would also be added for custom parameter substitution variables which could/would also be available to LTI 1 launches.

==Database changes==
It is anticipated that the addition of LTI 2 support will require the following database changes:
* new table to capture details of tool proxies
* new fields to lti_types table to record:
** foreign key for tool proxy
** enabled capabilities
** launch parameters
** icon and secureicon URLs
* new table to record tool settings

===lti_tool_proxies table===
{| class="wikitable"
|-
! Field name
! Type
! Description
|-
| id
| int(10)
| Primary key
|-
| regurl
| text
| Registration URL
|-
| state
| tinyint(2)
| Current state of tool proxy processing
|-
| guid
| varchar(255)
| Consumer key
|-
| secret
| varchar(255)
| Shared secret
|-
| capabilityoffered
| text
| Capabilities offered to Tool Provider
|-
| serviceoffered
| text
| Services offered to Tool Provider
|-
| toolproxy
| text
| Copy of agreed Tool Proxy (JSON)
|-
| createdby
| int(10)
| ID of user which initiated the registration process
|-
| timecreated
| int(10)
| Date/time at which the record was created
|-
| timemodified
| int(10)
| Date/time at which the record was last modified
|}

===lti_types table===
{| class="wikitable"
|-
! Field name
! Type
! Description
|-
| toolproxyid
| int(10)
| Primary key of related tool proxy (null for LTI 1 tools)
|-
| enabledcapability
| text
| Enabled capabilities (null for LTI 1 tools)
|-
| parameter
| text
| Launch parameters (null for LTI 1 tools)
|-
| icon
| text
| URL to icon file
|-
| secureicon
| text
| Secure URL to icon file
|}

===lti_tool_settings===
{| class="wikitable"
|-
! Field name
! Type
! Description
|-
| id
| int(10)
| Primary key
|-
| toolproxyid
| int(10)
| Primary key of related tool proxy
|-
| course
| int(10)
| Primary key of course (null for system-wide settings)
|-
| coursemoduleid
| int(10)
| Primary key of course module - tool link added to course (null for system-wide and context-wide settings)
|-
| name
| varchar(255)
| Setting name
|-
| value
| varchar(255)
| Setting value
|}

==Defining services==
The goal is to enable the list of available services to be extensible, this includes the Tool Consumer Profile, Tool Proxy and Tool Settings services which are required elements of LTI 2.0. A service is an endpoint to which requests may be sent; these requests send or receive resources of a specified media type.

===Service definitions===
* Properties:
** ID - unique ID for service
** Name - a display name for service
** IsEnabled - whether the service is currently enabled
** Resources - list of media types associated with the service
** Endpoint - URL for service requests
* Methods:
** ParseValue - parse a custom parameter value for substitution variables defined by the service and/or its resources
** CheckSignature - check the OAuth signature for a request received

===Resource definitions===
* Properties:
** ID - unique ID for resource
** Template - URL template for service requests
** Media types - list of supported media types
** Methods - supported HTTP methods
** Capabilities - names of available capabilities
** Parameters - values of parameters included in request template
* Methods:
** Endpoint - fully qualified URL
** ParseValue - parse a custom parameter value for substitution variables defined by the resource

===Installing services===
The initial approach will be to try to implement the above requirements using the existing [https://docs.moodle.org/dev/External_tool LTI Source Plugins] functionality.

==Tasks==
* registration page
* defining services
* tool consumer profile service
* tool proxy service
* tool settings service
* enable/disable tools
* generate launch request (including custom parameter substitution variables)

Improve SCORM 2004 Support

2021-08-10T15:11:48Z

Moodlebot: Text replacement - "class="nicetable"" to "class="wikitable""

{{Infobox Project
|name = Improve SCORM 2004 Support
|state = Community Bonding
|tracker = MDL-7068
|discussion =
|assignee = Mayank Gupta
}}
{{Moodle 2.3}}

GSOC
 '12


=Overview=
==Abstract==
This document is the specification for Improving SCORM 2004 Support in Moodle, a Google Summer Of Code ''(GSoC)'' 2012 project.
The ''goal'' of this project is to work towards achieving full SCORM 2004 4th Edition compliance in Moodle without the need of any external plugins, that is, improving the support for SCORM 2004 content packages in Moodle.

The project mentor is [http://moodle.org/user/profile.php?id=21591 Dan Marsden] and the program administrator is [http://moodle.org/user/view.php?id=381842 Michael de Raadt].

==Context==
The project will improve the SCORM 2004 support in Moodle by using the [https://docs.moodle.org/dev/SCORM_Test_Harness SCORM Test Harness]. The automated test framework will help by automating the execution of SCORM 2004 tests in Moodle and thus, will help in identify the issues with SCORM 2004 support in Moodle.
This project will also indirectly help in improving the SCORM Test Harness itself, as by getting the Test Harness into action bugs would be identified and fixed in the Test Harness.

In order for Moodle to be SCORM 2004 4th Edition compliant and pass all the 189 ADL SCORM 2004 conformance test packages, it needs to adhere to the specifications laid down by [http://www.adlnet.gov/wp-content/uploads/2011/07/SCORM_2004_4ED_v1_1_Doc_Suite.zip ADL SCORM 2004 ''4th Edition''].
The specification can be divided into three sub-specifications as -
* Content Aggregation Model '''(CAM)'''
* The Run-Time Environment '''(RTE)'''
* Sequencing and Navigation specification '''(SN)'''

===Content Aggregation Model===
The Content Aggregation Model sub-specification of SCORM 2004 4th Edition specifies how SCORM 2004 content developers should package their content so that the packages can be imported into the LMS. According to SCORM 2004 specification the content developers should package the content in a self-contained directory or a ZIP file which is also called a '''Package Interchange File (PIF)'''.

SCORM 2004 specifies that the packaged ZIP file should always contain an XML file with the name - ''' 'imsmanifest.xml' '''. This imsmanifest.xml file also called the manifest file should be located in the root of the ZIP file. The content developers have to make sure that this manifest file contains all the information the LMS would need to successfully deliver the SCORM 2004 content to the content viewers.

The manifest file divides the course into one or more parts called SCOs, which in other words represents the activity tree for the course content. The manifest file contains an XML representation of the activity tree of the package, information about how to launch each SCO, and optional metadata that would describe the course and its part.
As a LMS it is the responsibility of Moodle's "SCORM module's code" to correctly parse the manifest file, store all the required information of the package in the database.

====Current State====
The file '''/mod/scorm/datamodels/scormlib.php''' has the code that parses the manifest file.
Currently this file is not able to parse all the CAM definitions according to SCORM 2004 4th Edition Specifications.
For instance, the current code of '''scormlib.php''' is not able to parse correctly the '''ADLCP:DATA''', and '''ADLCP:MAP''' sections of the manifest file. These sections define the '''Inter-SCO Storage Data Model Extension'''; that was introduced in ADL SCORM 2004 4th Edition specification.
Other sections of the manifest file that scormlib.php fails to parse successfully will be identified and resolved during the course of the project by running the SCORM Test Harness for individual SCORM 2004 conformance packages.

===Run-Time Environment===
The Run-Time Environment (RTE) sub-specification of SCORM 2004 specification specifies how the LMS should launch the content package within itself. The RTE states that the SCORM 2004 content package should be launched within Moodle in a web browser as a new window or within a '''frameset''' in the same window. The RTE specification specifies that all the content in the SCORM 2004 package should be web deliverable and is always launched in a web browser. It also specifies that the LMS should launch one SCO at a time.

In order to allow communication between the SCORM 2004 content package more specifically the launched SCO of the content package and the LMS; the LMS should provide an '''ECMAScript''' (JavaScript) API through which the SCO can communicate with it. All communication between the SCO and the LMS can take place through this JavaScript API only, that is, the content package can by no means communicate with the LMS through form posts, database access (read/write), web services or any other mechanism.
As a SCO can communicate only through the JavaScript API, the LMS provides the JavaScript object of the API at a specific location within the browsers' DOM. This API object has the special name of ''' 'API_1484_11' ''' for SCORM 2004.
It is the responsibility of the content/SCO to locate this API object and then use it for all the communications it needs to do with the LMS. RTE specifies that only the SCO can initiate the communication as the LMS acts as a passive entity which is simply responding to the API calls made by the SCO.

The API provides a set of eight functions that permit the exchange of data with the LMS. These functions are -

{| class="wikitable" border="1" cellpadding="5" cellspacing="0" align="center"
|-
! Function
! Return Type
! Remarks
|-
| Initialize( “” )
| bool
| it indicates to the LMS that the content would like to begin a communication session.
|-
| Terminate( “” )
| bool
| it indicates to the LMS that the content has finished communicating
|-
| GetValue( element : CMIElement )
| string
| it allows the SCO/content to data from the LMS
|-
| SetValue( element : CMIElement, value : string)
| string
| it allows the SCO/content to persist data to the LMS.
|-
| Commit( “” )
| bool
| it is used by the SCO/content to signal the LMS that a significant chuck of data has been saved and that the LMS should ensure the data is properly persisted
|-
| GetLastError()
| CMIErrorCode
| it allows to determing if the last SCORM API call caused an error
|-
| GetErrorString( errorCode : CMIErrorCode )
| string
| it return a textual description of what the passed error code means
|-
| GetDiagnostic( errocCode : CMIErrorCode )
| string
| it returns detailed information about the prior error that can be useful in detecting the problem.
|}

The Computer Managed Instruction or '''CMI''' data model provides a list of data elements which can be read and written using the API. Each data model element has its own meaning.

Every SCO in a content package has its own set of run-time data. These data model elements have different values for different SCOs within a content package.
Before SCORM 2004 4th edition the RTE data model definitions came into existence these data model elements could not be shared across SCOs of the same or different content package.
When the content user or learner starts a new attempt on a SCO, the data model element's values are reset to the default values at the start of the new attempt. These data models have different default values and can be of either '''read-only''' or both read and '''write''' type.

Some examples SCORM 2004 RTE data model elements include the '''cmi.completion_status''' element - that saves the status of the SCO (completed or incomplete), '''cmi.success_status''' (passed or failed), the score of the learner, a bookmark to track the learner’s location, and the total amount of time the learner spent in the SCO.

However, apart from the non-sharable data model elements defined before, the SCORM 2004 4th Edition RTE Data Model definitions define the
'''adl.data''' data model elements that provide the unique ability to share sets of data across the SCOs.

====Current State====
The file '''/mod/scorm/datamodels/scorm_13.js.php''' has the code to deal with the data model elements that a SCO would require.
This code needs to be extended to support the data models defined by the SCORM 2004 4th Edition Run-Time Envirnoment Data Model definition. These data model elements mainly include adl.data elements - Inter-SCO Storage Data Model Extension.
Some progress has already been made on the tracker issue MDL-28805 - ADL TEST: Data Model Implementation (DMI).
While trying to fix the mentioned bug, a number of related issues that needed to be resolved before the bug MDL-28805 could be closed were identified. These bugs were - MDL-30666, MDL-30576, MDL-30577, MDL-30578, MDL-30579, MDL-30645.
As mentioned above, during the course of the project the data model code would be extended to support SCORM 2004 4th Edition Run-Time Environment Data Model definitions and other '' 'buggy areas' '' would be identified by running the SCORM Test Harness for SCORM 2004 Conformance packages issues would be reported and patches will be provided.

===Sequencing And Navigation===

The Sequencing and Navigation sub-specification of SCORM 2004 4th Edition specification allows content developers to '''override''' the default navigation of SCOs and enable them to govern how the content user/learner is allowed to navigate between various SCOs in the content package and also how the progress data is '''rolled up''' to the course level of the content package.

The content developers lay down the sequencing rules in the imsmanifest.xml file or the manifest file, in the root directory of the PIF. These rules in-turn determine which '''navigational controls''' should the LMS provide to the content user/learner, that is, whether or not a navigable table of contents '''(TOC)''' should be provided to the learner or just the previous/next buttons should be provided to the learner to navigate from one SCO to another in a linear sequence of SCOs.
By specifying sequencing and navigation rules in the manifest file the content developer can also specify that certain conditions like some SCOs/activities must be completed before the learner can navigate to the some other SCO/activity.
The content developer by adhering to the SCORM 2004 Sequence and Navigation specification can also apply a gradient weight to some parts or activities of the content package, that is, if some higher weighted activities when completed by the learner would add more to his total score than when he completes a relatively lower weighted activity. Not only this, the Sequencing and Navigation specifications can allow the content developer to randomly select a different subset of SCOs each time a new attempt is made.
The SN specification also powers the content developer to forcibly take the learner to initial SCO (that would generally have some instructions).

Every activity of a SCORM 2004 content package has a '''tracking data''' and a '''sequencing definition''' associated with it. The tracking data has the information about the current state of the activity that is, the score of the learner, the status, etc. The sequencing definition is the set of rules that defines which activity should follow next, that is, which activity should be presented to the learner after he completes the activity depending upon the tracking data of the activity.

The sequencing definition model rules can be subdivided as -

:'''''Sequencing Control Modes''''' – these define the type of navigation allowed to the learner, that is navigation through the TOC or linear navigation via previous/next buttons.
:'''''Constrain Choice Controls''''' – Restrict the activities that the user may select from the table of contents.
:'''''Sequencing Rules''''' – Specify if-then conditions that determine which activities are available for delivery and which activity should be delivered next.
:'''''Limit Conditions''''' – Provide limits on the number of times activities can be attempted.
:'''''Rollup Rules''''' – Specify if-then conditions that determine how status is rolled up to clusters throughout the activity tree.
:'''''Rollup Controls''''' – Determine which activities participate in status rollup and how their status is weighted in relation to other activities.
:'''''Rollup Consideration Controls''''' – Provide more precise control over status rollup than do the rollup controls.
:'''''Objectives''''' – Provide a way to track the status of individual learning objectives and share this status across activities. Objectives are often overloaded and used as variables to control sequencing actions.
:'''''Selection Controls''''' – Provide a way to specify that only a random subset of the available activities should be delivered.
:'''''Randomization Controls''''' - Shuffle the order of the activities to be delivered.
:'''''Delivery Controls''''' – Allow for non-communicative content to be delivered and sequenced.
:'''''Completion Threshold Controls''''' – Allow the tracking of completion percentage. This was introduced in the SCORM 2004 4th Edition specification.
:'''''Navigation Controls''''' - Control which navigational UI elements should be presented by the LMS.

====Current State====
The code that currently implements Sequencing and Navigation specification of ADL SCORM 2004 specification is in the file '''/mod/scorm/datamodels/sequencinglib.php'''.

The SCORM module currently supports '''activity restriction''', that is, if the content developer has restricted some activities to not to be navigable directly by selecting from the table of contents, the TOC does not allow the learner to do so. Though, the TOC is correctly rendered, there are issues like when the initial SCO/activity is complete and it triggers the continue event, the next SCO is not launched, rather the same initial SCO is launched again.
In some cases the SCO uses '''adl.nav.request''' to navigate to a different location, this also causes the same issue of the SCO being launched again.
These are just a couple of the many issues that are currently there in the SCORM module to support SCORM 2004 Sequencing and Navigation specification specification.

The bug that holds the next SCO from being launched will be the first issue that would be fixed as the part of the project to improve SCORM 2004 support in Moodle, because, this bug will prevent other SCORM 2004 test packages to load successfuly and thus, would not allow the SCORM 2004 conformance packages to run and test successfully.
A probable fix for the issue would be to store the structure so that code can continue but learner cannot use continue, TOC, links, etc.
The above can be implemented by shifting the URLs of the SCO to the id attribute of the spans HTML tags and then making JavaScript to fetch the ids and use them as URLs.

Work is already being done to rewrite the function '''scorm_get_toc''' - MDL-32835.

The SCORM Test Harness will help in identifying other Sequencing and Navigation issues in the SCORM module by helping to run the SCORM 2004 conformance test packages automatically.

= Schedule of Deliverables =
'''May 31st - 5th June''': Fix SN bug that prevents SCOs from loading, and potentially- [http://tracker.moodle.org/browse/MDL-28741 ADL Test: CM-02], [http://tracker.moodle.org/browse/MDL-28743 ADL Test: CM-03], and [http://tracker.moodle.org/browse/MDL-28802 ADL Test: DDM].

'''6th - 17th June''': Fix SCORM 2004 bugs, potentially- [http://tracker.moodle.org/browse/MDL-28805 ADL Test: DMI], [http://tracker.moodle.org/browse/MDL-28804 ADL Test: DMB], [http://tracker.moodle.org/browse/MDL-28745 ADL Test: CM-04], [http://tracker.moodle.org/browse/MDL-28926 ADL Test: T-01]

'''18th - 27th June''': Fix SCORM 2004 bugs, potentially- [http://tracker.moodle.org/browse/MDL-28772 ADL Test: CO-01], [http://tracker.moodle.org/browse/MDL-28773 ADL Test: CO-02], [http://tracker.moodle.org/browse/MDL-28775 ADL Test: CO-03], [http://tracker.moodle.org/browse/MDL-28795 ADL Test: CT-01]

'''27th June - 8th July''': Fix SCORM 2004 bugs, potentially- [http://tracker.moodle.org/browse/MDL-28806 ADL Test: MS-01], [http://tracker.moodle.org/browse/MDL-28807 MS-02], [http://tracker.moodle.org/browse/MDL-28808 MS-03], [http://tracker.moodle.org/browse/MDL-28814 OB-01], [http://tracker.moodle.org/browse/MDL-28796 CT-02]

'''9th - 15th July''': Fix SCORM 2004 bugs, potentially- [http://tracker.moodle.org/browse/MDL-28854 ADL Test: RU-01], [http://tracker.moodle.org/browse/MDL-28858 ADL Test: RU-02], [http://tracker.moodle.org/browse/MDL-28860 ADL Test: RU-03], [http://tracker.moodle.org/browse/MDL-28862 ADL Test: RU-04]

''This will be the midterm evaluation target - A detailed report on the then status of SCORM 2004 support in Moodle, mentioning all improvements and results of the closed issues to the Moodle Community.''

'''16th July - 22nd July''': Fix SCORM 2004 bugs, potentially- [http://tracker.moodle.org/browse/MDL-28902 ADL Test: SX-02], [http://tracker.moodle.org/browse/MDL-28903 ADL Test: SX-03], [http://tracker.moodle.org/browse/MDL-28904 ADL Test: SX-04], [http://tracker.moodle.org/browse/MDL-28749 CM-05]

'''23rd July - 1st August''': Fix SCORM 2004 bugs, potentially- [http://tracker.moodle.org/browse/MDL-28750 ADL Test: CM-06], [http://tracker.moodle.org/browse/MDL-28751 ADL Test: CM-07], [http://tracker.moodle.org/browse/MDL-28779 ADL Test: CO-05], [http://tracker.moodle.org/browse/MDL-28781 ADL Test: CO-06], [http://tracker.moodle.org/browse/MDL-28782 ADL Test: CO-07]

'''2nd - 12th August''': Fix SCORM 2004 bugs, potentially- [http://tracker.moodle.org/browse/MDL-28797 ADL Test: CT-03], [http://tracker.moodle.org/browse/MDL-28798 ADL Test: CT-04], [http://tracker.moodle.org/browse/MDL-28799 ADL Test: CT-05], [http://tracker.moodle.org/browse/MDL-28757 CM-08], [http://tracker.moodle.org/browse/MDL-28758 ADL Test: CM-09]

'''13th - 19th August''': Fix SCORM 2004 bugs, potentially- [http://tracker.moodle.org/browse/MDL-28818 ADL Test: OB-02], [http://tracker.moodle.org/browse/MDL-28819 ADL Test: OB-03], [http://tracker.moodle.org/browse/MDL-28822 ADL Test: 0B-04], [http://tracker.moodle.org/browse/MDL-28868 ADL Test: RU-05], [http://tracker.moodle.org/browse/MDL-28906 SX-05]

= Relevant Links =
*[https://docs.moodle.org/dev/SCORM_Test_Harness SCORM Test Harness]
*[https://docs.moodle.org/en/SCORM_FAQ SCORM FAQ]
*[http://www.adlnet.gov/capabilities/scorm/scorm-2004-4th ADL SCORM 2004 4th Edition]
*[https://docs.moodle.org/dev/GSOC/2012 GSoC 2012 - Moodle]

== Tracker ==
* [http://tracker.moodle.org/browse/MDL-7608 META: SCORM 2004 compliance + issues]

Hack-a-thon 2013

2021-08-10T15:11:48Z

Moodlebot: Text replacement - "class="nicetable"" to "class="wikitable""

{{Work in progress}}

{| class="wikitable"
|-
! Start Date
| To be announced
|-
! End Date
| To be announced
|}

==What is a Moodle Hack-a-thon?==

A Hack-a-thon is a period of intense community contribution to the Moodle project. Participants are rewarded for their involvement. There is a competitive aspect to the Hack-a-thon to encourage greater involvement.

==Categories of work==

The following categories are specifically targeted as areas of work for the Hack-a-thon.

===Bugs patched===

This category is for the most bugs resolved.

There are two groups in this category, each with separate prize pools.

* Recognised developers (in the [[Tracker#Tracker_groups_and_permissions|jira-developers]] Tracker group)
* New developers (not in the [[Tracker#Tracker_groups_and_permissions|jira-developers]] group)

Moodle HQ employees are excluded from competing.

{| class="wikitable"
|-
! Points
| 5 points for every bug + 1 point for every VOTE on that bug (so vote for your favourite bugs!) + 2 points for fixing on all supported branches
|-
! Reporting
| Participants should add themselves and links to their issues to [[Hack-a-thon_2013/Bugs_resolved]]. Participants should provide Git branches on the issue.
|-
! Verification
| Each reported fix will be reviewed by an authorised developer. Fixes may be allowed minor fixes after reviewing.
|-
! T-shirt standard
| 1 verified bug fix
|}

===Dud issues identified===

A [http://en.wikipedia.org/wiki/Dud dud] issue is one that is open, but should be closed, for one of the following reasons.
* It is a duplicate of another issue in the tracker (either a pre-existing issue or an active issue reported later; the point is that we end up closing one).
* It was an issue that has been fixed in current versions.
* It is an issue that has become obsolete because of changes present in current versions.
* It is not able to be replicated in any reasonable supported environment.

{| class="wikitable"
|-
! Points
| 3 points per identified issue (1 point for each additional duplicate after the first)
|-
! Reporting
| Participants should add themselves and links to their issues to [[Hack-a-thon_2013/Dud_issues_closed]]. Participants should comment on each issue they report.
|-
! Verification
| Each reported issue will be checked and closed by authorised person.
|-
! T-shirt standard
| 5 dud issues identified and verified as duds
|}

===Docs updated===

* Most Moodle [[Main_Page|Dev Docs]] API pages updated.

There are numerous API features that are undocumented or out of date.

{| class="wikitable"
|-
! Points
| 1 point for each API page updated. 3 points for each API page created.
|-
! Reporting
| Participants should add themselves and links to their updates to [[Hack-a-thon_2013/Docs_updated]]
|-
! Verification
| Each reported page or update will be checked and verified. Changes should be necessary and more than corrections of grammar or spelling.
|-
! T-shirt standard
| 3 updates or 1 page created
|}

===Plugins updated===

* Most Contributed plugins updated

{| class="wikitable"
|-
! Points
| ???
|-
! Reporting
| Participants should add themselves and links to their plugins to [[Hack-a-thon_2013/Plugins_updated]]
|-
! Verification
| ???
|-
! T-shirt standard
| ???
|}

==Prizes and recognition==

Each participant who fulfils the minimum t-shirt standard will receive a limited edition Hack-a-thon t-shirt.

Cash prizes will be awarded for each category (including two prizes for bug fixing). Prizes will be awarded as follows.

{| class="wikitable"
|-
| First prize
| AU$200
|-
| Second prize
| AU$100
|-
| Third prize
| AU$50
|}

Cash prizes will be paid via Paypal.

Winners in each category will be named in a news item on moodle.org, a feature story on moodle.com and recorded here in the Docs.

The judges decision is final. We reserve the right to disqualify someone if it becomes obvious they are cheating the system (eg. by filing fake reports, setting up fake accounts, reassigning bugs from other people after they are done etc.).

==See also...==

* [[Bugathon]] 2007

Developer meeting January 2015

2021-08-10T15:11:47Z

Moodlebot: Text replacement - "class="nicetable"" to "class="wikitable""

[[Developer meetings]] > January 2015 meeting notes

{| class="wikitable"
|-
| Time
| [http://timeanddate.com/worldclock/fixedtime.html?year=2015&month=1&day=20&hour=13&min=0&sec=0 13:00 UTC on Tuesday, 20 January 2015]
|-
| Meeting room
| [https://www.youtube.com/watch?v=JNJMF1l3udM Live stream at YouTube]
|-
| Chat
| [https://moodle.org/local/chatlogs/info.php Regular dev chat]
|-
| Twitter
| [https://twitter.com/search?q=%23moodledev #moodledev]
|-
| Event page
| [https://plus.google.com/events/cn6hb5p6vnjhafraaa8sjttjems Google+ page]
|-
| Meeting notes
| [https://docs.google.com/document/d/1uXHZPSbU3wZzlFj0Qk6ZHMwQ06KalvNdk0pqn2wmt_Q/edit?usp=sharing Google doc]
|}

The meeting will be streamed live on YouTube with chat through the regular Dev chat room and comments on Twitter.

You are encouraged to participate on composing the meeting notes in the shared document (see the link above) while listening to the presenters.

== Agenda ==

=== Moodle JS framework prototypes research (Invited speaker) ===

* by [https://moodle.org/user/profile.php?id=1337843 Damyon Wiese]
* I will cover a lot here including, Javascript loaders, Javascript Build Tools, Javascript Combo Loading, Javascript Accessible Widget Libraries, Templates for Renderers
* Please see [[JS Framework Specification]] and [[Render library specification]]
* Estimated length: 50 minutes

=== Prechecking against Moodle coding guidelines from your command line ===

* by Frédéric Massart
* The patch precheck job in Moodle continuous integration process - see [[Automated code review]]
* Short demonstration of the possibility to execute the CI precheck job from the command line (without the need to use the 'cime' label in the tracker), especially when using mdk
* Estimated length: 5-10 minutes

=== Quizventure game development ===

* by John Okely
* Short demonstration of the [https://moodle.org/plugins/view/mod_quizgame Quizventure game] module highlighting interesting things you can do with our existing APIs
* Estimated length: 5-10 minutes

=== Prototype for a new 'Send a message' feature ===

* by Frédéric Massart
* Rather than redirecting you somewhere to send a message inside Moodle, this new feature would open a dialog, etc...
* Estimated length: 5-10 minutes

=== Development of the quiz fault-tolerant mode ===

* by Tim Hunt
* This allows the students to continue working on their quiz attempt, even if the network is unreliable, by storing everything on the client-side, and using Ajax when possible. I will try to show some more of the details.
* If the network connection never comes back, you can download the responses as an ecrypted file, which can later be uploaded ot the server.
* Work in progress code is at [https://github.com/timhunt/moodle-quizaccess_offlinemode Tim's github repo]
* Do we want this in standard Moodle? If so, when, and how do we add it? (It was developed as a plugin while it was an experiment. If it went into standard Moodle it would need to be merged into the main quiz code.)
* Estimated length: 20 minutes

=== Database foreign keys enforcement ===
* by Avi Levi, Asaf Ohayon
* Fixes done on 2.9 Dev branch
* Tracker : https://tracker.moodle.org/browse/MDL-30799
* Discussion : https://moodle.org/mod/forum/discuss.php?d=275290
* GitHub : https://github.com/AdminTheWeb/moodle/commits/MDL-30799-master
* Estimated length: 10-15 minutes

=== Developer hackfests at upcoming Moodle moots ===

* by Michael de Raadt
* MoodleMoot IE-UK, May 11-13, Hackfest May 14 [http://mootieuk15.moodlemoot.org/mod/page/view.php?id=3 program]
* MoodleMoot Australia, July 6-8, Hackfest July 9 [http://mootau15.moodlemoot.org/mod/page/view.php?id=14 program]
* MoodleMoot US, Aug 4-5, Hackfest August 6 [http://mootus15.moodlemoot.org/ site]

=== Add more ===

* You are welcome to participate at the meeting as a speaker, too. We appreciate any Moodle development experience sharing
* If you have something you'd like to add to this page, please edit this page or contact [https://moodle.org/user/profile.php?id=1601 David Mudrák].