Skip to content

Commit ec8d954

Browse files
mhoebermhoeber
committed
Merge pull request openedx#5793 from edx/markhoeber-doc1160
WIP - Split Mongo Documentation
2 parents 757e8f1 + 3b84d60 commit ec8d954

File tree

6 files changed

+235
-0
lines changed

6 files changed

+235
-0
lines changed

‎docs/en_us/developers/source/change_log.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ Change Log
1010

1111
* - Date
1212
- Change
13+
* - 11/07/14
14+
- Created the :ref:`edX Modulestores` section and added the :ref:`Split
15+
Mongo Modulestore` chapter.
1316
* - 06/23/14
1417
- Added a :ref:`Preface` with resources for course teams, developers, researchers, and students.
1518
* - 05/20/14

‎docs/en_us/developers/source/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Contents:
1919
browsers.rst
2020
overview.rst
2121
extending_platform/index
22+
modulestores/index
2223
xblocks.rst
2324
pavelib.rst
2425
public_sandboxes.rst

‎docs/en_us/developers/source/modulestores/index.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.. _edX Modulestores:
2+
3+
###########################
4+
edX Modulestores
5+
###########################
6+
7+
.. toctree::
8+
:maxdepth: 2
9+
10+
overview
11+
mixedmodulestore
12+
split-mongo

‎docs/en_us/developers/source/modulestores/mixedmodulestore.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#################
2+
MixedModuleStore
3+
#################
4+
5+
MixedModuleStore provides a common API for all modulestore functions.
6+
7+
In addition, MixedModuleStore allows you to select which modulestore a
8+
specific course is stored in (XMLModuleStore, DraftModuleStore, Split Mongo)
9+
and routes requests for that course to the correct modulestore.
10+
11+
MixedModuleStore can also handle some conversions from one modulestore to
12+
another.

‎docs/en_us/developers/source/modulestores/overview.rst

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
#################################
2+
Overview of the edX Modulestores
3+
#################################
4+
5+
The edX Platform uses several different modulestores to store course data. Each
6+
of these modulestores is in use on edx.org.
7+
8+
See:
9+
10+
* `XMLModuleStore`_
11+
* `DraftModuleStore`_
12+
* :ref:`Split Mongo Modulestore`
13+
14+
***************
15+
XMLModuleStore
16+
***************
17+
18+
The XMLModuleStore was the first modulestore used for the edX Platform.
19+
20+
XMLModuleStore uses a file system that stores XML-based courses. When the LMS
21+
server starts, XMLModuleStore loads every block for every course into memory.
22+
23+
XMLModuleStore is read-only and does not enable users to change a course
24+
without restarting the server.
25+
26+
*****************
27+
DraftModuleStore
28+
*****************
29+
30+
DraftModuleStore was the next generation modulestore and provides greater
31+
scalability by allowing random access to course blocks and loading blocks on
32+
requests.
33+
34+
DraftModuleStore allows editing of courses without restarting the server.
35+
36+
In addition, DraftModuleStore stores a draft version of some types of blocks.
37+
38+
*****************
39+
Split Mongo
40+
*****************
41+
42+
Split Mongo is the newest modulestore. See the :ref:`Split Mongo Modulestore`
43+
chapter for more information.

