[LON-CAPA-users] version control

Michael T Hamlin lon-capa-users@mail.lon-capa.org
Tue, 4 Nov 2003 14:26:41 -0500 (EST)

as promised...

    version control issues and proposal.

two issues.

You can't just keep all versions of things.  That's not enough.
You must keep track of dependencies, and manage those connections,
or else things break.

Currently when you import a published resource into a course, that
link is NOT version dependent.  If someone alters that published
resource, then it would change in ALL the courses which use it.
While convenient for people writing their own material, this
behavior WILL cause things to break, and badly.

(for example: you write a problem using a library someone else wrote.
The problem does exactly what you want.  Then the library gets updated
and a function name or syntax changed.  Now without you having done
anything at all, your problem is broken, and you get no warning about it.
And if that problem was in a course, its even worse.

Imagine you've imported a working problem into your course, then
the author edits it without your knowledge.  Maybe the problem broke,
or changed numbers of parts or part ids.  If the problem was open, some
students perhaps already answered the problem, when it was working, in its
first form.  Others get an error message, or more insidious: they have more
or fewer or relabeled parts.  Serious grading inconsistencies.)

A proposed solution.

First:  When imported into courses, resources should AUTOMATICALLY be
nailed to the version number.  If a teacher saw and chose a resource, then
s/he meant to include THAT resource.  The contents of _their_ course should
NOT change without their knowledge and approval.  Nail down versions
by default.

Second:  Indicate to the course supervisor when resources have changed
since the versions they imported.  Provide a mechanism to browse the new
versions, get "diffs" on the versions, and easily update the course content
to the newer versions (both as individual resources, folder-wide, and
course-wide).  A good interface in the Docs screen would make all this very
natural and minimize the work:

   Folder Title:  Lecture 16 Problems   [[update all resources]]

   <<controls>>     <<Resource Title>>  <<Version>>   <<latest version info>>
   V^ Remov Renam   Inverse Trig         [rev 3] v
   V^ Remov Renam   River Survey         [rev 4] v
   V^ Remov Renam   Wired Antenna        [rev 2] v^   "rev 4" "diffs" [update]
   V^ Remov Renam   High Stack           [rev 3] v

There is an (easy) mechanism for devolving to older versions.  Next to the
[rev 3] entry in Line 1 is a down arrow, which changes the course content to
use version 2.
  Line 3 shows a resource in the course which is not the latest published
version of that resource; it would appear a different color than the other
lines.  Clicking on the up arrow would advance to using version 3.  Clicking
on "rev 4" would open a window with the version 4 resource.  Clicking on
"diffs" would give the same result as the author gets using "diffs".
Clicking on [update] button would update the resource link to the most
recent version of the resource (version 4 in this case).
  Next to the folder name a button "Update all resources" would do just
that: reset all resource links to the most recent published versions.  This
button would only appear if there are any resources not up to the latest date.

A few caveats.  If the differences between the existing and new versions are
major, like changes in part numbers or ids, there should be a severe warning,
unless the there are no submission records on that resource.  Other than that,
perhaps there would be a minor warning if the resource is currently "open".

Third: Real Versions.  When "version N" of a "resource A" is displayed, other
resources which are needed by resource A should also be the versions which
were current at the time resource A version N was published.  Without
back-dating versions of all the resources used by resource A in this way,
you -cannot- replicate the exact appearance of a resource A at the time of
version N's publication.  And there are times when _exact_ replication are
necessary; in cases of an exam dispute, for example.  The publication dates
of all resources can be used to figure out which versions were current at
any given time.
  Most importantly, this type of version control avoids all situations I
described at the top:  problems breaking (or other havoc) solely because of
version updates, and without any notification.  If you import a problem while
it is working, it will always work, because it will NEVER change without you
reviewing the changes and confirming they are good.
  This technique would have the side effect of prohibiting the publication of
a resource when a dependent resource is missing, which is currently permitted
(although there is a minor warning about it).

please, seriously consider this proposal.