diff --git a/.readthedocs.yml b/.readthedocs.yaml similarity index 100% rename from .readthedocs.yml rename to .readthedocs.yaml diff --git a/requirements/base.txt b/requirements/base.txt index 362e01c0..46bad8bf 100644 --- a/requirements/base.txt +++ b/requirements/base.txt @@ -40,14 +40,14 @@ packaging==23.1 # via # pydata-sphinx-theme # sphinx -pydata-sphinx-theme==0.13.3 +pydata-sphinx-theme==0.14.0 # via sphinx-book-theme -pygments==2.15.1 +pygments==2.16.1 # via # accessible-pygments # pydata-sphinx-theme # sphinx -pytz==2023.3 +pytz==2023.3.post1 # via babel requests==2.31.0 # via @@ -58,7 +58,7 @@ six==1.16.0 # via livereload snowballstemmer==2.2.0 # via sphinx -soupsieve==2.4.1 +soupsieve==2.5 # via beautifulsoup4 sphinx==6.2.1 # via @@ -102,7 +102,7 @@ sphinxcontrib-youtube==1.2.0 # via -r requirements/base.in sphinxext-rediraffe==0.2.7 # via -r requirements/base.in -tornado==6.3.2 +tornado==6.3.3 # via livereload typing-extensions==4.7.1 # via pydata-sphinx-theme diff --git a/requirements/pip-tools.txt b/requirements/pip-tools.txt index 5748bf66..d2e8e4e5 100644 --- a/requirements/pip-tools.txt +++ b/requirements/pip-tools.txt @@ -4,13 +4,15 @@ # # make upgrade # -build==0.10.0 +build==1.0.3 # via pip-tools -click==8.1.6 +click==8.1.7 # via pip-tools +importlib-metadata==6.8.0 + # via build packaging==23.1 # via build -pip-tools==7.1.0 +pip-tools==7.3.0 # via -r requirements/pip-tools.in pyproject-hooks==1.0.0 # via build @@ -19,8 +21,10 @@ tomli==2.0.1 # build # pip-tools # pyproject-hooks -wheel==0.41.0 +wheel==0.41.2 # via pip-tools +zipp==3.16.2 + # via importlib-metadata # The following packages are considered to be unsafe in a requirements file: # pip diff --git a/requirements/pip.txt b/requirements/pip.txt index fb1908e6..3e7d8f4a 100644 --- a/requirements/pip.txt +++ b/requirements/pip.txt @@ -4,11 +4,11 @@ # # make upgrade # -wheel==0.41.0 +wheel==0.41.2 # via -r requirements/pip.in # The following packages are considered to be unsafe in a requirements file: pip==23.2.1 # via -r requirements/pip.in -setuptools==68.0.0 +setuptools==68.2.2 # via -r requirements/pip.in diff --git a/source/community/release_notes/named_release_branches_and_tags.rst b/source/community/release_notes/named_release_branches_and_tags.rst index 46ad8333..47600712 100644 --- a/source/community/release_notes/named_release_branches_and_tags.rst +++ b/source/community/release_notes/named_release_branches_and_tags.rst @@ -49,6 +49,10 @@ Palm - 2023-06-14 - open-release/palm.1 + * - Palm.2 + - 2023-08-09 + - open-release/palm.2 + Olive ===== @@ -75,6 +79,10 @@ Olive - 2023-04-11 - open-release/olive.3 + * - Olive.4 + - 2023-05-22 + - open-release/olive.4 + Nutmeg ====== diff --git a/source/community/release_notes/palm.rst b/source/community/release_notes/palm.rst index 598cb753..81de0cf3 100644 --- a/source/community/release_notes/palm.rst +++ b/source/community/release_notes/palm.rst @@ -97,7 +97,7 @@ Instructor Experiences New Visual Problem Editor ========================= -The release includes an improved problem-authoring experience with an interactive editor. Writing markdown +The release includes an experimental improved problem-authoring experience with an interactive editor. When enabled, writing markdown code is no longer necessary. But, the advanced mode is still available, maintaining the ability to write and edit OLX XML. @@ -105,8 +105,7 @@ The Open edX wiki page `[2U] New Visual Problem Editor `_ of the Building and Running an edX Course documentation. -The visual problem editor is an update to the Course Authoring Micro-frontend first released in Olive and is enabled by -default in Palm. To enable the Visual Problem Editor, add the waffle flag +The Visual Problem Editor is hosted in the existing Course Authoring Micro-frontend. To enable the Visual Problem Editor, add the waffle flag :code:`new_core_editors.use_new_problem_editor` and set the value to “Yes” for all users. New ORA Grading Experience diff --git a/source/developers/concepts/index.rst b/source/developers/concepts/index.rst index 0264753f..0d43a8c7 100644 --- a/source/developers/concepts/index.rst +++ b/source/developers/concepts/index.rst @@ -2,6 +2,7 @@ Concepts Home ############# .. toctree:: + :maxdepth: 2 :glob: * diff --git a/source/developers/concepts/oep58.rst b/source/developers/concepts/oep58.rst new file mode 100644 index 00000000..f94c342e --- /dev/null +++ b/source/developers/concepts/oep58.rst @@ -0,0 +1,79 @@ +OEP-58 Overview +############### + +What is OEP-58? +=============== + +OEP-58 is a project to streamline translations management throughout the Open edX project. + +How translations are managed now +================================ + +Where translations currently live +--------------------------------- + +Translations currently live in 2 places. + +* In each repository in the form of ``.mo``, ``.po``, and ``.json`` files. +* In the ``edx-platform`` transifex project. + +How translations are written +---------------------------- + +Translators edit translations in the ``edx-platform`` transifex project + +How translations get into repositories from transifex +----------------------------------------------------- + +Each repository has a jenkins job that: + +* Pulls updated translations from transifex via the `deprecated`_ v2 api +* Commits the updated translations directly to the repo as `edx-transifex-bot`_ + +How translations currently get deployed +--------------------------------------- + +Translations are files in a repository that are built and deployed with the rest of the code. + +How translations will be managed post OEP-58 +============================================ + +Where translations will live +---------------------------- + +* In the `openedx-translations repository`_ +* In the ``openedx-translations`` transifex project + +How translations will be written +-------------------------------- + +Translators will edit translations in the ``openedx-translations`` transifex project + +How translations will get from transifex to the `openedx-translations repository`_ +---------------------------------------------------------------------------------- + +Translations will be committed to the `openedx-translations repository`_ via the supported `Transifex Integration GitHub App`_ + +How translations will be deployed +--------------------------------- + +The build process for each repository will be updated to use `openedx-atlas`_ to pull translations from the `openedx-translations repository`_. + +What needs to happen for a repository to make the switch +-------------------------------------------------------- +* The build process must be updated to support using `openedx-atlas`_ to pull translations from the `openedx-translations repository`_ +* The repository must be configured to use the `openedx-atlas`_ method at build time +* The `openedx-translations repository`_ must be updated to include the source strings +* Translations must exist in the ``openedx-translations`` transifex project + +Additional reading +================== +* `OEP-58: Translations Management — Open edX Proposals 1.0 documentation `_ +* `openedx-atlas README `_ +* `openedx-translations README `_ + +.. _deprecated: https://community.transifex.com/t/important-reminder-api-tx-cli-deprecation/3202 +.. _edx-transifex-bot: https://github.com/edx-transifex-bot +.. _openedx-translations repository: https://github.com/openedx/openedx-translations +.. _Transifex Integration GitHub App: https://github.com/apps/transifex-integration +.. _openedx-atlas: https://github.com/openedx/openedx-atlas \ No newline at end of file diff --git a/source/developers/how-tos/enable-translations-new-repo.rst b/source/developers/how-tos/enable-translations-new-repo.rst index 70d9d94d..b7aa7ab8 100644 --- a/source/developers/how-tos/enable-translations-new-repo.rst +++ b/source/developers/how-tos/enable-translations-new-repo.rst @@ -14,6 +14,8 @@ To enable translations on a new repository according to the `OEP-58 - Translatio for Python) - Configure the repository according to the appropriate section later in this document. +.. seealso:: + :doc:`/developers/concepts/oep58` Configuration ************* diff --git a/source/developers/how-tos/ongoing-maintainers-tasks.rst b/source/developers/how-tos/ongoing-maintainers-tasks.rst index 749ab63e..b0d4d8b2 100644 --- a/source/developers/how-tos/ongoing-maintainers-tasks.rst +++ b/source/developers/how-tos/ongoing-maintainers-tasks.rst @@ -73,6 +73,27 @@ As a part of bringing your repository into alignment with the standards of the p Keeping your dependencies up-to-date on a regular basis is both lest costly and more secure than waiting a long time between package updates. It is recommended that you **apply all security fix on packages you depend on within weekly**. For automated PRs that don't contain security updates to dependent packages it is still recommended that you triage them on a weekly basis. Schedule any complex upgrades in a timely manner - you don't want to be in a situation where it becomes an emergency to land them (whether to get new features or apply a major security fix). +Approving GitHub Actions for new committer PRs +********************************************** + +.. note:: + + This process is only for contributors that already have passed the CLA check, for those that haven’t please follow the normal process for helping the contributor onboard. + +When a user opens their first PR in a repository you maintain it is likely that they will need to be approved before some Github Actions, such as tests, will run. This is to protect us all from having malicious code run in our account as part of our test suite. + +When this occurs the orange “Approve and run“ will appear for the PR. + +The current process for this is to: + +1. Look over the PR to make sure that it is legitimate and there are no malicious changes. + + a. In the event of a questionable or malicious looking change, please notify #maintainers-pilot in Slack to warn other maintainers and allow us to take appropriate action. + +2. Any maintainer or Axim employee with write permissions on the repository can approve the PR after step 1 has been completed. This should only need to be done once per contributor per repository. + +3. Once the PR is unblocked, the rest of the approval process should work as normal. + Participating in Forum Discussions ********************************** diff --git a/source/developers/index.rst b/source/developers/index.rst index f84b387c..5a622f5c 100644 --- a/source/developers/index.rst +++ b/source/developers/index.rst @@ -29,7 +29,6 @@ Open edX Developers :class-card: sd-shadow-md sd-p-2 :class-footer: sd-border-0 - * :doc:`how-tos/maintain-a-repo` * :doc:`how-tos/enable-python-upgrade-automation` * :doc:`how-tos/enable-javascript-upgrade-automation` +++ @@ -59,7 +58,6 @@ Open edX Developers :class-card: sd-shadow-md sd-p-2 :class-footer: sd-border-0 - * :doc:`references/tools_for_maintainers` * :doc:`references/internal_data_formats/index` * `edx-platform `_ * `frontend-platform `_ @@ -70,3 +68,24 @@ Open edX Developers :expand: More References + + .. grid-item-card:: Maintainers Home + :class-card: sd-shadow-md sd-p-2 + :class-footer: sd-border-0 + + * :doc:`how-tos/maintain-a-repo` + * :doc:`how-tos/ongoing-maintainers-tasks` + * :doc:`references/tools_for_maintainers` + + +++ + .. button-ref:: maintainers_home + :color: primary + :outline: + :expand: + + Maintainers Home + +.. toctree:: + :hidden: + + maintainers_home diff --git a/source/developers/maintainers_home.rst b/source/developers/maintainers_home.rst new file mode 100644 index 00000000..b044aec8 --- /dev/null +++ b/source/developers/maintainers_home.rst @@ -0,0 +1,49 @@ +Maintainers Home +################ + +.. grid:: 1 2 2 2 + :gutter: 3 + :padding: 0 + + .. grid-item-card:: How-tos + :class-card: sd-shadow-md sd-p-2 + :class-footer: sd-border-0 + + * :doc:`how-tos/maintain-a-repo` + * :doc:`how-tos/ongoing-maintainers-tasks` + + .. grid-item-card:: References + :class-card: sd-shadow-md sd-p-2 + :class-footer: sd-border-0 + + * :doc:`references/tools_for_maintainers` + * `Maintainers Slack Channel`_ + + .. grid-item-card:: Process Documentation + :class-card: sd-shadow-md sd-p-2 + :class-footer: sd-border-0 + + * `Maintainership Wiki Space`_ + * `Maintainers Scrum of Scrums Notes`_ + * `Maintainers Office Hours Notes`_ + +Concepts Documentation +********************** + +* :doc:`openedx-proposals:processes/oep-0055-proc-project-maintainers` - The + OEP that kicked off the maintainership program. + +* `Community Contributions Project Manager`_ - The role definition for the + Community Project Managers. They help triage community PRs and coordinate + reviews from subject matter experts. + +.. _Maintainers Slack Channel: https://openedx.slack.com/archives/C03R320AFJP + +.. _Maintainers Office Hours Notes: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3603791889/Office+Hours+Notes + +.. _Maintainers Scrum of Scrums Notes: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3507027983/Maintainers+Scrum+of+Scrums + +.. _Maintainership Wiki Space: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3426844690/Maintainership+Pilot + +.. _Community Contributions Project Manager: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3548807177/Community+Contributions+Project+Manager + diff --git a/source/developers/quickstarts/first_openedx_pr.rst b/source/developers/quickstarts/first_openedx_pr.rst index 552602c5..a61de73f 100644 --- a/source/developers/quickstarts/first_openedx_pr.rst +++ b/source/developers/quickstarts/first_openedx_pr.rst @@ -121,7 +121,7 @@ Answer them however you like, although the default answers will work fine. .. code-block:: bash - tutor dev quickstart + tutor dev launch Depending on your system and your Internet connection speed, this could take anywhere from five minutes to over an hour, diff --git a/source/developers/references/index.rst b/source/developers/references/index.rst index 7a8ed5a0..7299e57f 100644 --- a/source/developers/references/index.rst +++ b/source/developers/references/index.rst @@ -22,4 +22,5 @@ Other References tools_for_maintainers a11y-ref internal_data_formats/index + legacy_guide/index glossary diff --git a/source/developers/references/legacy_guide/analytics.rst b/source/developers/references/legacy_guide/analytics.rst new file mode 100644 index 00000000..229d013c --- /dev/null +++ b/source/developers/references/legacy_guide/analytics.rst @@ -0,0 +1,396 @@ +.. _analytics: + +############## +Analytics +############## + +The edX LMS and Studio are instrumented to enable tracking of metrics and +events of interest. These data can be used for educational research, decision +support, and operational monitoring. + +The primary mechanism for tracking events is the `Event Tracking`_ API. It +should be used for the vast majority of cases. + +================= +Event Tracking +================= + +The `event-tracking`_ library aims to provide a simple API for tracking point- +in-time events. The `event-tracking documentation`_ summarizes the features +and primary use cases of the library as well as the current and future design +intent. + +Emitting Events +***************** + +Emitting from server-side python code:: + + from eventtracking import tracker + tracker.emit('some.event.name', {'foo': 'bar'}) + +Emitting from client-side JavaScript:: + + Logger.log 'some.event.name', 'foo': 'bar' + +.. note:: + The client-side API currently uses a deprecated library (the ``track`` + djangoapp) instead of the event-tracking library. Eventually, event-tracking + will publish a client-side API of its own: when available, that + API should be used instead of the ``track``-based solution. See + :ref:`deprecated_api`. + +Naming Events +============== + +Event names are intended to be formatted as `.` separated strings and help +processing of related events. The structure is intended to be +`namespace.object.action`. The namespace is intended to be a `.` separated +string that helps identify the source of events and prevent events with +similar or identical objects and actions from being confused with one another. +The object is intended to be a noun describing the object that was acted on. +The action is intended to be a past tense verb describing what happened. + +Examples: + + * ``edx.course.enrollment.activated`` + * Namespace: ``edx`` + * Object: ``course.enrollment`` + * Action: ``activated`` + +Choosing Events to Emit +======================== + +Consider emitting events to capture user intent. These will typically be +emitted on the client side when a user interacts with the user interface in +some way. + +Consider also emitting events when models change. Most models are not append- +only and it is frequently the case that an analyst would want to see the value +of a particular field at a particular moment in time. Given that many fields +are overwritten, that information is lost unless an event is emitted when the +model is changed. + +Sensitive Information +===================== + +By default, event information is written to an unencrypted file on disk. +Therefore, do not include clear text passwords, credit card numbers, or other +similarly sensitive information. + +Size +====== + +A cursory effort to regulate the size of the event is appreciated. If an event +is too large, it may be omitted from the event stream. However, do not +sacrifice the clarity of an event in an attempt to minimize size. It is much +more important that the event is clear. + +Debugging Events +================ + +On devstack, emitted events are stored in the ``/edx/var/log/tracking.log`` log +file. This file can be useful for validation and debugging. + +.. _Testing Event Emission: + +Testing Event Emission +====================== + +It is important to test instrumentation code since regressions can have a +significant negative impact on downstream consumers of the data. + +Each test can make stronger or weaker assertions about the structure and +content of various fields in the event. Tests can make assertions about +particular fields in the nested hierarchical structures that are events. This +allows them to continue to pass even if a new global field is added to all +events (for example). + +Failing tests are a form of communication with future developers. A test +failure is a way for you to tell those future developers that they have +changed something that you did not expect to change, and that there are +implications that they should think about carefully before making the change. +For this reason, limit the scope of your test to details you expect to remain +constant. Specifically, for eventing, this means only asserting on the +presence and correctness of fields your code is adding, not the precise set of +fields that happen to be present in all events today. + +In general, it is acceptable for events to contain "unexpected" fields. If you +add a field, most JSON parsers will accept this new field and allow the +downstream code to process the event. Since that downstream code does not know +about the new field it will simply be ignored. + +For this reason, most of our tests do not actually make assertions about +unexpected fields appearing in the events, instead they focus on the fields +that they *do* expect to be present and make assertions about the values of +these fields. This enables us to add global context without having to update +hundreds (or even thousands) of tests that were making assertions about the +exact set of fields present in the event. Instead, we prefer to only have a +small number of tests fail when making a change like this. Those tests might +be making more strict assertions about the global context, for example. When a +small number of targeted tests fail, they can be more effective at +communicating the exact set of assumptions that were being made before that +have now changed. + +Assertions +---------- + +The ``openedx.core.lib.tests.assertions.events`` module contains helper +functions that can be used to make assertions about events. The key function in +this module is ``assert_event_matches`` which allows tests to make assertions +about parts of the event. The signature looks like this:: + + def assert_event_matches(expected_event, actual_event, tolerate=None): + +The ``expected_event`` parameter contains the assertion that is being made. The +``actual_event`` parameter contains the complete event that was emitted. The +``tolerate`` parameter allows the test to specify the types of discrepancies +that it cares about. This allows you to be very strict in assertions about some +parts of the event and more lenient in other areas. + +Here are examples that highlight the default settings for ``tolerate``. + +:: + + # By default, decode string values for the "event" field as JSON and compare + # the contents with the actual event. This will not raise an error. + assert_event_matches( + {'event': {'a': 'b'}}, + {'event': '{"a": "b"}'} + ) + + # Ignore "unexpected" root fields. This will not raise an error even though + # the field "foo" does not appear in the expected event. + assert_event_matches( + {'event_type': 'test'}, + {'event_type': 'test', 'foo': 'bar'} + ) + + # Ignore "unexpected" fields in the context. This will not raise an error + # even though the field "foo" does not appear in the expected event context. + assert_event_matches( + {'event_type': 'test'}, + {'event_type': 'test', 'context': {'foo': 'bar'}} + ) + + # Overriding "tolerate" allows more strict assertions to be made. + # This assertion will raise an error! + assert_event_matches( + {'event_type': 'test'}, + {'event_type': 'test', 'context': {'foo': 'bar'}}, + tolerate=[] + ) + + +Unit testing +------------ + +Test classes should inherit from +``common.djangoapps.track.tests.EventTrackingTestCase``. Additionally, some +helper assertion functions are available to help with making assertions about +events. + +Here is an example of a subclass. + +:: + + from common.djangoapps.track.tests import EventTrackingTestCase + from openedx.core.lib.tests.assertions.events import assert_event_matches + + class MyTestClass(EventTrackingTestCase): + + def setUp(self): + # The setUp() of the superclass must be called + super(MyTestClass, self).setUp() + + def test_event_emitted(self): + my_function_that_emits_events() + + # If the above function only emits a single event, this can be used. + actual_event = self.get_event() + + # This will assert that the "event_type" of the event is "foobar". + # Note that it makes no assertions about any of the other fields + # in the event. + assert_event_matches({'event_type': 'foobar'}, actual_event) + + def test_no_event_emitted(self): + + my_function_that_does_not_emit() + + # This will fail if any events were emitted by the above function + # call. + self.assert_no_events_emitted() + +Bok Choy Testing +---------------- + +Test classes should use the mixin +``common.test.acceptance.tests.helpers.EventsTestMixin``. At its core, this +mixin captures all events that are emitted while the test is running and allows +you to make assertions about those events. Below some common patterns are +outlined. By default, Bok Choy event assertions are as lenient as possible. The +tests can be made more strict by passing in ``tolerate=[]`` to indicate that an +exact match is necessary. Similarly, other flags can be passed into the +``tolerate`` parameter to tightly control the level of validation performed. + +Wait for some events and make assertions about their content. + +:: + + def test_foobar_event_emission(self): + emit_foobar_event() + + # This will wait for the event to be emitted. It will time out if the + # event is not emitted quickly enough (or not emitted at all). + actual_events = self.wait_for_events({'event_type': 'foobar'}) + + # This will compare the first event emitted with the first expected + # event, the second with the second etc. + self.assert_events_match( + [ + {'event': {'a': 'b'}} + ], + actual_events + ) + + # ``wait_for_events`` also accepts arbitrary callable functions to check + # to see if an event "matches" + def some_custom_event_filter(event): + return event['event']['old_time'] > 10 + + # This will return when some_custom_event_filter returns true for at + # at least one event. + actual_events = self.wait_for_events(some_custom_event_filter) + + def test_multiple_events(self): + emit_several_events() + + def my_event_filter(event): + return event['event_type'] in ('first_event', 'second_event') + + # This will wait for 2 events to match the filter defined above. Note + # that it makes no assertions about their ordering or content. + actual_events = self.wait_for_events(my_event_filter, number_of_matches=2) + + # This ensures that first_event was emitted before second_event and + # checks the payload of both events. + self.assert_events_match( + [ + { + 'event_type': 'first_event', + 'event': {'a': 'b'} + }, + { + 'event_type': 'second_event', + 'event': {'a': 'other'} + } + ], + actual_events + ) + + def test_granular_assertion(self): + + # This foobar event is emitted first, with the "a" field set to "NOT B" + tracker.emit('foobar', {'a': 'NOT B'}) + + # A context manager can be used to ensure that the first "foobar" event + # is ignored. It only makes assertions about the events that are emitted + # inside this context. + with self.assert_events_match_during( + {'event_type': 'foobar'}, + [ + { + 'event': {'a': 'b'} + } + ] + ): + emit_foobar_event() + + +Documenting Events +******************* + +When you add events to the platform, your PR should describe the purpose of +the event and include an example event. In addition, consider including +comments that identify the purpose of the event and its fields. Your +descriptions and examples can help assure that researchers and other members +of the open edX community understand your intent and use the events correctly. + +You might find the following references helpful as you prepare your PR. + +* The *edX Platform Developer's Guide* provides guidelines for `contributing + to open edX `_. + +* The `edX Research + Guide `_ is a + reference for information about emitted events that are included in the edX + tracking logs. + +Request Context Middleware +********************************** + +The platform includes a middleware class that enriches all events emitted +during the processing of a given request with details about the request that +greatly simplify downstream processing. This is called the ``TrackMiddleware`` +and can be found in ``edx-platform/common/djangoapps/track/middleware.py``. + +Legacy Application Event Processor +********************************** + +In order to support legacy analysis applications, the platform emits standard +events using ``eventtracking.tracker.emit()``. However, it uses a custom event +processor which modifies the event before saving it to ensure that the event +can be parsed by legacy systems. Specifically, it replicates some information +so that it is accessible in exactly the same way as it was before. This state +is intended to be temporary until all existing legacy systems can be altered +to use the new field locations. + +======================= +Other Tracking Systems +======================= + +The following tracking systems are currently used for specialized analytics. +There is some redundancy with event-tracking that is undesirable. The event- +tracking library could be extended to support some of these systems, allowing +for a single API to be used while still transmitting data to each of these +service providers. This would reduce discrepancies between the measurements +made by the various systems and significantly clarify the instrumentation. + +Segment +***************** + +A selection of events can be transmitted to `Segment`_ in order to take +advantage of a wide variety of analytics-related third party services such as +Mixpanel and Chartbeat. It is enabled in the LMS if the ``SEGMENT_KEY`` +key is set to a valid Segment API key in the ``lms.yml`` file. Additionally, +the setting ``EVENT_TRACKING_SEGMENTIO_EMIT_WHITELIST`` in the ``lms.yml`` +file can be used to specify event names that should be emitted to Segment +from normal ``tracker.emit()`` calls. Events specified in this whitelist will be +sent to both the tracking logs and Segment. Similarly, it is enabled in Studio +if the ``SEGMENT_KEY`` key is set to a valid Segment API key in the +``studio.yml`` file. + + +Google Analytics +***************** + +Google analytics tracks all LMS page views. It provides several useful metrics +such as common referrers and search terms that users used to find the edX web +site. + +.. _deprecated_api: + +Deprecated APIs +***************** + +The ``track`` djangoapp contains a deprecated mechanism for emitting events. +Direct usage of ``server_track`` is deprecated and should be avoided in new +code. Old calls to ``server_track`` should be replaced with calls to +``tracker.emit()``. The celery task-based event emission and client-side event +handling do not currently have a suitable alternative approach, so they +continue to be supported. + +.. _event-tracking: https://github.com/openedx/event-tracking +.. _event-tracking documentation: http://event-tracking.readthedocs.io/en/latest/overview.html#event-tracking +.. _Segment: https://segment.com/ diff --git a/source/developers/references/legacy_guide/architecture.rst b/source/developers/references/legacy_guide/architecture.rst new file mode 100644 index 00000000..aabe8ec2 --- /dev/null +++ b/source/developers/references/legacy_guide/architecture.rst @@ -0,0 +1,123 @@ +##################### +Open edX Architecture +##################### + +The Open edX project is a web-based platform for creating, delivering, and +analyzing online courses. It is the software that powers edx.org and many other +online education sites. + +This page explains the architecture of the platform at a high level, without +getting into too many details. + +******** +Overview +******** + +There are a handful of major components in the Open edX project. Where +possible, these communicate using stable, documented APIs. + +The centerpiece of the Open edX architecture is `edx-platform`_, which contains +the learning management and course authoring applications (LMS and Studio, +respectively). + +This service is supported by a collection of other autonomous web services +called independently deployed applications (IDAs). Over time, we plan to +break out more of the existing edx-platform functions into new IDAs and MFEs. This +strategy will help manage the complexity of the edx-platform code base to make +it as easy as possible for developers to approach and contribute to the +project. + +.. image:: ./images/edx-architecture.png + :width: 700 + :alt: A diagram of the components and technologies that make up an edX site. + +Almost all of the server-side code in the Open edX project is in `Python`_, +with `Django`_ as the web application framework. + +************** +Key Components +************** + +================================ +Learning Management System (LMS) +================================ + + +====== +Studio +====== + +Studio is the course authoring environment. Course teams use it to create and +update courses. Studio writes its courses to the same Mongo database that the +LMS uses. + +=========== +Discussions +=========== + +Course discussions are managed by an IDA called comments (also called forums). +comments is one of the few non-Python components, written in `Ruby`_ using the +`Sinatra`_ framework. The LMS uses an API provided by the comments service to +integrate discussions into the learners’ course experience. + +The comments service includes a notifier process that sends learners +notifications about updates in topics of interest. + +=========== +Mobile Apps +=========== + +The Open edX project includes a mobile application, available for iOS and +Android, that allows learners to watch course videos and more. Open edX is actively +enhancing the mobile app. + +========= +Analytics +========= + + +=============== +Background Work +=============== + +A number of tasks are large enough that they are performed by separate +background workers, rather than in the web applications themselves. This work +is queued and distributed using `Celery`_ and `Redis`_. Examples of queued +work include: + +* Grading entire courses +* Sending bulk emails (with Amazon SES) +* Generating answer distribution reports +* Producing end-of-course certificates + + +====== +Search +====== + +The Open edX project uses `Elasticsearch`_ for searching in multiple contexts, +including course search and the comments service. + +================ +Other Components +================ + +In addition to the components detailed above, the Open edX project also has +services for other capabilities, such as one that manages e-commerce functions +like order work flows and coupons. + +.. _edx-platform: https://github.com/openedx/edx-platform +.. _Python: https://www.python.org/ +.. _Django: https://www.djangoproject.com/ +.. _MongoDB: http://www.mongodb.org/ +.. _Mako: http://www.makotemplates.org/ +.. _CoffeeScript: http://coffeescript.org/ +.. _Backbone.js: http://backbonejs.org/ +.. _Sass: http://sass-lang.com/ +.. _Bourbon framework: http://bourbon.io/ +.. _edx.org: http://edx.org/ +.. _Ruby: https://www.ruby-lang.org/en/ +.. _Sinatra: http://www.sinatrarb.com/ +.. _Celery: http://www.celeryproject.org/ +.. _Redis: https://redis.io/ +.. _Elasticsearch: https://www.elastic.co/ diff --git a/source/developers/references/legacy_guide/conventions/django.rst b/source/developers/references/legacy_guide/conventions/django.rst new file mode 100644 index 00000000..9df49099 --- /dev/null +++ b/source/developers/references/legacy_guide/conventions/django.rst @@ -0,0 +1,32 @@ +.. _Django Good Practices: + +********************* +Django Good Practices +********************* + +.. contents:: + :local: + :depth: 2 + +======= +Imports +======= + +Always import from the root of the project:: + + from lms.djangoapps.hologram.models import 3DExam # GOOD + from .models import 3DExam # GOOD + from hologram.models import 3DExam # BAD! + +The second form (relative import) only works correctly if the importing module is itself imported correctly. As long as there are no instances of the third form, everything should work. Don't forget that there are other places that mention import paths:: + + url(r'^api/3d/', include('lms.djangoapps.hologram.api_urls')), # GOOD + url(r'^api/3d/', include('hologram.api_urls')), # BAD! + + @patch('lms.djangoapps.hologram.models.Key', new=MockKey) # GOOD + @patch('hologram.models.Key', new=MockKey) # BAD! + + INSTALLED_APPS = [ + 'lms.djangoapps.hologram', # GOOD + 'hologram', # BAD! + ] diff --git a/source/developers/references/legacy_guide/conventions/index.rst b/source/developers/references/legacy_guide/conventions/index.rst new file mode 100644 index 00000000..0a7f6e33 --- /dev/null +++ b/source/developers/references/legacy_guide/conventions/index.rst @@ -0,0 +1,11 @@ +.. _coding_conventions: + +################## +Writing Good Code +################## + +.. toctree:: + :maxdepth: 2 + + django + diff --git a/source/developers/references/legacy_guide/extending_platform/extending.rst b/source/developers/references/legacy_guide/extending_platform/extending.rst new file mode 100644 index 00000000..ce82a8bb --- /dev/null +++ b/source/developers/references/legacy_guide/extending_platform/extending.rst @@ -0,0 +1,96 @@ + +.. _Options for Extending the edX Platform: + +########################################## +Options for Extending the edX Platform +########################################## + +There are several options for extending the Open edX Platform to provide useful +and innovative educational content in your courses. + +This section of the developers' documentation lists and explains the different ways to extend the platform, starting with the following table. + +.. |br| raw:: html + +
+ +.. list-table:: + :widths: 10 10 10 10 10 10 + :header-rows: 1 + + * - + - Custom |br| + JavaScript |br| + Applications + - LTI + - External |br| + Graders + - XBlocks + - Platform |br| + Customization + * - Development Cost + - Low + - Low + - Medium + - Medium + - High + * - Language + - JavaScript + - Any + - Any + - Python + - Python + * - Development Environment Needed + - No + - No + - Yes + - Yes + - Yes + * - Self-hosting Needed + - No + - Yes + - Yes + - No + - No + * - Need edX Involvement + - No + - No + - Yes + - Yes + - Yes + * - Clean UI Integration + - Yes + - No (see LTI) + - Yes + - Yes + - Yes + * - Mobile enabled + - Possibly + - Possibly + - Yes + - Yes + - Yes + * - Server Side Grading + - Possibly (See JavaScript) + - Yes + - Yes + - Yes + - Yes + * - Usage Data + - No (See JavaScript) + - No + - Limited + - Yes + - Yes + * - Provision in Studio + - No + - No + - No + - Yes + - No + * - Privacy Loss Compared to Hosting Open edX + - No + - Possibly + - Possibly + - No + - No diff --git a/source/developers/references/legacy_guide/extending_platform/index.rst b/source/developers/references/legacy_guide/extending_platform/index.rst new file mode 100644 index 00000000..f03da8e3 --- /dev/null +++ b/source/developers/references/legacy_guide/extending_platform/index.rst @@ -0,0 +1,9 @@ +########################### +Extending the edX Platform +########################### + +.. toctree:: + :maxdepth: 2 + + extending + xblocks diff --git a/source/developers/references/legacy_guide/extending_platform/xblocks.rst b/source/developers/references/legacy_guide/extending_platform/xblocks.rst new file mode 100644 index 00000000..59b3621d --- /dev/null +++ b/source/developers/references/legacy_guide/extending_platform/xblocks.rst @@ -0,0 +1,234 @@ +Integrating XBlocks with edx-platform +===================================== + +The edX LMS and Studio have several features that are extensions of the core +XBlock libraries (https://xblock.readthedocs.io). These features are listed +below. + +* `LMS`_ +* `Studio`_ +* `Testing`_ +* `Deploying your XBlock`_ + +You can also render an individual XBlock in HTML with the :ref:`XBlock +URL`. + +*** +LMS +*** + +================ +Runtime Features +================ + +These are properties and methods available on ``self.runtime`` when a view or +handler is executed by the LMS. + +* anonymous_student_id: An identifier unique to the student in the particular + course that the block is being executed in. The same student in two different + courses will have two different ids. + +* publish(block, event_type, event): Emit events to the surrounding system. + Events are dictionaries that can contain arbitrary data. XBlocks can publish + events by calling ``self.runtime.publish(self, event_type, event)``. The + ``event_type`` parameter enables downstream processing of the event since it + uniquely identifies the schema. This call will cause the runtime to save the + event data in the application event stream. XBlocks should publish events + whenever a significant state change occurs. Post-hoc analysis of the event + stream can yield insight about how the XBlock is used in the context of the + application. Ideally interesting state of the XBlock could be reconstructed + at any point in history through careful analysis of the event stream. + +.. TODO: Link to the authoritative list of event types. + +In the future, these are likely to become more formal XBlock services (one +related to users, and the other to event publishing). + +================ +Class Features +================ + +These are class attributes or functions that can be provided by an XBlock to +customize behavior in the LMS. + +* student_view (XBlock view): This is the view that will be rendered to display + the XBlock in the LMS. It will also be used to render the block in "preview" + mode in Studio, unless the XBlock also implements author_view. +* has_score (class property): True if this block should appear in the LMS + progress page. +* get_progress (method): See documentation in + x_module.py:XModuleMixin.get_progress. +* icon_class (class property): This can be one of (``other``, ``video``, or + ``problem``), and determines which icon appears in edx sequence headers. + There is currently no way to provide a different icon. + +================ +Grading +================ + +To participate in the course grade, an XBlock should set ``has_score`` to +``True``, and should ``publish`` a ``grade`` event whenever the grade changes. +The ``grade`` event is a dictionary of the following form. + +:: + + { + 'value': , + 'max_value': , + 'user_id': , + } + +The grade event represents a grade of ``value/max_value`` for the current user. +The ``user_id`` field is optional, the currently logged in user's ID will be +used if it is omitted. + +================ +Restrictions +================ + +A block cannot modify the value of any field with a scope where the ``user`` +property is ``UserScope.NONE``. + +****** +Studio +****** + +================ +Class Features +================ + +* studio_view (XBlock.view): The view used to render an editor in Studio. The + editor rendering can be completely different from the LMS student_view, and + it is only shown when the author selects "Edit". + +* author_view (XBlock.view): An optional view of the XBlock similar to + student_view, but with possible inline editing capabilities. This view + differs from studio_view in that it should be as similar to student_view as + possible. When previewing XBlocks within Studio, Studio will prefer + author_view to student_view. + +* non_editable_metadata_fields (property): A list of ``xblock.fields.Field`` + objects that should not be displayed in the default editing view for Studio. + +================ +Restrictions +================ + +A block cannot modify the value of any field with a scope where the ``user`` +property is not ``UserScope.NONE``. + + +Testing +------- + +These instructions are temporary. Once XBlocks are fully supported by +edx-platform (both the LMS and Studio), installation and testing will be much +more straightforward. + +To enable an XBlock for testing in your devstack +(https://github.com/openedx/configuration/wiki/edX-Developer-Stack), follow these +steps. + +#. Install your block. + + :: + + $ vagrant ssh + vagrant@precise64:~$ sudo -u edxapp /edx/bin/pip.edxapp install /path/to/your/block + +#. Enable the block. + + #. In ``edx-platform/lms/envs/common.py``, uncomment:: + + # from xmodule.x_module import prefer_xmodules + # XBLOCK_SELECT_FUNCTION = prefer_xmodules + + #. In ``edx-platform/cms/envs/common.py``, uncomment:: + + # from xmodule.x_module import prefer_xmodules + # XBLOCK_SELECT_FUNCTION = prefer_xmodules + + +#. Add the block to your courses' advanced settings in Studio. + + #. Log in to Studio, and open your course + #. Settings -> Advanced Settings + #. Change the value for the key ``"advanced_modules"`` to + ``["your-block"]`` + +#. Add your block into your course. + + #. Edit a unit + #. Advanced -> your-block + +Note the name ``your-block`` used in Studio must exactly match the key you used +to add your block to your ``setup.py`` ``entry_points`` list. (If you are still +discovering XBlocks and simply used the ``workbench-make-new.py`` script as +described in the `xblocktutorial:Open edX XBlock Tutorial`, look in the +``setup.py`` file that was created.) + +********************* +Deploying Your XBlock +********************* + +To deploy your block to your own hosted version of edx-platform, you need to +install it into the virtualenv that the platform is running out of, and add to +the list of ``ADVANCED_COMPONENT_TYPES`` in +``edx-platform/cms/djangoapps/contentstore/views/component.py``. + + +.. _XBlock URL Dev: + +************************************** +Rendering XBlocks with the XBlock URL +************************************** + +The XBlock URL supports HTML rendering of an individual XBlock without the user +interface of the LMS. + +To use the XBlock URL and return the HTML rendering of an individual XBlock, +you use the following URL path for an XBlock on an edX site. + +``https://{host}/xblock/{usage_id}`` + +======================== +Finding the ``usage_id`` +======================== + +The ``usage_id`` is the unique identifier for the problem, video, text, or +other course content component, or for sequential or vertical course container +component. There are several ways to find the ``usage_id`` for an XBlock in the +LMS, including viewing either the staff debug info or the page source. For more +information, see +`opencoursestaff:Finding the Usage ID for Course Content`. + +=================== +Example XBlock URLs +=================== + +For example, a video component in the "Creating Video for the edX Platform" +course on the edx.org site has the following URL. + +``https://courses.edx.org/courses/course-v1:edX+VideoX+1T2016/courseware/ccc7c32c65d342618ac76409254ac238/1a52e689bcec4a9eb9b7da0bf16f682d/`` + +This video component appears as follows in the LMS. + +.. image:: ../images/XBlock_URL_example_before.png + :alt: A video component presented in the context of the edX LMS, with + navigational options to reach all other course content. + +To construct the XBlock URL for the same video component, you obtain its +``usage_id`` and then use the following URL format. + +``https://courses.edx.org/xblock/block-v1:edX+VideoX+1T2016+type@video+block@47faf3a03c4f4023b187528c25932e0a`` + +When you use this URL, the video component appears in your browser as follows. + +.. image:: ../images/XBlock_URL_example_after.png + :alt: A video component presented without any options for accessing other + course content. + +For courses created prior to October 2014, the ``usage_id`` begins with +``i4x://``, as in the following example. + +``https://courses.edx.org/xblock/i4x://edX/DemoX.1/problem/47bf6dbce8374b789e3ebdefd74db332`` diff --git a/source/developers/references/legacy_guide/front_matter/browsers.rst b/source/developers/references/legacy_guide/front_matter/browsers.rst new file mode 100644 index 00000000..5f559cc1 --- /dev/null +++ b/source/developers/references/legacy_guide/front_matter/browsers.rst @@ -0,0 +1,7 @@ +.. _Browsers: + +######################## +Open edX Browser Support +######################## + +TODO: This needs to be removed from all of the books that reference it and be updated for the Open edX community. diff --git a/source/developers/references/legacy_guide/front_matter/index.rst b/source/developers/references/legacy_guide/front_matter/index.rst new file mode 100644 index 00000000..f71c4e8b --- /dev/null +++ b/source/developers/references/legacy_guide/front_matter/index.rst @@ -0,0 +1,9 @@ +############################# +General Information +############################# + +.. toctree:: + :maxdepth: 2 + + browsers + diff --git a/source/developers/references/legacy_guide/glossary.rst b/source/developers/references/legacy_guide/glossary.rst new file mode 100644 index 00000000..cd67d581 --- /dev/null +++ b/source/developers/references/legacy_guide/glossary.rst @@ -0,0 +1,1166 @@ +.. _Glossary: + +############ +Glossary +############ + +:ref:`A` - :ref:`C` - :ref:`D` - :ref:`E` - :ref:`F` +- :ref:`G` - :ref:`H` - :ref:`I` - :ref:`K` - :ref:`L` +- :ref:`M` - :ref:`N` - :ref:`O` - :ref:`P` - :ref:`R` +- :ref:`S` - :ref:`T` - :ref:`V` - :ref:`W` - :ref:`XYZ` + +.. note:: Most of the links to documentation provided in this glossary are to + the `partnercoursestaff:document index` guide, for edX partners. Many + of the same topics are available in the Open edX version of this guide, + `opencoursestaff:Building and Running an Open edX Course`. + +.. _A: + +**** +A +**** + +.. _AAC: + +**AAC** + + Advanced audio coding (AAC) is an audio coding standard for digital audio + compression. AAC is the standard format for YouTube. + +.. _AB Test: + +**A/B test** + + See `partnercoursestaff:Content Experiment`. + + +.. _About Page: + +**About page** + + The course page that provides potential learners with a course summary, + prerequisites, a course video and image, and important dates. + +.. only:: Partners + + For more information, see `partnercoursestaff:Pub Creating and + Announcing a Course`. + + +**accessible label** + + In a problem component, you use special formatting to identify the specific + question that learners will answer by selecting options or entering text or + numeric responses. + + This text is referred to as the accessible label because screen readers read + all of the text that you supply for the problem and then repeat the text that + is identified with this formatting immediately before reading the answer + choices for the problem. This text is also used by reports and Insights to + identify each problem. + + All problems require accessible labels. + + For more information, see `partnercoursestaff:Simple Editor`. + + +.. _Advanced Editor_g: + +**advanced editor** + + An OLX (open learning XML) editor in a problem component that allows you to + create and edit any type of problem. For more information, see + `partnercoursestaff:Advanced Editor`. + +.. _Amazon Web Services: + +**Amazon Web Services (AWS)** + + A third-party file hosting site where course teams can store course assets, + such as problem files and videos. If videos are posted on both YouTube and + AWS, the AWS version of the video serves as a backup in case the YouTube + video does not play. + +.. _Assignment Type: + +**assignment type** + + The category of graded student work, such as homework, exams, and exercises. + For more information, see `partnercoursestaff:Grading Index`. + +.. _C: + +**** +C +**** + +**CAPA problem** + + A CAPA (computer assisted personalized approach) problem refers to any of + the problem types that are implemented in the edX platform by the + ``capa_module`` XBlock. Examples range from text input, drag and drop, and + math expression input problem types to circuit schematic builder, custom + JavaScript, and chemical equation problem types. + + Other assessment methods are also available, and implemented using other + XBlocks. An open response assessment is an example of a non-CAPA problem + type. + +.. _Certificate: + +**certificate** + + A document issued to an enrolled learner who successfully completes a course + with the required passing grade. Not all edX courses offer certificates, and + not all learners enroll as certificate candidates. + + For information about setting up certificates for your course, see + `Setting Up Certificates`. + +**chapter** + + See :ref:`Section`. + + +.. _Chemical Equation_g: + +**chemical equation response problem** + + A problem that allows learners to enter chemical equations as answers. For + more information, see `partnercoursestaff:Chemical Equation`. + + +.. _Circuit Schematic_g: + +**circuit schematic builder problem** + + A problem that allows learners to construct a schematic answer (such as an + electronics circuit) on an interactive grid. For more information, see + `partnercoursestaff:Circuit Schematic Builder`. + +**closed captions** + + The spoken part of the transcript for a video file, which is overlaid on the + video as it plays. To show or hide closed captions, you select the **CC** + icon. You can move closed captions to different areas on the video screen by + dragging and dropping them. + + For more information, see `learners:Video Player`. + +.. _codec_g: + +**codec** + + A portmanteau of "code" and "decode". A computer program that can encode or + decode a data stream. + +.. _Cohort: + +**cohort** + + A group of learners who participate in a class together. Learners who are in + the same cohort can communicate and share experiences in private + discussions. + + Cohorts are an optional feature of courses on the edX platform. For + information about how you enable the cohort feature, set up cohorts, and + assign learners to them, see `partnercoursestaff:Cohorts Overview`. + +.. _Component_g: + +**component** + + The part of a unit that contains your actual course content. A unit can + contain one or more components. For more information, see + `partnercoursestaff:Developing Course Components`. + +.. _Content Experiment: + +**content experiment** + + You can define alternative course content to be delivered to different, + randomly assigned groups of learners. Also known as A/B or split testing, + you use content experiments to compare the performance of learners who have + been exposed to different versions of the content. For more information, see + `partnercoursestaff:Overview of Content Experiments`. + + +**content library** + + See :ref:`Library`. + + +.. _Content Specific Discussion Topic_g: + +**content-specific discussion topic** + + A category within the course discussion that appears at a defined point in + the course to encourage questions and conversations. To add a content- + specific discussion topic to your course, you add a discussion component to + a unit. Learners cannot contribute to a content-specific discussion topic + until the release date of the section that contains it. Content-specific + discussion topics can be divided by cohort, so that learners only see and + respond to posts and responses by other members of the cohort that they are + in. + + For more information, see `partnercoursestaff:Working with Discussion + Components`. For information about making content-specific discussion topics + divided by cohort, see `partnercoursestaff:Set up Discussions in + Cohorted Courses`. + + +.. _Course Catalog: + +**course catalog** + + The page that lists all courses offered in the edX learning management + system. + + +.. _Course Handouts: + +**course handouts** + + Course handouts are files you make available to learners on the **Home** + page. For more information, see `partnercoursestaff:Adding Course + Updates and Handouts`. + +**course mode** + + See :ref:`enrollment track`. + +**course navigation pane** + + The navigation frame that appears at one side of the **Course** page in the + LMS. The course navigation pane shows the sections in the course. When you + select a section, the section expands to show subsections. When you select a + subsection, the first unit in that subsection appears on the course page. + + See also :ref:`Unit Navigation Bar`. + +.. _Course Page: + +**Course page** + + The page that opens first when learners access your course. On the **Course** + page, learners can view the course outline and directly access the course, + either by clicking a specific section or subsection on the outline, or by + clicking the **Start Course** button (**Resume Course** if the learner has + previously accessed the course). + + The latest course update, such as a course welcome message, appears above the + course outline. Links to various **Course Tools** including **Bookmarks**, + **Reviews** and **Updates** appear at the side of this page. This page is a + combination of the former **Home** and **Courseware** pages. + +.. _Run: + +**course run** + + A version of the course that runs at a particular time. Information about a + course run includes start and end dates, as well as staff and the languages + the course is available in. You can create a course run when you create a + course. + + .. only:: Partners + + For more information, see `Planning Course Run Information`. + +**course track** + + See :ref:`enrollment track`. + +.. _Courseware: + +**courseware** + + In OLX (open learning XML) and in data packages, "courseware" refers to the + main content of your course, consisting mainly of lessons and assessments. + Courseware is organized into sections, subsections, units, and components. + Courseware does not include handouts, the syllabus, or other course + materials. + + Note that the **Course** page was formerly called the **Courseware** page. + + +**course-wide discussion topic** + + Optional discussion categories that you create to guide how learners find + and share information in the course discussion. Course-wide discussion + topics are accessed from the **Discussion** page in your course. Examples of + course-wide discussion topics include Announcements and Frequently Asked + Questions. Learners can contribute to these topics as soon as your course + starts. For more information, see `partnercoursestaff:Discussions` and + `partnercoursestaff:Create CourseWide Discussion Topics`. + + If you use cohorts in your course, you can divide course-wide discussion + topics by cohort, so that although all learners see the same topics, they + only see and respond to posts and responses by other members of the cohort + that they are in. For information about configuring discussion topics in + courses that use cohorts, see `partnercoursestaff:Set up Discussions in + Cohorted Courses`. + + +.. _Custom Response Problem: + +**custom response problem** + + A custom response problem evaluates text responses from learners using an + embedded Python script. These problems are also called + "write-your-own-grader" problems. For more information, see + `partnercoursestaff:Write Your Own Grader`. + +.. _D: + +**** +D +**** + +.. _Data Czar_g: + +**data czar** + + A data czar is the single representative at a partner institution who is + responsible for receiving course data from edX, and transferring it securely + to researchers and other interested parties after it is received. + + For more information, see the `data:edX Research Guide`. + +**discussion** + + The set of topics defined to promote course-wide or unit-specific dialog. + Learners use the discussion topics to communicate with each other and the + course team in threaded exchanges. For more information, see + `partnercoursestaff:Discussions`. + +.. _Discussion Component: + +**discussion component** + + Discussion topics that course teams add directly to units. For example, a + video component can be followed by a discussion component so that learners + can discuss the video content without having to leave the page. When you add + a discussion component to a unit, you create a content-specific discussion + topic. See also :ref:`Content Specific Discussion Topic `. + + For more information, see `partnercoursestaff:Working with Discussion + Components`. + +**discussion thread list** + + The navigation frame that appears at one side of the **Discussion** page in + the LMS. The discussion thread list shows the discussion categories and + subcategories in the course. When you select a category, the list shows all + of the posts in that category. When you select a subcategory, the list shows + all of the posts in that subcategory. Select a post to read it and its + responses and comments, if any. + +.. _Dropdown_g: + +**dropdown problem** + + A problem that asks learners to choose from a collection of answer options, + presented as a drop-down list. For more information, see + `partnercoursestaff:Dropdown`. + + +.. _E: + +**** +E +**** + +.. _edX101_g: + +**edX101** + + An online course about how to create online courses. The intended audience + for `edX101`_ is faculty and university administrators. + +.. _edX Edge_g: + +**edX Edge** + + `edX Edge`_ is a less restricted site than edX.org. While only edX employees + and consortium members can create and post content on edX.org, any users with + course creator permissions for Edge can create courses with Studio on + studio.edge.edx.org, then view the courses on the learning management system + at edge.edx.org. + +.. _edX Studio: + +**edX Studio** + + The edX tool that you use to build your courses. For more information, see + `Getting Started with Studio`. + +.. _embargo: + +**embargo** + + An embargo is an official ban on trade or commercial activity with a + particular country. For example, due to U.S. federal regulations, edX cannot + offer certain courses (for example, particular advanced STEM courses) on the + edx.org website to learners in embargoed countries. Learners cannot access + restricted courses from an embargoed country. In some cases, depending on the + terms of the embargo, learners cannot access any edX courses at all. + +**enrollment mode** + + See :ref:`enrollment track`. + +.. _enrollment_track_g: + +**enrollment track** + + Also called **certificate type**, **course mode**, **course seat**, **course + track**, **course type**, **enrollment mode**, or **seat type**. + + The enrollment track specifies the following items about a course. + + * The type of certificate, if any, that learners receive if they pass the + course. + * Whether learners must verify their identity to earn a certificate, using + a webcam and a photo ID. + * Whether the course requires a fee. + + * **audit**: This is the default enrollment track when learners enroll in a + course. This track does not offer certificates, does not require identity + verification, and does not require a course fee. + + * **professional**: This enrollment track is only used for specific + professional education courses. The professional enrollment track offers + certificates, requires identity verification, and requires a fee. Fees for + the professional enrollment track are generally higher than fees for the + verified enrollment track. Courses that offer the professional track do not + offer a free enrollment track. + + .. note:: + If your course is part of a MicroMasters or professional certificate + program, your course uses the verified track. These courses do not use + the professional enrollment track. + + * **verified**: This enrollment track offers verified certificates to + learners who pass the course, verify their identities, and pay a required + course fee. A course that offers the verified enrollment track also + automatically offers a free non-certificate enrollment track. + + * **honor**: This enrollment track was offered in the past and offered an + honor code certificate to learners who pass the course. This track does not + require identity verification and does not require a fee. Note, however, + that as of December 2015, edx.org no longer offers honor code certificates. + For more information, see `News About edX Certificates`_. + + .. only:: Partners + + * **credit**: In this enrollment track, learners who pass the course and + comply with additional requirements, including identity verification, can + receive academic credit for the course. For more information, see + `partnercoursestaff:Academic Course Credit`. + + .. only:: Open_edX + + * **professional (no ID)**: Like the professional enrollment track, this + track offers certificates and requires a fee. However, this track does + not require identity verification. Courses that offer the professional + (no ID) track do not offer a free enrollment track. + + +.. _Exercises: + +**exercises** + + Practice or practical problems that are interspersed in edX course content + to keep learners engaged. Exercises are also an important measure of + teaching effectiveness and learner comprehension. For more information, see + `partnercoursestaff:Exercises and Tools Index`. + + +.. _Export: + +**export** + + A tool in edX Studio that you use to export your course or library for + backup purposes, or so that you can edit the course or library directly in + OLX format. See also :ref:`Import`. + + For more information, see `partnercoursestaff:Export a Course` or + `partnercoursestaff:Export a Library`. + +.. _F: + +*** +F +*** + +**forum** + + See :ref:`Discussion`. + +.. _fps: + +**fps** + + Frames per second. In video, the number of consecutive images that appear + every second. + + +.. _G: + +**** +G +**** + +.. _grade: + +**grade range** + + Thresholds that specify how numerical scores are associated with grades, and + the score that learners must obtain to pass a course. + + For more information, see `partnercoursestaff:Set the Grade Range`. + + +**grading rubric** + + See :ref:`Rubric`. + + +.. _H: + +**** +H +**** + +.. _H264: + +**H.264** + + A standard for high definition digital video. + +.. _Home Page: + +**Home page** + + See :ref:`Course Page`. + +.. _Text Component: + +**Text component** + + A type of component that you can use to add and format text for your course. + A Text component can contain text, lists, links, and images. For more + information, see `partnercoursestaff:Working with Text Components`. + + + +.. _I: + +**** +I +**** + + +.. _Image Mapped_g: + +**Image mapped input problem** + + A problem that presents an image and accepts clicks on the image as an + answer. For more information, see `partnercoursestaff:Image Mapped + Input`. + + +.. _Import: + +**Import** + + A tool in Studio that you use to load a course or library in OLX format + into your existing course or library. When you use the Import tool, Studio + replaces all of your existing course or library content with the content + from the imported course or library. See also :ref:`Export`. + + For more information, see `partnercoursestaff:Import a Course` or + `partnercoursestaff:Import a Library`. + +**instructor dashboard** + + A user who has the Admin or Staff role for a course can access the instructor + dashboard in the LMS by selecting **Instructor**. Course team members use the + tools, reports, and other features that are available on the pages of the + instructor dashboard to manage a running course. + + For more information, see `partnercoursestaff:Managing Live Course + Index`. + +.. _K: + +**** +K +**** + +**keyword** + + A variable in a bulk email message. When you send the message, a value that + is specific to the each recipient is substituted for the keyword. + +.. _L: + +**** +L +**** + +**label** + + See :ref:`Accessible Label`. + +.. _LaTeX_g: + +**LaTeX** + + A document markup language and document preparation system for the TeX + typesetting program. In edX Studio, you can `partnercoursestaff:import + LaTeX code`. + + +.. _Learning Management System: + +**learning management system (LMS)** + + The platform that learners use to view courses, and that course team members + use to manage learner enrollment, assign team member privileges, moderate + discussions, and access data while the course is running. + +**learning sequence** + + See :ref:`Unit Navigation Bar`. + +**left pane** + + See :ref:`Course Navigation Pane`. + +.. _Library_g: + +**library** + + A pool of components for use in randomized assignments that can be shared + across multiple courses from your organization. Course teams configure + randomized content blocks in course outlines to reference a specific library + of components, and randomly provide a specified number of problems from that + content library to each learner. + + For more information, see `partnercoursestaff:Content Libraries` and + `partnercoursestaff:Randomized Content Blocks`. + + +.. _Live Mode: + +**live mode** + + A view that allows the course team to review all published units as learners + see them, regardless of the release dates of the section and subsection that + contain the units. For more information, see `partnercoursestaff:View + Published Content`. + +**LON-CAPA** + + The Learning Online Network with Computer-Assisted Personalized Approach + e-learning platform. The structure of CAPA problem types in the edX platform + is based on the `LON-CAPA`_ assessment system, although they are not + compatible. + + See also :ref:`CAPA Problems`. + +.. _M: + +**** +M +**** + +.. _Math Expression_g: + +**math expression input problem** + + A problem that requires learners to enter a mathematical expression as text, + such as e=m*c^2. + + For more information, see `learners:Math Formatting` in the *EdX + Learner's Guide*. + + +.. _MathJax: + +**MathJax** + + A LaTeX-like language that you use to write equations. Studio uses MathJax + to render text input such as x^2 and sqrt(x^2-4) as "beautiful math." + + For more information, see `partnercoursestaff:MathJax in Studio`. + + +.. _Module_g: + +**module** + + An item of course content, created in an XBlock, that appears on the + **Course** page in the edX learning management system. Examples of + modules include videos, HTML-formatted text, and problems. + + Module is also used to refer to the structural components that organize + course content. Sections, subsections, and units are modules; in fact, the + course itself is a top-level module that contains all of the other course + content as children. + + +.. _Multi-select_g: + +**multi-select problem** + + A problem that prompts learners to select one or more options from a list of + possible answers. For more information, see + `partnercoursestaff:Multi-select`. + + +.. _N: + +**** +N +**** + +.. _NTSC: + +**NTSC** + + National Television System Committee. The NTSC standard is a color encoding + system for analog videos that is used mostly in North America. + +.. _Numerical Input_g: + +**numerical input problem** + + A problem that asks learners to enter numbers or specific and relatively + simple mathematical expressions. For more information, see + `partnercoursestaff:Numerical Input`. + + +.. _O: + +**** +O +**** + +**OLX** + + OLX (open learning XML) is the XML-based markup language that is used to + build courses on the Open edX platform. + + For more information, see `olx:What is Open Learning XML?`. + + +.. _Open Response Assessment_g: + +**open response assessment** + + A type of assignment that allows learners to answer with text, such as a + short essay and, optionally, an image or other file. Learners then evaluate + each others' work by comparing each response to a :ref:`rubric ` + created by the course team. + + These assignments can also include a self assessment, in which learners + compare their own responses to the rubric, or a staff assessment, in which + members of course staff evaluate learner responses using the same rubric. + + For more information, see `partnercoursestaff:Open Response Assessments + Two`. + +.. _P: + +**** +P +**** + +.. _Pages_g: + +**pages** + + Pages organize course materials into categories that learners select in the + learning management system. Pages provide access to the course content and to + tools and uploaded files that supplement the course. Links to each page + appear in the course material navigation bar. + + For more information, see `partnercoursestaff:Adding Pages to a + Course`. + +.. _PAL: + +**PAL** + + Phase alternating line. The PAL standard is a color encoding system for + analog videos. It is used in locations such as Brazil, Australia, south Asia, + most of Africa, and western Europe. + +**partner manager** + + Each EdX partner institution has an edX partner manager. The partner manager + is the primary contact for the institution's course teams. + + +**pre-roll video** + + A short video file that plays before the video component selected by the + learner. Pre-roll videos play automatically, on an infrequent schedule. + + For more information, see `partnercoursestaff:Adding a PreRoll Video`. + + +.. _Preview Mode: + +**preview mode** + + A view that allows you to see all the units of your course as learners see + them, regardless of the unit status and regardless of whether the release + dates have passed. + + For more information, see `partnercoursestaff:Preview Unpublished + Content`. + + +.. _Problem Component: + +**problem component** + + A component that allows you to add interactive, automatically graded + exercises to your course content. You can create many different types of + problems. + + For more information, see `partnercoursestaff:Working with Problem + Components` and `partnercoursestaff:Exercises and Tools Index`. + +.. _Proctored Exam_g: + +**proctored exam** + + At edX, proctored exams are timed, impartially and electronically monitored + exams designed to ensure the identity of the test taker and determine the + security and integrity of the test taking environment. Proctored exams are + often required in courses that offer verified certificates or academic + credit. For more information, see `partnercoursestaff:Managing + Proctored Exams`. + +.. _Program: + +**program** + + A program is a collection of related courses. Learners enroll in a program by + enrolling in any course that is part of a program, and earn a program + certificate by passing each of the courses in the program with a grade that + qualifies them for a verified certificate. + + Several types of program are available on edx.org, including MicroMasters, + Professional Certificate, and XSeries programs. + + +.. _Program Offer: + +**program offer** + + A program offer is a discount offered for a specific program. The discount + can be either a percentage amount or an absolute (dollar) amount. + + +.. _Progress Page: + +**Progress page** + + The page in the learning management system that shows learners their scores + on graded assignments in the course. For more information, see + `learners:SFD Check Progress` in the *EdX Learner's Guide*. + + +.. _Q: + +***** +Q +***** + +**question** + + A question is a type of post that you or a learner can add to a course + discussion topic to bring attention to an issue that the discussion + moderation team or learners can resolve. + + For more information, see `partnercoursestaff:Discussions`. + +.. _R: + +**** +R +**** + +**Research Data Exchange (RDX)** + + An edX program that allows participating partner institutions to request data + for completed edx.org courses to further approved educational research + projects. Only partner institutions that choose to participate in RDX + contribute data to the program, and only researchers at those institutions + can request data from the program. + + For more information, see `data:Research Data Exchange`. + +.. _Rubric_g: + +**rubric** + + A list of the items that a learner's response should cover in an open + response assessment. For more information, see the + `partnercoursestaff:PA Rubric` topic in `partnercoursestaff:Open + Response Assessments Two`. + + See also :ref:`Open Response Assessment`. + + +.. _S: + +**** +S +**** + +**seat type** + + See :ref:`enrollment track`. + +.. _Section_g: + +**section** + + The topmost category in your course outline. A section can represent a time + period or another organizing principle for course content. A section + contains one or more subsections. + + For more information, see `partnercoursestaff:Developing Course + Sections`. + + +**sequential** + + See :ref:`Subsection`. + + +.. _Short Course Description: + +**short description** + + The description of your course that appears on the edX `Course List + `_ page. + + For more information, see `Course Short Description Guidelines`. + + +.. _Simple Editor_g: + +**simple editor** + + The graphical user interface in a problem component. The simple editor is + available for some problem types. For more information, see + `partnercoursestaff:Problem Studio View`. + +**single sign-on (SSO)** + + SSO is an authentication service that allows a user to access multiple + related applications, such as Studio and the LMS, with the same username and + password. The term SSO is sometimes used to refer to third party + authentication, which is a different type of authentication system. For + information about third party authentication, see + :ref:`Third Party Authentication`. + + +.. _Single_select_g: + +**single select problem** + + A problem that asks learners to select one answer from a list of options. + For more information, see `partnercoursestaff:Single Select`. + + +.. _Special Exam_g: + +**special exam** + + A general term that applies to proctored and timed exams in edX courses. See + :ref:`Timed Exam` and :ref:`Proctored Exam
+ +The browser would execute the JavaScript code in the ```` tag. The user has injected code into the page that would +display a pop-up alert, which we would not want to allow. Because this attack +could contain arbitrary JavaScript that would be executed by the browser with +the same trust as any JavaScript that is sent from the application, it has the +potential to do something much more malicious than simply displaying a pop-up. +An example might be to steal and email the user's cookies. + +In Mako, you can introduce HTML-escaping for all expressions on a page using +the page directive with the ``h`` filter. Here is an example of an expression +that is properly HTML-escaped. + +.. code-block:: mako + + <%page expression_filter="h"/> + ... +
${course_name}
+ +The resulting safe page source is as follows. + +.. code-block:: mako + +
<script>alert('XSS!');</script>
+ +This time, the browser will not interpret the `` + +For this example, imagine that someone uses Studio to set the course name as +shown here. + +.. code-block:: mako + + ";alert('XSS attack!');" + +The resulting unsafe page source, sent to the browser with no escaping, would +look like this. + +.. code-block:: mako + + + +You can see how the attacker closed out the string and again tricked the +browser into executing the malicious JavaScript in the context of JavaScript. +There are several reasons why you do not want to use the default HTML-escaping +here. + +#. JavaScript-escaping will also escape all characters that are special + characters in HTML, such as ``<``. However, JavaScript-escaping will + escape ``<`` to ``\u003C``, rather than to ``<``. This will still keep + the browser from finding an HTML tag where it does not belong. + +#. The resulting string might not ultimately be used in an HTML context, so + HTML entities might not be the proper escaping. + +The way to properly JavaScript-escape code in Mako is shown in the following +example. + +.. code-block:: mako + + <%! from openedx.core.djangolib.js_utils import js_escaped_string %> + ... + + +The code above would produce the following safe page source. + +.. code-block:: mako + + + +.. _CSS Context: + +CSS Context and Escaping +======================== + +The browser treats any code inside a ``

