~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to doc/notes/subversion.txt

  • Committer: William Grant
  • Date: 2012-06-28 01:52:02 UTC
  • Revision ID: me@williamgrant.id.au-20120628015202-f6ru7o367gt6nvgz
Hah

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
IVLE Design - Subversion Web Access
2
 
===================================
3
 
 
4
 
    Author: Matt Giuca
5
 
    Date: 3/12/2007
6
 
 
7
 
We will provide students with a web interface to Subversion. A major focus of
8
 
the web interface is to shield new students from the details of actually
9
 
managing a repository and just provide them with what looks like a normal file
10
 
browser, which happens to backup their files.
11
 
 
12
 
We are considering writing our own web file browser to Subversion.
13
 
 
14
 
The original concept is this (as implemented in the IVLE / PynApple prototype):
15
 
 
16
 
* Provide an interface to just the repository. All accesses are done directly
17
 
  to the repository, the interface knows nothing about workspaces.
18
 
* Editing the files within the environment automatically commits the changes
19
 
  to the repo.
20
 
* Allow import / export of files.
21
 
* Execute the Python programs in a special "run" directory which protects the
22
 
  user's workspace.
23
 
* Presumably allow some kind of rollback to previous versions.
24
 
 
25
 
This was problematic because it did not allow us to browse the directories
26
 
outside of subversion (such as the execution directory).
27
 
 
28
 
Our new design is to write a web-based _workspace_ browser. This will give
29
 
students a more hands-on experience using a repository, but more importantly
30
 
let them see what temporary files are being created and clean them up. This
31
 
simplifies the system and reduces the amount of "magic" we have to perform
32
 
around the students.
33
 
 
34
 
A major advantage of this is that we no longer have to have a separate file
35
 
browser from the repository browser. There is no "execution" directory - the
36
 
student just works entirely within their own workspace. (If necessary this
37
 
browser could be made to explore parts of the file system outside of a
38
 
workspace, simply disabling the SVN features).
39
 
 
40
 
This means the student can have their permanent files (say "flower-in.png") in
41
 
the same directory as the temporary files (say "flower-out.png") and not need
42
 
to worry about changing directories or any of those complications.
43
 
 
44
 
Terminology shift
45
 
-----------------
46
 
 
47
 
In order to shield new students from the immediate reality of a "repository",
48
 
we will present the system as a simple extension of a normal file system they
49
 
are used to. (This section is written in a deliberately obtuse style; this is
50
 
the "story" we will tell new students).
51
 
 
52
 
The student is given a "workspace", with no mention of a repository. Inside
53
 
the workspace they have "permanent files" and "temporary files". Permanent
54
 
files are those which exist in both the (somewhat hidden) repository, and the
55
 
workspace, while temporary files exist only in the workspace.
56
 
 
57
 
Unlike originally proposed, editing and saving documents will *not*
58
 
auto-commit. We hope to augment the editor with a "save" button (which saves
59
 
to the workspace) and a "save-and-commit" button (which saves and commits the
60
 
file automatically, possibly asking for a log message).
61
 
 
62
 
The paradigm we present to students is: the system saves a permanent backup of
63
 
your file when you hit "save-and-commit". In fact, each time you hit
64
 
"save-and-commit" it saves a separate backup, so later you can go back to any
65
 
older version. Files backed up permanently are the so-called "permanent files"
66
 
while files which haven't been committed permanently are "temporary files".
67
 
 
68
 
Editing a permanent file and saving it but not committing it results in an
69
 
"out-of-date" file. This means you have made changes which aren't yet
70
 
permanently backed up. The commit button either in the editor or the file
71
 
browser will ensure these changes are permanently saved.
72
 
 
73
 
A useful reason we have temporary files is you can muck around with them
74
 
however you like, and if you don't like the changes, you can "roll back" or
75
 
"clean up" by hitting the cleanup button. The cleanup button does *two* things
76
 
- it "undoes" all the changes you made to out-of-date files, going back to
77
 
their last permanent version, and it also deletes any temporary files.
78
 
 
79
 
