Index: openacs-4/packages/assessment/www/doc/versioning.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/assessment/www/doc/versioning.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/assessment/www/doc/versioning.adp 20 Aug 2015 17:36:22 -0000 1.1.2.1
+++ openacs-4/packages/assessment/www/doc/versioning.adp 25 Aug 2015 18:02:19 -0000 1.1.2.2
@@ -2,13 +2,13 @@
This topic requires special mention because it is centrally
+ This topic requires special mention because it is centrally
important to Assessment and one of the most radical departures from
the current packages (in which "surveys" or "questionnaires" are
all one-shot affairs that at best can be cloned but not readily
-modified in a controlled fashion). During its lifetime, an Assessment may undergo revisions in the
+modified in a controlled fashion). During its lifetime, an Assessment may undergo revisions in the
midst of data collection. These revisions may be minor (change of a
label on an Item or adddition of a new Choice to an Item) or major
(addition or deletion of an entire Section). Obviously in most
@@ -17,51 +17,63 @@
the Assessment package must accommodate them. Clinical trial
protocols change; teachers alter their exams from term to term. And
still, there is a crucial need to be able to assemble and interpret
-data collected across all these changes. Another type of "revision" occurs when a component (an Item
+data collected across all these changes. Another type of "revision" occurs when a component (an Item
Choice, Item, Section, or the entire Assessment) needs to be
translated into another language. Even if the semantics of the
component are identical (and they should be or you need a better
translator ;-), the Assessment package needs to handle this
situation correctly: an admin user needs to be able to "assign" the
right language version to a set of subjects, and the returned user
-data need to be assembled into trans-language data sets. Note that two orthogonal constructs are in play here:Overview
Overview
+
+data need to be assembled into trans-language data sets.
Note that two orthogonal constructs are in play here:
+The Content Repository (CR) in OpenACS is designed to handle + +
The Content Repository (CR) in OpenACS is designed to handle these complex design issues, though it is still undergoing refinements and how best to use it is also still being discovered. -So the ideas here are still somewhat exploratory.
For each of the package components that need to be versioned +So the ideas here are still somewhat exploratory.
+For each of the package components that need to be versioned (certainly the core components as_assessments, as_sections, as_items, and as_item_choices; but also other components like as_policies), we extend the basic CR entities cr_items and cr_revisions. Thus we actually have, for instance, two tables for -Items:
This pattern of dual tables is used for all components that need +
This pattern of dual tables is used for all components that need to behave this way. When an admin user creates a new Item, a new row is inserted into the as_items and the as_items_revs table. Then when the same admin user (or another admin user) changes something -about the Item, a new as_items_revs row is inserted.
Now here is where things become tricky, though.. Any time a +about the Item, a new as_items_revs row is inserted.
+Now here is where things become tricky, though.. Any time a component is changed, there is a simultaneous implicit change to the entire hierarchy. Data collected after this change will be collected with a semantically different instrument. Whether the difference is large or small is immaterial; it is different, and Assessment must handle this. And the CR doesn't do this for us -automagically.
So what the package must do is version both the individual +automagically.
+So what the package must do is version both the individual entities and also all the relationships over which we join when we're assembling the entire Assessment (whether to send out to a requesting user, to stuff the database when the form comes back, or -to pull collected data into a report).
This doesn't involve merely creating triggers to insert new +to pull collected data into a report).
+This doesn't involve merely creating triggers to insert new mapping table rows that point to the new components. We also need to insert new revisions for all components higher up the hierarchy -than the component we've just revised. Thus:
Another key issue, discussed in this +
Another key issue, discussed in this thread, involves the semantics of versioning. How big of a modification in some Assessment package entity needs to happen before that entity is now a "new item" instead of a "new version of an existing item"? If a typo in a single Item Choice is corrected, one can reasonably assume that is merely a new version. But if an Item of multiple choice options is given a new choice, is this Item -now a new one?
One possible way this could be defined would derive from the +now a new one?
+One possible way this could be defined would derive from the hierarchy model in the CR: cr_items -- but not cr_revisions -- can contain other entities; the parent_id column is only in cr_items. Thus if we want to add a fifth as_item_choice to an as_item (while preserving the state of the as_item that only had four as_item_choices), we need to insert a new as_item and not merely a -new as_item_rev for the existing as_item.
A final point concerns the mapping tables. The OpenACS framework +new as_item_rev for the existing as_item.
+A final point concerns the mapping tables. The OpenACS framework
provides a variety of special-purpose mapping tables that are all
proper acs_objects (member_rels, composition_rels, acs_rels, and
the CR's own cr_rels). These provide additional control over
permissioning but fundamentally are mapping tables. In the long run
the benefit of using them is the ability of OpenACS 6, to auto
construct code based on cr_item_types and relationships.
-
Within each subsystem of the Assessment package, the following +
+Within each subsystem of the Assessment package, the following entities will inherit from the CR. We list them here now, and once we've confirmed this selection, we'll move the information out to -each of the subsystems' pages.