~azzar1/unity/add-show-desktop-key : revision 8

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.