(Note: I think it would be a good idea to separate these. Have a "rollback"
80
 
button which is seen as a large-scale undo button, which just reverts all
81
 
out-of-date files; that is reverts uncommitted changes to files in the repo,
82
 
and a "cleanup" button which deletes all temporary files; that is deletes any
83
 
files which have not been added).
84
 
 
85
 
(Another note: One thing which confuses *many* students, even 3rd and 4th
86
 
year, is the difference between "add" and "commit". Hopefully we can simplify
87
 
this so that the add button also commits? We need to decide if we want to
88
 
enforce atomicity - that is, if we expect students to avoid committing one
89
 
file at a time creating broken revisions - because things like the
90
 
"save-and-commit" button on the editor, and "add-and-commit" in the file
91
 
browser really discourage atomicity. I would argue for the best.)
92
 
 
93
 
Note that files could also be out-of-date if the Python program somehow
94
 
mangles them. In this case they should be reverted. Because of this, the
95
 
environment could portray out-of-date files as somehow "damaged".
96
 
 
97
 
A final note that the current "save" button in EditArea saves to the local
98
 
disk - ie. it is really a "download" button. Will need to modify this so
99
 
"save" just writes to the workspace, and have a separate download button
100
 
(possibly only through the file browser interface).
101
 
 
102
 
Multiple levels of expertise
103
 
----------------------------
104
 
 
105
 
We have identified at least two modes to place the interface (particularly,
106
 
the file browser) into when considering the expertise levels of the users.
107
 
 
108
 
We plan to have new students go into a "dumbed down" mode ("novice mode")
109
 
which will hide certain features and details, in particular the subversion
110
 
features.
111
 
 
112
 
Essentially the novice mode will give students the impression that this is
113
 
just a file system, with no revision control. There will be just a single
114
 
"save" button in the editor which will save to the student's workspace.
115
 
 
116
 
The "adept" mode by contrast will provide two save buttons - "save as draft"
117
 
(or save as temporary) and "save and commit". These behave as described above.
118
 
 
119
 
The question is, what does the novice mode "save" button do. It could either
120
 
write to the workspace only (effectively meaning students are without revision
121
 
control until they move into adept mode), or it could auto-commit each save.
122
 
If it autocommits we may or may not let the students in novice mode browse
123
 
their history (but if necessary, a lab demonstrator could go into adept mode
124
 
to retrieve old versions).
125
 
 
126
 
Autocommitting each save has advantages:
127
 
 
128
 
* Students can be helped to retrieve old versions if they mess up or lose
129
 
  their work.
130
 
* We can check their history when we mark projects.
131
 
 
132
 
Disadvantages:
133
 
 
134
 
* CPU drain from high volume of commits (see "unresolved issues" at the bottom).
135
 
* Possibly hard to explain once they move into adept mode that "save no longer
136
 
  saves your history unless you click save+commit" - which is why I'm calling
137
 
  it "save as draft" and having NO button called simply "save".
138
 
 
139
 
I have to say I am inclined to give even novice users both buttons. It isn't a
140
 
terribly difficult concept to distinguish between "I am just mucking around
141
 
with this file" and "I want to keep this".
142
 
 
143
 
Alternatively, if we do dumb it down, perhaps instead of committing each save,
144
 
we just save to their workspace and do automatic commits from the workspace
145
 
every so often (timewise, or number-of-saves-wise).
146
 
 
147
 
Use cases
148
 
---------
149
 
 
150
 
We have identified three levels of proficiency, which we will expect students
151
 
to progress through as they go through the course.
152
 
 
153
 
1. Novice user (students in their first or second week with no prior
154
 
    experience to revision control).
155
 
2. Familiar user (students who have grasped the concept of revision control
156
 
    and are expected to use the system as normal developers use revision
157
 
    control for single-developer projects).
158
 
3. Group user (students who are undertaking group work and need to use
159
 
    advanced multi-user features such as conflict-and-merge handling).
160
 
 
161
 
### Novice user ###
162
 
 
163
 
#### Use case: First hello world ####
164
 
 
165
 
Background: The student has used IVLE's tutorial section to write simple
166
 
Python programs and also played around in the console, but they haven't used
167
 