`. + +.. _Split_Test: + +**split test** + + See :ref:`Content Experiment`. + + +.. _Subsection: + +**subsection** + + A division in the course outline that represents a topic in your course, + such as a lesson or another organizing principle. Subsections are defined + inside sections and contain units. + + For more information, see `partnercoursestaff:Developing Course + Subsections`. + + +.. _T: + +**** +T +**** + +.. _Text Input_g: + +**text input problem** + + A problem that asks learners to enter a line of text, which is then checked + against a specified expected answer. + + For more information, see `partnercoursestaff:Text Input`. + +.. _Timed Exam_g: + +**timed exam** + + Timed exams are sets of problems that a learner must complete in the amount + of time you specify. When a learner begins a timed exam, a countdown timer + displays, showing the amount of time allowed to complete the exam. + If needed, you can grant learners additional time to complete the exam. + For more information, see `partnercoursestaff:Timed Exams`. + +.. _TPA_g: + +**third party authentication** + + A system-wide configuration option that allows users who have a username and + password for one system, such as a campus or institutional system, to log in + to that system and automatically be given access to the LMS. These users do + not enter their system credentials in the LMS. + + For more information about how system administrators can integrate an + instance of Open edX with a campus or institutional authentication system, + see `installation:Enabling Third Party Authentication`. + +.. _Transcript Definition: + +**transcript** + + A text version of the content of a video. You can make video transcripts + available to learners. + + For more information, see `Obtain a Video Transcript`. + +.. _U: + +*** +U +*** + +**unit** + + A unit is a division in the course outline that represents a lesson. + Learners view all of the content in a unit on a single page. + + For more information, see `partnercoursestaff:Developing Course Units`. + +**unit navigation bar** + + The horizontal control that appears at the top of the **Course** page in the + LMS. The unit navigation bar contains an icon for each unit in the selected + subsection. When you move your pointer over one of these icons, the name of + the unit appears. If you have bookmarked a unit, the unit navigation bar + includes an identifying flag above that unit's icon. + + See also :ref:`Course Navigation Pane`. + +.. _V: + +**** +V +**** + +.. _VBR: + +**VBR** + + Variable bit rate. The bit rate is the number of bits per second that are + processed or transferred. A variable bit rate allows the bit rate to change + according to the complexity of the media segment. + +**vertical** + + See :ref:`Unit`. + +.. _Video Component: + +**video component** + + A component that you can use to add recorded videos to your course. + + For more information, see `partnercoursestaff:Working with Video + Components`. + + +.. _W: + +**** +W +**** + +.. _Whitelist: + +**whitelist** + + In edX courses, a whitelist is a list of learners who are being provided with + a particular privilege. For example, whitelisted learners can be specified as + being eligible to receive a certificate in a course, regardless of whether + they would otherwise have qualified based on their grade. + + In the grade report for a course, whitelisted learners have a value of "Yes" + in the **Certificate Eligible** column, regardless of the grades they + attained. For information about the grade report, see + `partnercoursestaff:Interpret the Grade Report`. + + +.. _Wiki: + +**wiki** + + The page in each edX course that allows both learners and members of the + course team to add, modify, or delete content. Learners can use the wiki to + share links, notes, and other helpful information with each other. For more + information, see `partnercoursestaff:Course_Wiki`. + + +.. _X: + +**** +XYZ +**** + +.. _XBlock: + +**XBlock** + + EdX's component architecture for writing course components: XBlocks are + the components that deliver course content to learners. + + Third parties can create components as web applications that can run within + the edX learning management system. For more information, see + `xblocktutorial:Open edX XBlock Tutorial`. + + +**XSeries** + + A set of related courses in a specific subject. Learners qualify for an + XSeries certificate when they pass all of the courses in the XSeries. For + more information, see `XSeries Programs`_. + + +.. include:: ./links.rst + diff --git a/source/developers/references/legacy_guide/images/ECommerce_Debug_Config.png b/source/developers/references/legacy_guide/images/ECommerce_Debug_Config.png new file mode 100644 index 00000000..2bfa9d75 Binary files /dev/null and b/source/developers/references/legacy_guide/images/ECommerce_Debug_Config.png differ diff --git a/source/developers/references/legacy_guide/images/ECommerce_SSH_Config.png b/source/developers/references/legacy_guide/images/ECommerce_SSH_Config.png new file mode 100644 index 00000000..0cbec50c Binary files /dev/null and b/source/developers/references/legacy_guide/images/ECommerce_SSH_Config.png differ diff --git a/source/developers/references/legacy_guide/images/JavaScriptInputExample.png b/source/developers/references/legacy_guide/images/JavaScriptInputExample.png new file mode 100644 index 00000000..1c9220de Binary files /dev/null and b/source/developers/references/legacy_guide/images/JavaScriptInputExample.png differ diff --git a/source/developers/references/legacy_guide/images/XBlock_URL_example_after.png b/source/developers/references/legacy_guide/images/XBlock_URL_example_after.png new file mode 100644 index 00000000..de0abbd9 Binary files /dev/null and b/source/developers/references/legacy_guide/images/XBlock_URL_example_after.png differ diff --git a/source/developers/references/legacy_guide/images/XBlock_URL_example_before.png b/source/developers/references/legacy_guide/images/XBlock_URL_example_before.png new file mode 100644 index 00000000..f0ac105a Binary files /dev/null and b/source/developers/references/legacy_guide/images/XBlock_URL_example_before.png differ diff --git a/source/developers/references/legacy_guide/images/edx-architecture.png b/source/developers/references/legacy_guide/images/edx-architecture.png new file mode 100644 index 00000000..50b4a0da Binary files /dev/null and b/source/developers/references/legacy_guide/images/edx-architecture.png differ diff --git a/source/developers/references/legacy_guide/images/edx-platform-transifex-project.png b/source/developers/references/legacy_guide/images/edx-platform-transifex-project.png new file mode 100644 index 00000000..ef720bab Binary files /dev/null and b/source/developers/references/legacy_guide/images/edx-platform-transifex-project.png differ diff --git a/source/developers/references/legacy_guide/images/join-language-team.png b/source/developers/references/legacy_guide/images/join-language-team.png new file mode 100644 index 00000000..346b0f32 Binary files /dev/null and b/source/developers/references/legacy_guide/images/join-language-team.png differ diff --git a/source/developers/references/legacy_guide/images/preventing-xss.png b/source/developers/references/legacy_guide/images/preventing-xss.png new file mode 100644 index 00000000..bf822288 Binary files /dev/null and b/source/developers/references/legacy_guide/images/preventing-xss.png differ diff --git a/source/developers/references/legacy_guide/images/project-resources.png b/source/developers/references/legacy_guide/images/project-resources.png new file mode 100644 index 00000000..9c739aaf Binary files /dev/null and b/source/developers/references/legacy_guide/images/project-resources.png differ diff --git a/source/developers/references/legacy_guide/images/view-team-members.png b/source/developers/references/legacy_guide/images/view-team-members.png new file mode 100644 index 00000000..c1896655 Binary files /dev/null and b/source/developers/references/legacy_guide/images/view-team-members.png differ diff --git a/source/developers/references/legacy_guide/index.rst b/source/developers/references/legacy_guide/index.rst new file mode 100644 index 00000000..2d839e26 --- /dev/null +++ b/source/developers/references/legacy_guide/index.rst @@ -0,0 +1,21 @@ +.. _edX Developer's Guide: + +############################ +Open edX Developer's Guide +############################ + +.. toctree:: + :numbered: + :maxdepth: 2 + + front_matter/index + architecture + process/index + extending_platform/index + testing/index + analytics.rst + conventions/index + internationalization/index + preventing_xss/index + style_guides/index + glossary diff --git a/source/developers/references/legacy_guide/internationalization/i18n.rst b/source/developers/references/legacy_guide/internationalization/i18n.rst new file mode 100644 index 00000000..ad9ca804 --- /dev/null +++ b/source/developers/references/legacy_guide/internationalization/i18n.rst @@ -0,0 +1,817 @@ +.. _i18n: + +###################################### +Internationalization Coding Guidelines +###################################### + +Preparing code to be presented in many languages can be complex and difficult. +This section presents best practices for marking English strings in source so +that they can be extracted, translated, and displayed to the user in the +language of their choice. + +.. contents:: + :depth: 1 + :local: + + +********************************** +General Internationalization Rules +********************************** + +For source files to be successfully localized, you need to prepare them so that +any human-readable strings can be extracted by a pre-processing step, and then +have localized strings used at runtime. This preparation requires attention to +detail, and unfortunately limits what you can do with strings in the code. + +Follow these general rules for internationalizing your code. + +#. Always mark complete sentences for translation. If you combine fragments at + runtime, there is no way for the translator to construct a proper sentence + in their language. + +#. Do not combine strings together at runtime. + +#. Limit the amount of text in strings that is not presented to the user. HTML + markup is better applied after translation. If you include HTML in strings + there is a chance that translators will translate your tags or attributes. + +#. Use placeholders with descriptive names: ``"Welcome {student_name}"`` is + much better than ``"Welcome {0}"``. + +For details, see :ref:`i18n Style Guidelines`. + + +******************** +Editing Source Files +******************** + +When you edit source files (including Python, JavaScript, or HTML template +files), you should be aware of the following conventions. + +#. Know what has to be at the top of the file (if anything) to prepare it for + i18n. + +#. Know how strings are marked for internationalization. This markup typically + takes the form of a function call with the string as an argument. + +#. Know how translator comments are indicated. Such comments in the file will + travel with the strings to the translators, giving them context to produce + the best translation. Translator comments have a ``Translators:`` marker + and must appear on the line preceding the text they describe. In Python, + multi-line comments are supported for translator comments that need to be + wrapped. + +The code samples below show how to do each of these things for a variety of +programming languages. + +.. note:: Take into account not just the programming language involved, but the + type of file that you are preparing for internationalization. For example, + JavaScript embedded in an HTML Mako template is treated differently than + JavaScript in a pure .js file. There are many different escaping methods that + you can use. For more details, see :ref:`Preventing XSS`. + +.. contents:: + :depth: 1 + :local: + + +.. _i18n Python Source Code: + +================== +Python Source Code +================== + +.. highlight:: python + +In most Python source code, indicate strings for translation and add +translator comments as shown. For more details, refer to the Django +documentation. :: + + from django.utils.translation import ugettext as _ + + # Translators: This will help the translator + message = _("Welcome!") + + # Translators: This is a very long comment that needs to wrap + # over multiple lines because it would be too long otherwise. + message = _("Hello world") + +Some edX code cannot use Django imports. To maintain portability, XBlocks, +XModules, Inputtypes and Responsetypes forbid importing Django. Each of these +has its own way of accessing translations, as shown in the following examples. :: + + ### for XBlock & XModule: + _ = self.runtime.service(self, "i18n").ugettext + # Translators: a greeting to newly-registered students. + message = _("Welcome!") + + # for InputType and ResponseType: + _ = self.capa_system.i18n.ugettext + # Translators: a greeting to newly-registered students. + message = _("Welcome!") + +Translator comments will work in these places too, so wherever possible, +provide clarifying comments for translators. However, be aware of a quirk in +the Python parser. When you write translator comments, make sure the message +string is on the very next line after the comment. + +The following example is not correct. :: + + # Translators: this comment won't be properly harvested! + message = _( + "Long message " + "on a few lines." + ) + +This example is correct. :: + + message = _( + # Translators: this comment will be properly harvested! + "Long message " + "on a few lines." + ) + + +.. _i18n Django Template Files: + +===================== +Django Template Files +===================== + +.. highlight:: django + +In Django template files (`templates/*.html`), indicate strings for +translation and add translator comments as shown. :: + + {% load i18n %} + + {# Translators: this will help the translator. #} + {% trans "Welcome!" %} + + +.. _i18n Mako Template Files: + +=================== +Mako Template Files +=================== + +.. highlight:: mako + +In Mako template files (`templates/*.html`), you can use all of the tools +available to Python programmers. Just make sure to import the relevant +functions first. Here is a Mako template example. :: + + <%page expression_filter="h"/> + <%! from django.utils.translation import ugettext as _ %> + ... + ## Translators: message to the translator. This comment may + ## wrap on to multiple lines if needed, as long as they are + ## lines directly above the marked up string. + ${_("Welcome!")} + +Make sure that all Mako comments, including translators comments, begin +with *two* pound signs (#). + +All translated strings should be text, not HTML. This means that for display +in an HTML page, the strings must be HTML-escaped. In the example above, HTML- +escaping is handled through the ``<%page>`` directive with the ``h`` filter. +For more information, see :ref:`Preventing XSS`. + +To mix plain text and HTML using ``format()``, you must use the ``HTML()`` and +``Text()`` functions. Use the ``HTML()`` function when you have a replacement +string that contains HTML tags. For the ``HTML()`` function to work, you must +use the ``Text()`` function to wrap the plain text translated string. Both the +``HTML()`` and ``Text()`` functions must be closed before any calls to +``format()``. + +.. code-block:: mako + + <%page expression_filter="h"/> + <%! + from django.utils.translation import ugettext as _ + + from openedx.core.djangolib.markup import HTML, Text + %> + ... + ${Text(_("Click over to {link_start}the home page{link_end}.")).format( + link_start=HTML(''), + link_end=HTML(''), + )} + + +You can nest the formatting further. The rule is, any string which is HTML +should be wrapped in the ``HTML()`` function, and any string which is not +wrapped in ``HTML()`` should be escaped as needed to be displayed as regular +text. Again, you must close the ``HTML()`` and ``Text()`` calls before making +any call to ``format()``. + +.. code-block:: mako + + <%page expression_filter="h"/> + <%! + from django.utils.translation import ugettext as _ + + from openedx.core.djangolib.markup import HTML, Text + %> + ... + ${Text(_("Click over to {link_start}the home page{link_end}.")).format( + link_start=HTML('').format(home_page_link), + link_end=HTML(''), + )} + +For more information on proper escaping, see :ref:`Preventing XSS`. + + +.. _i18n JavaScript Files: + +================ +JavaScript Files +================ + +.. highlight:: html + +To internationalize JavaScript, the HTML template (``base.html``) must first +load a special JavaScript library, and Django must be configured to serve it. +:: + + + +.. highlight:: javascript + +Then, in JavaScript files (``*.js``):: + + // Translators: this will help the translator. + var message = gettext('Welcome!'); + +For interpolation with translated strings, you must use +``StringUtils.interpolate`` or ``HtmlUtils.interpolateHtml``, as shown in the +following example. :: + + var message = StringUtils.interpolate( + gettext('You are enrolling in {courseName}'), + { + courseName: 'Rock & Roll 101' + } + ) + +For more details on how to use ``StringUtils`` and ``HtmlUtils``, see :ref:`Safe +JavaScript Files `. + +Note that JavaScript embedded in HTML in a Mako template file is handled +differently. There, you must use the Mako syntax even within the JavaScript. + + +.. _i18n CoffeeScript Files: + +================== +CoffeeScript Files +================== + +.. highlight:: coffeescript + +CoffeeScript files are compiled to JavaScript files, so you indicate strings +for translation and add translator comments mostly as you would in +:ref:`Javascript `. :: + + `// Translators: this will help the translator.` + message = gettext('Hey there!') + + # Interpolation must use JavaScript, not CoffeeScript interpolation + var message = StringUtils.interpolate( + gettext('You are enrolling in {courseName}'), + { + courseName: 'Rock & Roll 101' + } + ) + +However, because strings are extracted from the compiled .js files, some native +CoffeeScript features break the extraction from the .js files. Be aware of the +following rules. + +#. Do not use CoffeeScript string interpolation. Doing so results in string + concatenation in the .js file, preventing string extraction. Instead, use + ``StringUtils.interpolate`` and ``HtmlUtils.interpolateHtml`` as documented + in :ref:`Safe JavaScript Files `. + +#. Do not use CoffeeScript comments for translator comments. They are not + passed through to the JavaScript files. + +:: + + # DO NOT do this: + # Translators: this won't get to the translators! + message = gettext("This won't work") + + # YES do this: + `// Translators: this will get to the translators.` + message = gettext("This works") + + ### + Translators: This will work, but takes three lines :( + ### + message = gettext("Hey there") + +.. highlight:: python + + +.. _i18n Underscore Template Files: + +========================= +Underscore Template Files +========================= + +Underscore template files are used in conjunction with JavaScript, so the same +techniques that are used for localization in :ref:`Javascript ` are used for Underscore template files. + +Make sure that the i18n JavaScript library has already been loaded, and then +use the i18n function ``gettext`` and the ``StringUtils`` function +``StringUtils.interpolate`` in your template, as shown in this example. + +.. code-block:: javascript + + <%- + StringUtils.interpolate( + gettext('You are enrolling in {courseName}'), + { + courseName: 'Rock & Roll 101' + } + ) + %> + +.. important:: Due to a bug in the underlying underscore extraction library, + when ``StringUtils.interpolate`` and ``gettext`` are on the same line, the + library will not work properly. In such cases, the library will extract the + word ``gettext`` rather than the actual string that needs to be extracted. + Make sure to separate ``StringUtils.interpolate`` and ``gettext`` into two + different lines, as shown in the example above. + +.. note:: You must use ``<%-`` for all translated strings that do not include + HTML tags, as this will HTML-escape the strings before including them in the + page. + +If you have a translated string that includes a mix of HTML and plain text, +you must use ``HtmlUtils.interpolateHtml`` along with ``<%=``. Using ``<%=`` +is only acceptable when you use an ``HtmlUtils`` function. + +.. code-block:: javascript + + <%= + HtmlUtils.interpolateHtml( + gettext('You are enrolling in {spanStart}{courseName}{spanEnd}'), + { + courseName: 'Rock & Roll 101', + spanStart: HtmlUtils.HTML(''), + spanEnd: HtmlUtils.HTML('') + } + ) + %> + +You can access ``HtmlUtils`` and ``StringUtils`` from inside a template that is +processed using ``HtmlUtils.template()``. For more details regarding the use of +``StringUtils`` and ``HtmlUtils``, see :ref:`Safe JavaScript Files `. + +Currently, translator comments are not supported in underscore template files, +because the underlying library does not parse them out. You should add +translator comments using standard comment syntax, so that when work is done +to support translator comments, the comments are already defined in your code. +Additionally, translator comments in the code will enable us to answer +questions from translators. + + +.. _i18n Other Types of Content: + +====================== +Other Types of Content +====================== + +We have not yet established guidelines for internationalizing the following +types of content. + +* Course content (such as subtitles for videos) +* Documentation (written for Sphinx as .rst files) + + +.. _i18n Coverage Testing: + +**************** +Coverage Testing +**************** + +These instructions assume that you are a developer working on +internationalizing new or existing user-facing features. To test that your +code is properly internationalized, you generate a set of 'dummy' +translations, then view those translations on your app's page to make sure +everything (scraping and serving) is working properly. + +First, use the coverage tool to generate dummy files. + +.. code-block:: sh + + $ paver i18n_dummy + +This step creates new dummy translations in the Esperanto directory +(edx-platform/conf/local/eo/LC_MESSAGES) and the RTL directory +(edx-platform/conf/local/rtl/LC_MESSAGES). DO NOT CHECK THESE FILES IN. You +should discard these files once you have finished testing. + +Next, restart the LMS and Studio to load in the new translation files. + +.. code-block:: sh + + $ paver devstack lms + $ paver devstack studio + +Append ``/update_lang/`` to the root LMS or Studio URL and use the form to set +the preview language. The language code ``eo`` can be used to specify the test +language. + +Instead of plain English strings, you should see specially-accented English +strings that look like this example. + + Thé Fütüré øf Ønlïné Édüçätïøn Ⱡσяєм ι# + Før änýøné, änýwhéré, änýtïmé Ⱡσяєм # + +This dummy text is distinguished by extra accent characters. If you see plain +English without these accents, it most likely means that the strings have not +yet been marked for translation, or you have broken a rule. To fix this issue, +follow these steps. + +#. Find the strings in the source tree (either in Python, JavaScript, or HTML + template code). + +#. Refer to the coding guidelines above to make sure the strings have been + properly externalized. + +#. Rerun the scripts and confirm that the strings are now properly converted + into dummy text. + +This dummy text is also distinguished by "Lorem ipsum" text at the end of each +string, and is always terminated with "#". The original English string is +padded with about 30% more characters, to simulate languages (such as German) +which tend to have longer strings than English. If you see problems with your +page layout, such as columns that do not fit, or text that is truncated (the +``#`` character should always be displayed on every string), then you will +probably need to fix the page layouts accordingly to accommodate the longer +strings. + +Finally, append ``/update_lang/`` to the root LMS or Studio URL and set the +language code to ``rtl`` to view your feature in the dummy right-to-left +(RTL) language. Test to make sure that the user interface is properly +"flipped" to right-to-left mode. Note that certain page elements might not +look correct because they are controlled by the browser. For more effective testing, +switch your browser's language to Arabic or another RTL language (Hebrew, +Persian, or Urdu) as well. See our `RTL UI Guidelines`_ for information +about fixing any issues that you find. + +When you have finished reviewing, append ``/update_lang/`` to the LMS or +Studio URL and reset your session to your base language. + +==================== +Set Preview Language +==================== + +Before you set the preview language, sign in to either LMS or Studio. Then +append ``/update_lang/`` to the root LMS or Studio URL. A form appears for you +to set or clear the preview language. Set the Language code (for example use +``eo`` for the test language Esperanto), and then select **Submit** to set the +preview language. Use the **Reset** button to reset the preview language to +your default setting. Refresh your browser page to display the page in the +selected language. The language persists for the duration of your session. + +.. _RTL UI Guidelines: https://github.com/openedx/edx-platform/wiki/RTL-UI-Best-Practices + + +.. _i18n Style Guidelines: + +**************** +Style Guidelines +**************** + +=========================================== +Do Not Append Strings or Interpolate Values +=========================================== + +It can be difficult for translators to provide reasonable translations of +small sentence fragments. If your code appends sentence fragments, even if it +seems fine in English, the same concatenation is very unlikely to work +properly for other languages. + +Bad:: + + message = _("Welcome to the ") + settings.PLATFORM_NAME + _(" dashboard.") + +In this scenario, the translator has to figure out how to translate these two +separate strings. It is very difficult to translate a fragment such as +"Welcome to the." In some languages, the fragments will be in a different +order. For example, in Spanish this phrase would be ordered as "Welcome to the +dashboard of edX". + +It is much easier for a translator to figure out how to translate the entire +sentence, using the pattern "Welcome to the {platform_name} dashboard." + +Good:: + + message = _("Welcome to the {platform_name} dashboard.").format(platform_name=settings.PLATFORM_NAME) + + +Note that you cannot concatenate (+) within the ``gettext`` call at all. The +following example does not work. + +Bad:: + + message = _( + "Welcome to {platform_name}, the online learning platform " + + "that hosts courses from world-class universities around the world!" + ).format(platform_name=settings.PLATFORM_NAME) + +In Python, because _() is a function, the following example works. + +Good (Python only!):: + + message = _( + "Welcome to {platform_name}, the online learning platform " + "that hosts courses from world-class universities around the world!" + ).format(platform_name=settings.PLATFORM_NAME) + +However, in JavaScript and other languages, the ``gettext`` call cannot be +broken up over multiple lines. You will have to live with long lines on +``gettext`` calls, and we make a style exception for this. + +Bad:: + + message = gettext('Here is a really really long message that is' + + 'incorrectly broken over two lines.') + +Good (JavaScript):: + + message = gettext('Here is a really really long message that is correctly left on a single line.') + +====================== +Use Named Placeholders +====================== + +Python string formatting provides both positional and named placeholders. Use +named placeholders, never use positional placeholders. Positional placeholders +cannot be translated into other languages, which might need to re-order them +to make syntactically correct sentences. Even with a single placeholder, a +named placeholder provides more context to the translator. + +Bad:: + + message = _('Today is %s %d.') % (m, d) + +OK:: + + message = _('Today is %(month)s %(day)s.') % {'month': m, 'day': d} + +Best:: + + message = _('Today is {month} {day}.').format(month=m, day=d) + +Notice that in English, the month comes first, but in Spanish the day comes +first. This is reflected in the .po file in the following way. :: + + # fragment from edx-platform/conf/locale/es/LC_MESSAGES/django.po + msgid "Today is {month} {day}." + msgstr "Hoy es {day} de {month}." + +The resulting output is correct in each language. :: + + English output: "Today is November 26." + Spanish output: "Hoy es 26 de Noviembre." + + +============================== +Only Translate Literal Strings +============================== + +As programmers, we are used to using functions in flexible ways. But +translation functions such as ``_()`` and ``gettext()`` cannot be used in the +same ways as other functions. At runtime, they are real functions like any +other, but they also serve as markers for the string extraction process. + +For string extraction to work properly, the translation functions must be +called only with literal strings. If you use them with a computed value, the +string extracter will not have a string to extract. + +The difference between the right way and the wrong way can be very subtle, as +shown in these examples. + +:: + + # BAD: This tries to translate the result of .format() + _("Welcome, {name}".format(name=student_name)) + + # GOOD: Translate the literal string, then use it with .format() + _("Welcome, {name}").format(name=student_name)) + +:: + + # BAD: The dedent always makes the same string, but the extractor can't find it. + _(dedent(""" + .. very long message .. + """)) + + # GOOD: Dedent the translated string. + dedent(_(""" + .. very long message .. + """)) + +:: + + # BAD: The string is separated from _(), the extractor won't find it. + if hello: + msg = "Welcome!" + else: + msg = "Goodbye." + message = _(msg) + + # GOOD: Each string is wrapped in _() + if hello: + message = _("Welcome!") + else: + message = _("Goodbye.") + + +========================== +Be Aware of Nested Context +========================== + +When you provide strings in templated files for translation, you have to be +careful of nested context. For example, consider this JavaScript fragment in a +Mako template. :: + + + +When the string is rendered in French, it will produce the following invalid +JavaScript. + +.. code-block:: none + + + +Avoid this issue by following the best practices detailed in :ref:`Preventing +XSS`. Here is the same example with proper escaping. + +.. code-block:: mako + + <%! + from django.utils.translation import ugettext as _ + + from openedx.core.djangolib.js_utils import js_escaped_string + %> + ... + + +The code with proper escaping produces the following JavaScript-escaped code. + +.. code-block:: html + + + + +================== +Singular vs Plural +================== + +It can be tempting to improve a message by selecting singular or plural based +on a count, as shown in the following example. :: + + if count == 1: + msg = _("There is 1 file.") + else: + msg = _("There are {file_count} files.").format(file_count=count) + +The example above is not the correct way to choose a string, because other +languages have different rules for when to use singular and when plural, and +there might be more than two choices. + +One option is not to use different text for different counts. :: + + msg = _("Number of files: {file_count}").format(file_count=count) + +If you want to choose based on number, you need to use another ``gettext`` variant +to do so. :: + + from django.utils.translation import ungettext + msg = ungettext("There is {file_count} file", "There are {file_count} files", count) + msg = msg.format(file_count=count) + +The example above will properly use count to find a correct string in the +translation file; you can then use that string to format in the count. + + +===================== +Translating Too Early +===================== + +When the ``_()`` function is called, it will fetch a translated string using +the current user's language to decide which string to fetch. + +If you invoke the ``_()`` function before we know the user, then the wrong +language might be used. :: + + from django.utils.translation import ugettext as _ + + HELLO = _("Hello") + GOODBYE = _("Goodbye") + + def get_greeting(hello): + if hello: + return HELLO + else: + return GOODBYE + +Here the HELLO and GOODBYE constants are assigned when the module is first +imported, at server startup. There is no current user at that time, so +``ugettext`` will use the server's default language. When we eventually use +those constants to show a message to the user, they are not looked up again, +and the user will get the wrong language. + +There are a few ways to deal with this situation. The first is to avoid +calling ``_()`` until we have the user. :: + + def get_greeting(hello): + if hello: + return _("Hello") + else: + return _("Goodbye") + +Another way is to use Django's ``ugettext_lazy`` function. Instead of returning +a string, it returns a lazy object that will wait to do the lookup until it is +actually used as a string. :: + + from django.utils.translation import ugettext_lazy as _ + +Using this method can be tricky, because the lazy object does not act like a +string in all cases. + +The last way to solve the problem is to mark the string so that it will be +extracted properly, but not actually do the lookup when the constant is +defined. :: + + from django.utils.translation import ugettext + + _ = lambda text: text + + HELLO = _("Hello") + GOODBYE = _("Goodbye") + + def get_greeting(hello): + if hello: + return ugettext(HELLO) + else: + return ugettext(GOODBYE) + +Here we define ``_()`` as a pass-through function, so the string will be found +during extraction, but will not be translated too early. At runtime, we then +use the real translation function to get the localized string. + + +================== +Multi-line Strings +================== + +Translator notes must directly precede the string literals to which they refer. +For example, the translator note here will not be passed along to translators. +:: + + # Translators: you will not be able to see this note because + # I do not directly prepend the line with the translated string literal. + # See the line directly below this one does not contain part of the string? + long_translated_string = _( + "I am a long string, with many, many words. So many words that it is " + "advisable that I be split over this line." + ) + +In such a case, make sure you format your code so that the string begins on +a line directly below the translator note. :: + + # Translators: you will be able to see this note. + # See how the line directly below this one contains the start of the string? + long_translated_string = _("I am a long string, with many, many words. " + "So many words that it is advisable that I " + "be split over this line.") + +.. _i18n Additional Resources: + +******************** +Additional Resources +******************** + +The following links provide other resources related to internationalization. + +* `Django Internationalization `_ (overview) +* `Django: Internationalizing Python code `_ +* `Django Translation guidelines `_ +* `Django Format localization `_ diff --git a/source/developers/references/legacy_guide/internationalization/index.rst b/source/developers/references/legacy_guide/internationalization/index.rst new file mode 100644 index 00000000..66f9d57e --- /dev/null +++ b/source/developers/references/legacy_guide/internationalization/index.rst @@ -0,0 +1,9 @@ +###################################### +Writing Code for Internationalization +###################################### + +.. toctree:: + :maxdepth: 2 + + i18n.rst + diff --git a/source/developers/references/legacy_guide/links.rst b/source/developers/references/legacy_guide/links.rst new file mode 100644 index 00000000..af644edb --- /dev/null +++ b/source/developers/references/legacy_guide/links.rst @@ -0,0 +1,629 @@ +.. Include this file in any file that includes a non-doc link. + +.. EdX Links + +.. _edX Support: https://courses.edx.org/support/contact_us + +.. _edX Help Center for Learners: https://support.edx.org/hc/en-us/ + +.. _Math Formatting in Course Discussions: https://courses.edx.org/courses/course-v1:edX+DemoX.1+2T2017/wiki/edx/adding-math-expressions-course-discussion-post/ + +.. _change log for the Backbone.js library: https://github.com/jashkenas/backbone/blob/master/index.html#L4299 + +.. _Query string syntax: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax + +.. _Coming Soon Programs Page: https://open.edx.org/announcements/coming-soon-xseries-programs-page + +.. _Using edX Insights: http://edx.readthedocs.io/projects/edx-insights/en/latest/ + +.. _Review Answers to Graded Problems: http://edx.readthedocs.io/projects/edx-insights/en/latest/performance/Performance_Answers.html#review-answers-to-graded-problems + +.. _Review Answers to Ungraded Problems: http://edx.readthedocs.io/projects/edx-insights/en/latest/performance/Performance_Ungraded.html#review-answers-to-ungraded-problems + +.. _Open edX Analytics wiki: https://openedx.atlassian.net/wiki/spaces/COMM/pages/979927117/Open+edX+Analytics + +.. _openedx-analytics: http://groups.google.com/forum/#!forum/openedx-analytics + +.. _Entity Relationship Diagram for ORA Data: https://openedx.atlassian.net/wiki/display/AN/Entity+Relationship+Diagram+for+ORA+Data + +.. _edX Enrollment API: http://edx.readthedocs.io/projects/edx-platform-api/en/latest/enrollment/index.html + +.. _Course Navigation Changes: https://open.edx.org/announcements/update-course-navigation-changes + +.. _course-data: http://groups.google.com/a/edx.org/forum/#!forum/course-data + +.. _edx.org: http://edx.org + +.. _Edge: http://edge.edx.org + +.. _Edge registration: http://edge.edx.org/register + +.. _XML file: https://edge.edx.org/auth/saml/metadata.xml + +.. _test metadata file: https://courses.stage.edx.org/auth/saml/metadata.xml + +.. _edX Demo course: https://www.edx.org/course/demox-edx-demox-1-0 + +.. _information about open response assessments: https://courses.edx.org/courses/edX/DemoX.1/2014/courseware/70a1e3505d83411bb72393048ac4afd8/1e5cd9f233a2453f83731ccbd863b731/ + +.. _example peer assessment: https://courses.edx.org/courses/edX/DemoX.1/2014/courseware/70a1e3505d83411bb72393048ac4afd8/1e5cd9f233a2453f83731ccbd863b731/2 + +.. _Videos on edX: https://courses.edx.org/courses/edX/DemoX.1/2014/courseware/0af8db2309474971bfa70cda98668a30/ec3364075f2845baa625bfecd5970410/2 + +.. _AA Introduction to Music Theory: https://studio.edge.edx.org/course/sylviaX/TEST10/2014_T3 + +.. _La Tierra Centroamericana: https://studio.edge.edx.org/course/edX/GEO101/2014_T1> + +.. _edX Trademark Policy: https://www.edx.org/trademarks + +.. _Edx Proxy Instructions: https://openedx.atlassian.net/wiki/spaces/OpenOPS/pages/60228028/EdX+Proxy+Instructions + +.. _edX Edge: http://edge.edx.org + +.. _Studio: https://studio.edge.edx.org + +.. _edx.org registration: https://courses.edx.org/register + +.. _Research & Pedagogy: https://www.edx.org/about/research-pedagogy + +.. _docs@edx.org: docs@edx.org + +.. _Overview of Creating an edX Course: https://www.edx.org/course/overview-creating-edx-course-edx-edx101#.VHKBz76d9BV + +.. _Creating Video for the edX Platform: https://www.edx.org/course/videox-creating-video-for-the-edx-platform + +.. _Open edX Portal: http://open.edx.org/ + +.. _Partner Portal: http://partners.edx.org/ + +.. _Announcements: https://open.edx.org/announcements + +.. _edX Partner Support: https://partners.edx.org/edx_zendesk + +.. _edX pattern library: http://ux.edx.org/design_elements/colors/ + +.. _Open edX Named Releases page: https://edx.readthedocs.io/projects/edx-developer-docs/en/latest/named_releases.html + +.. _Open edX Installation: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/installation/ + +.. _Open edX Native Installation: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/installation/native_installation.html + +.. GitHub Links + +.. _GitHub: http://github.com + +.. _Contribute to edX Documentation: https://github.com/openedx/edx-documentation#contribute-to-edx-documentation + +.. _edx-documentation/shared: https://github.com/openedx/edx-documentation/blob/master/shared/conf.py + +.. _edx-analytics-configuration: https://github.com/openedx/edx-analytics-configuration + +.. _edx-documentation: https://github.com/openedx/edx-documentation + +.. _edx-tools wiki: https://github.com/openedx/edx-tools/wiki + +.. _custom_form_app: https://github.com/open-craft/custom-form-app + +.. _EdX Search: https://github.com/openedx/edx-search/ + +.. _GitHub Help: https://help.github.com/articles/set-up-git + +.. _edx-documentation: https://github.com/openedx/edx-documentation + +.. _password_policy_validators: https://github.com/openedx/edx-platform/blob/master/common/djangoapps/util/password_policy_validators.py + +.. _PyEnv: https://github.com/yyuu/pyenv + +.. _example CSS file for drag and drop problems: https://github.com/openedx/xblock-drag-and-drop-v2/blob/master/drag_and_drop_v2/public/themes/apros.css + +.. _VirtualEnv: http://www.virtualenv.org/en/latest/ + +.. _Virtual Environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/ + +.. _VirtualEnv Installation: https://virtualenv.pypa.io/en/latest/installation.html + +.. _VirtualEnvWrapper: http://virtualenvwrapper.readthedocs.io/en/latest + +.. _XBlock SDK: https://github.com/openedx/xblock-sdk + +.. _thumbs.py: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/thumbs/thumbs.py + +.. _thumbs.js: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/thumbs/static/js/src/thumbs.js + +.. _Thumbs XBlock: https://github.com/openedx/xblock-sdk/tree/master/sample_xblocks/thumbs + +.. _1.js: https://github.com/openedx/xblock-sdk/blob/master/workbench/static/workbench/js/runtime/1.js + +.. _Problem XBlock: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/problem.py + +.. _Content XBlocks: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/content.py + +.. _Slider XBlock: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/slider.py + +.. _Structure XBlocks: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/structure.py + +.. _View Counter XBlock: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/view_counter.py + +.. _thumbs.html: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/thumbs/static/html/thumbs.html + +.. _thumbs.css: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/thumbs/static/css/thumbs.css + +.. _requirements/edx/github.txt: https://github.com/openedx/edx-platform/blob/master/requirements/edx/github.txt + +.. _submission_mixin.py: https://github.com/openedx/edx-ora2/blob/a4ce7bb00190d7baff60fc90fb613229565ca7ef/openassessment/xblock/submission_mixin.py + +.. _edx-platform: https://github.com/openedx/edx-platform + +.. _configuration: https://github.com/openedx/configuration + +.. _The migrate.sh script: https://github.com/openedx/configuration/blob/named-release/dogwood.rc/util/vagrant/migrate.sh + +.. _The upgrade.sh script: https://github.com/openedx/configuration/blob/master/util/vagrant/upgrade.sh + +.. _Developing on Devstack: https://openedx.atlassian.net/wiki/display/OpenOPS/Running+Devstack + +.. _Getting Started on Analytics: https://github.com/openedx/devstack/blob/master/docs/analytics.rst + +.. _forum migration described on the Open edX wiki: https://openedx.atlassian.net/wiki/display/TNL/Migrating+the+Discussion+Forums+to+Support+Teams+Discussion+Filtering + +.. _Google Drive XBlock: https://github.com/openedx/xblock-google-drive + +.. _init file: https://github.com/openedx/edx-ora2/blob/a4ce7bb00190d7baff60fc90fb613229565ca7ef/openassessment/fileupload/backends/__init__.py + +.. _base.py: https://github.com/openedx/edx-ora2/blob/a4ce7bb00190d7baff60fc90fb613229565ca7ef/openassessment/fileupload/backends/base.py + +.. _S3.py: https://github.com/openedx/edx-ora2/blob/a4ce7bb00190d7baff60fc90fb613229565ca7ef/openassessment/fileupload/backends/s3.py + +.. _edX Analytics Installation: https://openedx.atlassian.net/wiki/display/OpenOPS/edX+Analytics+Installation + +.. _ux.edx.org: http://ux.edx.org/ + +.. _ui-toolkit.edx.org: http://ui-toolkit.edx.org/ + +.. _edx-ui-toolkit GitHub repository: https://github.com/edx/edx-ui-toolkit + +.. _Re install Open edX in Ubuntu 12.04: https://github.com/openedx/configuration/wiki/Re-install-Open-edX-in-Ubuntu-12.04 + +.. EDX VMs + +.. _iOS: http://github.com/openedx/edx-app-ios +.. _Android: http://github.com/openedx/edx-app-android + +.. _edX Managing the Full Stack: https://github.com/openedx/configuration/wiki/edX-Managing-the-Full-Stack + +.. _OEXPushNotificationManager.m: https://github.com/openedx/edx-app-ios/blob/master/Source/OEXPushNotificationManager.m + +.. _OEXParsePushProvider.m: https://github.com/openedx/edx-app-ios/blob/master/Source/OEXParsePushProvider.m + +.. _OEXPushProvider.h: https://github.com/openedx/edx-app-ios/blob/master/Source/OEXPushProvider.h + +.. _AndroidManifest.xml: https://github.com/openedx/edx-app-android/blob/master/VideoLocker/AndroidManifest.xml#L270 + +.. _EdxParsePushBroadcastReceiver.java: https://github.com/openedx/edx-app-android/blob/master/VideoLocker/src/main/java/org/edx/mobile/module/notification/EdxParsePushBroadcastReceiver.java + +.. _UserNotificationManager.java: https://github.com/openedx/edx-app-android/blob/master/VideoLocker/src/main/java/org/edx/mobile/module/notification/UserNotificationManager.java + +.. _ParseNotificationDelegate.java: https://github.com/openedx/edx-app-android/blob/master/VideoLocker/src/main/java/org/edx/mobile/module/notification/ParseNotificationDelegate.java + +.. _Python SAML Toolkit: https://github.com/onelogin/python-saml + + +.. _Manual Testing: https://github.com/openedx/edx-platform/tree/master/common/test/data/manual-testing-complete + +.. _manual-testing-complete: https://github.com/openedx/edx-platform/tree/master/common/test/data/manual-testing-complete + +.. _2014.xml: https://github.com/openedx/edx-platform/blob/master/common/test/data/manual-testing-complete/course/2014.xml + +.. _edX-Insider: https://github.com/pmitros/edX-Insider + +.. _Ongoing: https://github.com/pmitros/edX-Insider/tree/master/Ongoing + +.. _Week_overview.html: https://github.com/pmitros/edX-Insider/blob/master/Ongoing/html/Week_overview.html + +.. _course.xml: https://github.com/pmitros/edX-Insider/blob/master/Ongoing/course.xml + +.. _edX Demo Course GitHub: https://github.com/openedx/edx-demo-course + +.. EDX WIKI LINKS + +.. _Open edX Releases Wiki page: https://openedx.atlassian.net/wiki/spaces/OpenOPS/pages/11108700/Open+edX+Releases + +.. _Release Pages: https://openedx.atlassian.net/wiki/pages/viewpage.action?pageId=12550314 + +.. _Open edX Installation options: https://openedx.atlassian.net/wiki/x/wwCXAw + +.. _Open edX Native 12.04 Installation: https://openedx.atlassian.net/wiki/x/bgCXAw + +.. _Legacy Open edX Native Installation: https://openedx.atlassian.net/wiki/x/g4G6C + +.. _Koa Open edX Native Installation: https://openedx.atlassian.net/wiki/x/lIJjdQ + +.. _edX Feature Flags: https://openedx.atlassian.net/wiki/spaces/OpenDev/pages/34734726/edX+Feature+Flags + +.. _Managing Open edX Tips and Tricks: https://openedx.atlassian.net/wiki/spaces/OpenOPS/pages/60227913/Managing+Open+edX+Tips+and+Tricks + +.. _How to Override Default Configuration Passwords and Verify Exposed Services: https://openedx.atlassian.net/wiki/spaces/OpenOPS/pages/153813109/How+to+Override+Default+Configuration+Passwords+and+Verify+Exposed+Services + +.. THIRD PARTY LINKS + +.. _Oscar: https://github.com/django-oscar/django-oscar +.. _E-Commerce service: https://github.com/openedx/ecommerce +.. _Transifex: https://www.transifex.com/ +.. _configure the Transifex client: http://docs.transifex.com/client/config/ +.. _Django password validation documentation: https://docs.djangoproject.com/en/2.1/topics/auth/passwords/#module-django.contrib.auth.password_validation +.. _Communications API: http://django-oscar.readthedocs.io/en/latest/howto/how_to_customise_oscar_communications.html#communications-api +.. _django-compressor: http://django-compressor.readthedocs.io/ +.. _RequireJS: http://requirejs.org/ +.. _OpenID Connect: http://openid.net/specs/openid-connect-core-1_0.html +.. _devstack: https://github.com/openedx/devstack +.. _Testing in Django: https://docs.djangoproject.com/en/1.8/topics/testing/ +.. _Django sites framework: https://docs.djangoproject.com/en/1.8/ref/contrib/sites +.. _Jasmine: http://jasmine.github.io/2.3/introduction.html +.. _edX JavaScript Style Guide: https://edx.readthedocs.io/projects/edx-developer-guide/en/latest/style_guides/javascript-guidelines.html +.. _JSHint: http://www.jshint.com/ +.. _jscs: https://www.npmjs.org/package/jscs +.. _Waffle: http://waffle.readthedocs.io/en/latest +.. _Waffle documentation: http://waffle.readthedocs.io/en/latest +.. _Segment: https://segment.com +.. _CourseTalk: https://www.coursetalk.com/ +.. _Google Play: https://play.google.com/store/apps/details?id=org.edx.mobile +.. _App Store: https://itunes.apple.com/us/app/edx/id945480667?mt=8 +.. _VoiceOver for OS X: https://www.apple.com/accessibility/osx/voiceover/ +.. _Creative Commons website: http://creativecommons.org/licenses +.. _Google Fonts: https://www.google.com/fonts#UsePlace:use/Collection:Open+Sans +.. _Time and Date Time Zone Converter: http://www.timeanddate.com/worldclock/converter.html +.. _Cross-referencing arbitrary locations: http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations +.. _Time Zone Converter: http://www.timezoneconverter.com/cgi-bin/tzc.tzc +.. _MOOCdb project: http://moocdb.csail.mit.edu/ +.. _MOOCczar project: https://github.com/UQ-UQx +.. _Google Calendar website: https://www.google.com/calendar +.. _Adobe Flash Player: https://get.adobe.com/flashplayer/ +.. _Oppia XBlock: https://github.com/oppia/xblock + +.. _Durham University Alt Text Checker: https://www.dur.ac.uk/cis/web/accessibility/tools/alttext/ + +.. _Web Accessibility Evaluation Tool: http://wave.webaim.org/ + +.. _Accept-Language: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4 + +.. _Referer: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.36 + +.. _mongodb: http://docs.mongodb.org/manual/ + +.. _MongoDB® database: http://www.mongodb.com + +.. _AWS Command Line Interface: http://aws.amazon.com/cli/ + +.. _AWS Documentation: http://aws.amazon.com/documentation/ + +.. _Docker: https://www.docker.com/community-edition + +.. _Docker documentation: https://docs.docker.com/ + +.. _Docker for Windows: https://docs.docker.com/docker-for-windows/ + +.. _Elastic MapReduce: http://aws.amazon.com/elasticmapreduce/ + +.. _default EC2 role for Amazon EMR: http://docs.aws.amazon.com/ElasticMapReduce/latest/DeveloperGuide/emr-iam-roles-defaultroles.html#emr-iam-roles-defaultec2 + +.. _Default IAM Roles for Amazon EMR: https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-iam-role-for-ec2.html + +.. _a single public subnet: http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Scenario1.html + +.. _example configuration scenario: http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Scenario2.html + +.. _spot pricing market: http://aws.amazon.com/ec2/purchasing-options/spot-instances/ + +.. _MySQL connector library: http://dev.mysql.com/downloads/connector/j/5.1.html + +.. _Gpg4win Compendium: http://www.gpg4win.org/doc/en/gpg4win-compendium.html + +.. _Gpg4win: http://gpg4win.org/ + +.. _GPG Tools: https://gpgtools.org/ + +.. _First Steps: http://support.gpgtools.org/kb/how-to/first-steps-where-do-i-start-where-do-i-begin#setupkey + +.. _3Play Media: http://www.3playmedia.com + +.. _Wikipedia XML entry: http://en.wikipedia.org/wiki/XML + +.. _LON-CAPA: http://www.lon-capa.org/ + +.. _LON-CAPA XML format: https://s1.lite.msu.edu/adm/help/Authoring_XML_Intro.hlp#Authoring_XML_Intro + +.. _make: https://www.gnu.org/software/make/ + +.. _LaTeX: http://www.latex-project.org/ + +.. _RST: http://docutils.sourceforge.net/rst.html + +.. _Proctoring Software System Requirements: http://clientportal.softwaresecure.com/support/index.php?/Knowledgebase/Article/View/252/0/system-requirements-remote-proctor-now + +.. _Vagrant's documentation on boxes: http://docs.vagrantup.com/v2/boxes.html + +.. _RabbitMQ: http://www.rabbitmq.com/ + +.. _Download Python: https://www.python.org/downloads/release/python-386/ + +.. _YouTube Data API v3: https://developers.google.com/youtube/v3/ + +.. _instructions for obtaining authorization credentials: https://developers.google.com/youtube/registering_an_application + +.. _nginx: http://nginx.com + +.. _gunicorn: http://gunicorn.org + +.. _Introduction to the Mac OS X Command Line: http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line + +.. _Windows Command Line Reference: http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/ntcmds.mspx?mfr=true + +.. _Vagrant Getting Started: http://docs.vagrantup.com/v2/getting-started/index.html + +.. _VirtualBox: https://www.virtualbox.org/wiki/Downloads + +.. _Vagrant: http://www.vagrantup.com/downloads.html + +.. _VirtualBox Guest Editions: http://www.virtualbox.org/manual/ch04.html + +.. _Vagrant documentation: http://docs.vagrantup.com/v2/ + +.. _Ansible: https://docs.ansible.com/ + +.. _Font Awesome: http://fortawesome.github.io/Font-Awesome/icons/ + +.. _BitTorrent: http://www.bittorrent.com/ + +.. _Shibboleth configuration wiki: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPMetadataProvider + +.. _Azure portal: https://manage.windowsazure.com + +.. _Microsoft Azure: https://azure.microsoft.com/en-us/pricing/free-trial/ + +.. _python-social-auth backend documentation: http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends + +.. _IMS LTI 1.1 Consumer Launch: http://www.imsglobal.org/developers/LTI/test/v1p1/lms.php + +.. _LTI 1.1: https://www.imsglobal.org/LTI/v1p1p1/ltiIMGv1p1p1.html + +.. _LTI 1.3: https://www.imsglobal.org/spec/lti/v1p3 + +.. _LTI Advantage: https://www.imsglobal.org/lti-advantage-overview + +.. _Deep Linking: https://www.imsglobal.org/spec/lti-dl/v2p0 + +.. _Assignments and Grades services: https://www.imsglobal.org/spec/lti-ags/v2p0 + +.. _Names and Roles Provisioning Service: https://www.imsglobal.org/spec/lti-nrps/v2p0 + +.. _LTI_NRPS_ACTIVE_ENROLLMENT_LIMIT setting: https://github.com/openedx/xblock-lti-consumer/blob/master/docs/decisions/0004-lti-advantage-nrps.rst#decision + +.. _Issuing Badges: https://wiki.mozilla.org/Badges/Onboarding-Issuer#Issuing_Badges + +.. _Oppia: https://www.oppia.org + +.. _Oppia User Documentation: https://oppia.github.io/ + +.. _Office Mix: http://www.mixforteachers.com/what-is-office-mix.html + +.. _Office Mix gallery: https://mix.office.com/Gallery + +.. _Office Mix Knowledge Base: https://officemix.uservoice.com/knowledgebase + +.. _How to add Closed Captions to an Office Mix: https://officemix.uservoice.com/knowledgebase/articles/505262-how-to-add-closed-captions-to-an-office-mix + +.. _W3C CSS color specification: https://www.w3.org/TR/css-color-3/ + +.. _ESLint: https://openedx.atlassian.net/wiki/display/FEDX/ESLint + +.. _Webpack: https://webpack.js.org/ + +.. _Tutor: https://docs.tutor.overhang.io/ + +.. Release Notes + + + +.. _edX101: https://www.edx.org/course/overview-creating-edx-course-edx-edx101#.VIIJbWTF_yM + + +.. _GitHub Flow: https://github.com/blog/1557-github-flow-in-the-browser +.. _RST: http://docutils.sourceforge.net/rst.html + +.. _edX Insights: https://insights.edx.org + +.. _edX Status: http://status.edx.org/ + +.. _docs.edx.org: http://docs.edx.org + +.. _edX roadmap: https://open.edx.org/features-roadmap/all + +.. _MathJax 2.4: http://docs.mathjax.org/en/latest/whats-new-2.4.html#whats-new-2-4 + +.. _MathJax 2.3: http://docs.mathjax.org/en/latest/whats-new-2.3.html#whats-new-2-3 + + +.. _Open edX wiki page for Dogwood: https://openedx.atlassian.net/wiki/display/OPEN/Dogwood + +.. _Dogwood blog post: https://open.edx.org/blog/newest-open-edx-release-dogwood-now-available + +.. _Adding E-Commerce to the Open edX Platform (Dogwood): http://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/named-release-dogwood.rc/ecommerce/index.html + +.. _Open edX Conference: http://con.openedx.org/ + +.. _Registration: http://www.eventbrite.com/e/open-edx-con-2015-tickets-17211056734?aff=relnotes + +.. _Django 1.5: https://docs.djangoproject.com/en/1.8/releases/1.5 + +.. _Django 1.6: https://docs.djangoproject.com/en/1.8/releases/1.6 + +.. _Django 1.7: https://docs.djangoproject.com/en/1.8/releases/1.7 + +.. _Django 1.8: https://docs.djangoproject.com/en/1.8/releases/1.8 + +.. _1.8.6: https://docs.djangoproject.com/en/1.8/releases/1.8.6/ + +.. _1.8.7: https://docs.djangoproject.com/en/1.8/releases/1.8.7/ + +.. _Django website: https://www.djangoproject.com + +.. _Django Forms: https://docs.djangoproject.com/en/1.8/ref/forms/ + +.. _Database Transactions: https://docs.djangoproject.com/en/1.8/topics/db/transactions + +.. _Django 1.8 Upgrade Release Notes: https://openedx.atlassian.net/wiki/display/TNL/Django+1.8+Upgrade+Release+Notes + +.. _Django 1.8 pull request: https://github.com/openedx/edx-platform/pull/10401 + +.. _app_label: https://docs.djangoproject.com/en/1.8/ref/models/options/#app-label + +.. _Sass: http://sass-lang.com/ +.. _Sass variables: http://sass-lang.com/documentation/file.SASS_REFERENCE.html#variables_ +.. _Sass partials: http://sass-lang.com/documentation/file.SASS_REFERENCE.html#partials +.. _the documentation for Sass partials: http://sass-lang.com/documentation/file.SASS_REFERENCE.html#partials +.. _the documentation for Sass variable defaults: http://sass-lang.com/documentation/file.SASS_REFERENCE.html#variable_defaults_ +.. _Sass/CSS Styleguide: https://github.com/edx/ux-pattern-library/wiki/Styleguide:-Sass-&-CSS + +.. _News About edX Certificates: http://blog.edx.org/news-about-edx-certificates?track=blog + +.. _edX course catalog: https://www.edx.org/course-list/allschools/verified/allcourses` + +.. _edX Programs: https://www.edx.org/course?program=all + +.. _Verified Certificates: https://www.edx.org/verified-certificate + +.. _XSeries: https://www.edx.org/xseries + +.. _XSeries Programs: https://www.edx.org/xseries + +.. _MicroMasters: https://www.edx.org/micromasters + +.. _MicroMasters Programs: https://www.edx.org/micromasters + +.. _Professional Certificate: https://www.edx.org/professional-certificate + +.. _Professional Certificate Programs: https://www.edx.org/professional-certificate + +.. _financial assistance application: https://courses.edx.org/financial-assistance + +.. _LinkedIn: https://www.linkedin.com/ + +.. _Adding a Suffix or Certifications to Your Profile Name: https://www.linkedin.com/help/linkedin/answer/6545/adding-a-suffix-or-certifications-to-your-profile-name?lang=en + +.. Browsers + +.. _Chrome: https://www.google.com/chrome + +.. _Safari: https://www.apple.com/safari + +.. _Firefox: https://mozilla.org/firefox + +.. _Microsoft Edge: https://www.microsoft.com/microsoft-edge + +.. _Microsoft Internet Explorer: http://windows.microsoft.com/internet-explorer/download-ie + +.. Peer Instruction + +.. _Turn to Your Neighbor: https://peerinstruction.wordpress.com/ + +.. _OAuth 2.0 Standard: https://tools.ietf.org/html/draft-ietf-oauth-v2-31 + +.. _curl client program: https://curl.haxx.se/ + +.. Video Catalog + +.. _Adding a Video ID: https://youtu.be/7Yc1Z8RLYxM + +.. _OID: https://en.wikipedia.org/wiki/Object_identifier + +.. _URN: https://en.wikipedia.org/wiki/Uniform_Resource_Name + +.. _eduPersonPrincipalName: https://www.internet2.edu/media/medialibrary/2013/09/04/internet2-mace-dir-eduperson-201203.html#eduPersonPrincipalName + +.. _eduPersonEntitlement: https://www.internet2.edu/media/medialibrary/2013/09/04/internet2-mace-dir-eduperson-201203.html#eduPersonEntitlement + +.. _eduPerson Object Class Specification: https://www.internet2.edu/media/medialibrary/2013/09/04/internet2-mace-dir-eduperson-201203.html + +.. _official Google instructions: https://developers.google.com/identity/protocols/oauth2 + +.. _Google Developers Console: https://console.developers.google.com/project/_/apiui/apis/library + +.. _Facebook for Developers: https://developers.facebook.com/apps/?action=create + +.. _LinkedIn Developers: https://www.linkedin.com/secure/developer + +.. _Microsoft Sign In: https://account.live.com + +.. _Azure account creation: https://azure.microsoft.com/en-us/pricing/free-trial + +.. _Azure sign in: https://portal.azure.com + +.. _AWS template file: https://github.com/openedx/edx-platform/blob/b3462e5b1c3cc45ad8673f3f12e84fa17ffa6b64/lms/envs/aws.py#L586-L596 + +.. _random and highly secure password: https://github.com/openedx/edx-platform/blob/46d69eba/common/djangoapps/third_party_auth/pipeline.py#L392-L410 + +.. _OAuth backends supported by python-social-auth v0.2.12: http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends + +.. _python-social-auth supported backend: http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends + +.. _list of python-social-auth backends: https://github.com/omab/python-social-auth/tree/master/social/backends + +.. _python-social-auth documentation: http://python-social-auth.readthedocs.io/en/latest/index.html + +.. _the default value in the aws.py file: https://github.com/openedx/edx-platform/blob/b3462e5b1c3cc45ad8673f3f12e84fa17ffa6b64/lms/envs/aws.py#L586-L596 + +.. _Media formats supported by the HTML audio and video elements: https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#MP4_H.264_(AAC_or_MP3) + +.. _editing object metadata: http://docs.aws.amazon.com/AmazonS3/latest/UG/EditingtheMetadataofanObject.html + +.. _Amazon S3: http://aws.amazon.com/s3/ + +.. _YouTube: http://www.youtube.com + +.. _3Play Media: http://www.3playmedia.com + +.. _Cielo24: http://www.cielo24.com + +.. _Creating Video for the edX Platform: https://www.edx.org/course/videox-creating-video-for-the-edx-platform + +.. _Creating Videos: https://courses.edx.org/courses/edX/edX101/2014/courseware/c2a1714627a945afaceabdfb651088cf/9dd6e5fdf64b49a89feac208ab544760/ + +.. _edX101 Overview of Creating an edX Course: https://www.edx.org/node/5496#.VH8p51fF_FA + +.. _12 Principles of Multimedia Learning: http://hartford.edu/academics/faculty/fcld/data/documentation/technology/presentation/powerpoint/12_principles_multimedia.pdf + +.. _List of ISO 639-1 codes: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes + +.. _Proctoring Software System Requirements: http://clientportal.softwaresecure.com/support/index.php?/Knowledgebase/Article/View/252/0/system-requirements-remote-proctor-now + +.. _edX Automated Communication Engine: http://edx-ace.readthedocs.io/en/latest + +.. _JIRA Platform project: https://openedx.atlassian.net/projects/PLAT/issues + +.. _retirement: https://user-retirement-guide.readthedocs.io/en/latest/index.html + +.. _User Retirement: https://user-retirement-guide.readthedocs.io/en/latest/index.html + +.. _Open edX Release Notes: http://edx.readthedocs.io/projects/open-edx-release-notes/en/latest/ironwood.html + +.. _Password Policy: https://github.com/openedx/edx-platform/wiki/Optional-Password-Policy-Enforcement + +.. _Taking Timed and Proctored Exams: https://support.edx.org/hc/en-us/sections/115004169247 + +.. _Proctored exam rules and requirements: https://support.edx.org/hc/en-us/articles/360000218027 + +.. _Technical problems during a proctored exam: https://support.edx.org/hc/en-us/articles/360000205167 + +.. _Checking Your Onboarding Status and Resetting Your Onboarding Exam: https://support.edx.org/hc/en-us/articles/1500002350902 + +.. _XQueue: https://github.com/openedx/xqueue + +.. _edX XQueue repository: https://github.com/openedx/xqueue/blob/master/queue + +.. _GnuPG website: https://www.gnupg.org + +.. _xqueue_watcher: https://github.com/openedx/xqueue-watcher + +.. _Stanford Online xqueue_pull_ref: https://github.com/Stanford-Online/xqueue_pull_ref + +.. _Mozilla Firefox: https://www.mozilla.org/en-US/firefox/new/ diff --git a/source/developers/references/legacy_guide/preventing_xss/index.rst b/source/developers/references/legacy_guide/preventing_xss/index.rst new file mode 100644 index 00000000..12f21e2f --- /dev/null +++ b/source/developers/references/legacy_guide/preventing_xss/index.rst @@ -0,0 +1,13 @@ +.. _preventing_xss: + +############################################### +Preventing Cross Site Scripting Vulnerabilities +############################################### + +.. toctree:: + :maxdepth: 2 + + preventing_xss + preventing_xss_strip_tags + preventing_xss_in_django_templates + preventing_xss_in_react diff --git a/source/developers/references/legacy_guide/preventing_xss/preventing_xss.rst b/source/developers/references/legacy_guide/preventing_xss/preventing_xss.rst new file mode 100644 index 00000000..6f1cede8 --- /dev/null +++ b/source/developers/references/legacy_guide/preventing_xss/preventing_xss.rst @@ -0,0 +1,1880 @@ +.. _Preventing XSS: + +############################################### +Preventing Cross Site Scripting Vulnerabilities +############################################### + +Cross Site Scripting (XSS) vulnerabilities allow user-supplied data to be +incorrectly executed as code in a web browser. It can be difficult to write code +that is safe from XSS security vulnerabilities. This section presents best +practices for handling proper escaping in the Open edX platform to avoid these +vulnerabilities. + +.. note:: If you become aware of security issues, do not report them in + public. Instead, please email security@openedx.org. + +.. contents:: + :depth: 1 + :local: + + +Philosophy and General Rules +**************************** + +The philosophy behind the recommendations in this section is to make things as +simple as possible for developers. Protecting against XSS vulnerabilities +typically requires properly escaping user-provided data before it is placed on +the page. Rather than trying to determine if data is user-provided and could +be compromised, we will play it safe and escape data whether it is user- +provided or not. Unfortunately, because there are many different rules for +escaping, you still must choose the proper type of escaping. + +Here are some general rules. + +#. **Escape always.** Assume that all data is untrusted and escape it + appropriately. Do not try to determine whether data could or could not be + manipulated by a user. + +#. **Escape late.** Delay escaping as long as possible, until you can see the + actual context and understand the proper escaping that is required for + the context. Browsers interpret different contexts such as HTML, URLs, + CSS, and Javascript/JSON with different rules, so there are different + escaping requirements based on where the data is being used in a page. + +#. **Escape appropriately.** Know what kind of data you have (for example, + HTML, plain text, or JSON) and where it is going (for example, HTML or + JavaScript). Choose the proper escaping function based on these details. + +#. **Validation is not sufficient.** Validating inputs does not replace the + need to properly escape. In some cases, this may reduce the likelihood of + potential problems, but proper escaping is always necessary. + +#. **Do not store escaped data.** Again, because you do not know ahead of time + all the places that the data will be used, you must wait until you have + the proper context to decide on the proper escaping. + + +Types of Context and Escaping +***************************** + +.. contents:: + :depth: 1 + :local: + +Overview of Contexts +==================== + +The following diagram provides a high-level overview of the relationship +between the different templates, different contexts of DOM creation and +manipulation, and different types of escaping. As a general rule, proper +escaping is related to the context in which the data is being written, and +might not match the context that will eventually be reading the data. + +.. image:: ../images/preventing-xss.png + :width: 666px + :height: 289px + :align: center + :alt: A diagram detailing how data flows from Django applications and Django + models through Mako templates and Django templates into an HTML page. Data can + then flow from the HTML page into JavaScript, and back down into the DOM + through jQuery or Underscore.js templates. + +In the Open edX platform, data flows from the application to the initial HTML page +mainly through the use of Mako templates. + +.. Make sure the numbers in the list below are in sync with the numbered arrows in +.. the preventing-xss.png diagram above, if either the diagram or the list is modified. + +Descriptions of each numbered arrow in the diagram follow. + +#. This step represents the use of Mako templates to write general HTML tags + (that is, tags other than `` + +The following resulting unsafe page source is sent to the browser. + +.. code-block:: mako + +