‎docs/en_us/developers/source/modulestores/split-mongo.rst

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
.. _Split Mongo Modulestore:
2+
3+
############################
4+
Split Mongo Modulestore
5+
############################
6+
7+
See:
8+
9+
* `Overview`_
10+
* `Split Mongo Data Model`_
11+
* `Split Mongo Capabilities`_
12+
13+
14+
************************
15+
Overview
16+
************************
17+
18+
*Split Mongo* is the term used for the new edX modulestore. Split Mongo is
19+
built on mongoDB. For information about mongoDB, see the `mongoDB website`_.
20+
21+
The "split" in Split Mongo refers to how a course is split into three types of
22+
information:
23+
24+
* The course identity, referred to as the `course index <Course Index>`_.
25+
* The `course structure <Course Structures>`_.
26+
* The course content, referred to as `XBlock definitions <XBlock Definitions>`_.
27+
28+
This separation of identity, structure, and content enables course authors to
29+
use more advanced capabilities when developing and managing courses.
30+
31+
.. _mongoDB website: http://www.mongodb.org
32+
33+
************************
34+
Split Mongo Data Model
35+
************************
36+
37+
In the Split Mongo data model, edX courses are split into three collections:
38+
39+
* `Course Index`_
40+
* `Course Structures`_
41+
* `XBlock Definitions`_
42+
43+
=============
44+
Course Index
45+
=============
46+
47+
The course index is a dictionary that stores course IDs. Each course ID points
48+
to a course structure.
49+
50+
The course index supports multiple branches of a course. The index can store
51+
multiple entries for a course ID, with each entry pointing to a different
52+
course structure that corresponds to a different branch.
53+
54+
As currently implemented, for each course, there is a branch for both the
55+
published and draft versions of the course. The published and draft branches of
56+
the course point to different structures.
57+
58+
In the edX Platform:
59+
60+
* Students using the LMS see and interact with the published version of the
61+
course.
62+
63+
* Course staff using edX Studio make changes to the draft version of the
64+
course.
65+
66+
* When the user changes a the course outline, display names, the course
67+
about page, course updates, other course pages, sections or subsections,
68+
the draft branch is automatically published; that is, it becomes the
69+
published branch.
70+
71+
* For units and components, changes are saved in the draft branch. The user
72+
must publish the unit to change the draft branch to the published branch.
73+
When the user begins another set of changes, the draft branch is updated.
74+
75+
Course Reruns
76+
**************
77+
78+
The edX Platform enables you to rerun a course. When you rerun a course, a new
79+
course index is created. The new course index points to the same course
80+
structure as the original course index.
81+
82+
==========================
83+
Course Structures
84+
==========================
85+
86+
The course structure defines, or outlines, the content of a course.
87+
88+
A course structure is made up of blocks in a tree data structure. Blocks are
89+
objects in a course, such as the course itself, sections, subsections, and
90+
units. A block can reference other blocks; for example, a section references
91+
one or more subsections. Each block has a unique ID that is generated by the
92+
edX Platform.
93+
94+
Each block in the course structure points to an XBlock definition. Different
95+
blocks, in the same or in different structures, can point to the same
96+
definition.
97+
98+
Course structures, and each block within a structure, are versioned. That is,
99+
when a course author changes a course, or a block in the course, a new course
100+
structure is saved; the previous course structure, and previous versions of
101+
blocks within the structure, remain in the database and are not modified.
102+
103+
==========================
104+
XBlock Definitions
105+
==========================
106+
107+
XBlock definitions contain the content of each block. For some blocks, such as
108+
sections and subsections, the definition consists of the block's display name.
109+
For components, such as HTML or problem components, the definition also
110+
contains the content of the object. A definition can be referenced by multiple
111+
blocks.
112+
113+
XBlock definitions are versioned. That is, when a course author changes
114+
content, a new XBlock definition for that object is saved; the previous
115+
definition remains in the database and is not modified.
116+
117+
************************
118+
Split Mongo Capabilities
119+
************************
120+
121+
The Split Mongo data model enables the edX Platform to implement advanced
122+
content management functionality. Specifically, Split Mongo is designed to
123+
enable:
124+
125+
* `Multiple Course Branches`_
126+
* `Versioning`_
127+
* `Content Reuse`_
128+
129+
While these capabilities are not fully implemented in the edX Platform, Split
130+
Mongo is designed to allow future enhancements that enable these content
131+
management capabilities.
132+
133+
========================
134+
Multiple Course Branches
135+
========================
136+
137+
Split Mongo enables multiple branches of a course. The `course index <Course
138+
Index`>_ can have multiple entries for a course ID, each of which points to a
139+
different structure.
140+
141+
The edX Platform currently uses a draft and a published branch for a course.
142+
Future enhancements may use other branches.
143+
144+
============
145+
Versioning
146+
============
147+
148+
In Split Mongo, every change to a course or a block within the course is saved,
149+
with the time and user recorded.
150+
151+
Versioning enables future enhancements such as allowing course authors to
152+
revert a course or block to a previous version.
153+
154+
==============
155+
Content Reuse
156+
==============
157+
158+
By using pointers to reference XBlock definitions from `course structures
159+
<Course Structures>`_, Split Mongo enables content reuse. A single `XBlock
160+
definition <XBlock Definition>`_ can be referenced from multiple course
161+
structures.
162+
163+
Future enhancements to the edX Platform can allow course authors to reuse an
164+
XBlock in multiple contexts, streamlining course development and maintenance.

0 commit comments

Comments
 (0)