the file system yet. They presumably are proficient managing and editing normal
168
 
files and folders as in Windows at home, school, etc.
169
 
 
170
 
1. Student navigates to the "files" screen. They see an empty directory.
171
 
2. Student clicks "new file". They are immediately taken to the editor with an
172
 
    untitled file. (We do not ask for filenames until they save, as most GUI
173
 
    programs behave).
174
 
3. Student types in the Python "Hello world" program, and clicks "save".
175
 
    (Tempting to print a warning about temporary files but this will probably just
176
 
    confuse them at first).
177
 
4. A dialog box asks for the filename. They type in "hello.py". As with
178
 
    familiar GUI apps, they can always choose to "Save As" later.
179
 
5. Student can now "run" the program from within the editor. (They could have
180
 
    done this before they saved - we should be able to handle running code
181
 
    which the student has not saved).
182
 
6. Returning to the file browser, student sees "hello.py" with a "temporary
183
 
    file" icon next to it. At this stage this icon can be ignored but if the
184
 
    student enquires, a demonstrator explains that temporary files are SAVED
185
 
    but you can make permanent backups of files in case you mess them up by
186
 
    clicking "commit".
187
 
7. Student clicks "commit" and the temporary file icon goes away.
188
 
 
189
 
Note that apart from the commit issue, this whole usage example is supposed to
190
 
feel like what the students are used to with Windows applications such as file
191
 
Explorer and Microsoft Word, Notepad, etc. (Sorry to use Microsoft metaphors
192
 
but let's face it, that's what they know).
193
 
 
194
 
Students will call directories "folders". Do we need to explain that they are
195
 
the same thing? Should IVLE call them "folders"? Presumably the icons will
196
 
make this rather obvious!
197
 
 
198
 
#### Use case: Normal workflow, single-file programs ####
199
 
 
200
 
Background: For the first few weeks, students will be primarily editing
201
 
programs which are single-file Python programs, and will treat the file
202
 
browser as just a directory hierarchy with backup facilities. Assume the
203
 
student already has a Python file created as above, and it is a permanent file.
204
 
 
205
 
1. Student opens the file browser where their file is stored. They click
206
 
    "edit" and are taken to the editor screen.
207
 
2. Student edits the file, saving it frequently and running it. They are aware
208
 
    of the "temporary file" icon on the screen.
209
 
3. Student is happy that the changes they made are positive. They click "save
210
 
    and commit". For novice students, this simply removes the "temporary file"
211
 
    icon, and the student can sleep knowing they have a permanent backup to
212
 
    revert to.
213
 
4. Advanced students may have turned on the "ask for log messages" checkbox in
214
 
    their settings. When they click "save and commit", a dialog box appears
215
 
    which prompts for a log message. (This is a more advanced feature, after
216
 
    students realise the value of leaving themselves short notes for when they
217
 
    browse the history).
218
 
 
219
 
Note I am thinking of having a little icon space in the editor which shows
220
 
either:
221
 
 
222
 
* A "unsaved" icon if the user has made changes without saving (like how vim
223
 
  writes a "+" in the title bar).
224
 
* A "temporary file" icon if the user has saved it without committing.
225
 
* No icon if the user has just committed.
226
 
 
227
 
Unresolved issues
228
 
-----------------
229
 
 
230
 
### Disk quota ###
231
 
If we are keeping a repository, this means students completely
232
 
lack the ability to delete their permanent files (for the purpose of freeing
233
 
up space). This means that if students reach their quota, they can't fix it.
234
 
 
235
 
Solutions:
236
 
 
237
 
* Only put a quota on the head (do not penalise students for large files in
238
 
  repo). This could be abused.
239
 
* Allow students to request (through an admin) that a file is permanently
240
 
  historically erased from the repository.
241
 
 
242
 
### Novice mode CPU usage ###
243
 
 
244
 
In novice mode there will be signficantly more commits than adept mode because
245
 
of the commit each save policy (if we go down that road). Each commit takes up
246
 
a little bit of disk space (permanently), but also is problematic because it
247
 
takes awhile to commit and many students all using novice mode could overwhelm
248
 
the system.