Mercurial > p > roundup > code

comparison doc/upgrading.txt @ 1008:10ed4791f969

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Wrote most of the upgrading documentation (please read!) Removed the hard coded template path Removed unused config vars from instance_config
author Richard Jones <richard@users.sourceforge.net>
date Mon, 02 Sep 2002 07:46:55 +0000
parents f36ffa50374f
children fc55426544b5
comparison
equal deleted inserted replaced
1007:fec6af48558b 1008:10ed4791f969
8 .. contents:: 8 .. contents::
9 9
10 Migrating from 0.4.x to 0.5.0 10 Migrating from 0.4.x to 0.5.0
11 ============================= 11 =============================
12 12
13 This has been a fairly major revision of Roundup:
14
15 1. Brand new, much more powerful, flexible, tasty and nutritious templating.
16 Unfortunately, this means all your current templates are useless. Please
17 don't hesitate to ask on roundup-users for help (or complete conversions
18 if you're completely stuck)!
19 2. The database backed got a lot more flexible, allowing Metakit and SQL
20 databases! The only SQL database implemented at present is gadfly, but
21 others shouldn't be a whole lot more work.
22 3. A brand new, highly flexible and much more robust security system including
23 a system of Permissions, Roles and Role assignments to users. You may now
24 define your own Permissions that may be checked in CGI transactions.
25 4. Journalling has been made less storage-hungry, so has been turned on
26 by default *except* for author, recipient and nosy link/unlink events. You
27 are advised to turn it off in your instances too.
28 5. Because of the above changes, the instance configuration has seen some
29 major changes. See below for the details.
30
31 Please, *back up your database* before you start the migration process. This
32 is as simple as copying the "db" directory and all its contents from your
33 instance to somewhere safe.
34
35
13 0.5.0 Configuration 36 0.5.0 Configuration
14 ------------------- 37 -------------------
15 38
16 TODO: mention stuff about indexing 39 Due to the new templating having a top-level ``page`` that defines links for
17 TODO: mention that the dbinit needs the db.post_init() method call for 40 searching, indexes, adding items etc, the following variables are no longer
18 reindexing 41 used:
19 TODO: dbinit now imports classes from selct_db 42
20 TODO: select_db needs fixing to include Class, FileClass and IssueClass 43 - HEADER_INDEX_LINKS
21 TODO: migration of security settings 44 - HEADER_ADD_LINKS
22 TODO: nosy reactor has been updated 45 - HEADER_SEARCH_LINKS
23 TODO: user.item template html needs updating for new security 46 - SEARCH_FILTERS
24 TODO: maybe something about export/import? 47 - DEFAULT_INDEX
48 - UNASSIGNED_INDEX
49 - USER_INDEX
50 - ISSUE_FILTER
51
52 The new security implementation will require additions to the dbinit module,
53 but also removes the need for the following instance config variables:
54
55 - ANONYMOUS_ACCESS
56 - ANONYMOUS_REGISTER
57
58 but requires two new variables which define the Roles assigned to users who
59 register through the web and e-mail interfaces:
60
61 - NEW_WEB_USER_ROLES
62 - NEW_EMAIL_USER_ROLES
63
64 in both cases, 'User' is a good initial setting. To emulate
65 ``ANONYMOUS_ACCESS='deny'``, remove all "View" Permissions from the
66 "Anonymous" Role. To emulate ``ANONYMOUS_REGISTER='deny'``, remove the "Web
67 Registration" and/or the "Email Registration" Permission from the "Anonymous"
68 Role. See the section on customising security in the `customisation
69 documentation`_ for more information.
70
71
72 0.5.0 Schema Specification
73 --------------------------
74
75 0.5.0 Database backend changes
76 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77
78 Your select_db module in your instance has changed a fair bit. Where it used
79 to contain::
80
81 # WARNING: DO NOT EDIT THIS FILE!!!
82 from roundup.backends.back_anydbm import Database
83
84 it must now contain::
85
86 # WARNING: DO NOT EDIT THIS FILE!!!
87 from roundup.backends.back_anydbm import Database, Class, FileClass, IssueClass
88
89 Note the addition of the Class, FileClass, IssueClass imports. These are very
90 important, as they're going to make the next change work too. You now need to
91 modify the top of the dbinit module in your instance from::
92
93 import instance_config
94 from roundup import roundupdb
95 from select_db import Database
96
97 from roundup.roundupdb import Class, FileClass
98
99 class Database(roundupdb.Database, select_db.Database):
100 ''' Creates a hybrid database from:
101 . the selected database back-end from select_db
102 . the roundup extensions from roundupdb
103 '''
104 pass
105
106 class IssueClass(roundupdb.IssueClass):
107 ''' issues need the email information
108 '''
109 pass
110
111
112
113 to just::
114
115 import instance_config
116 from select_db import Database, Class, FileClass, IssueClass
117
118 Yes, remove the Database and IssueClass definitions and those other imports.
119 They're not needed any more!
120
121
122 0.5.0 Journalling changes
123 ~~~~~~~~~~~~~~~~~~~~~~~~~
124
125 Journalling has been optimised for storage. Journalling of links has been
126 turned back on by default. If your tracker has a large user base, you may wish
127 to turn off journalling of nosy list, message author and message recipient
128 link and unlink events. You do this by adding ``do_journal='no'`` to the Class
129 initialisation in your dbinit. For example, your *msg* class initialisation
130 probably looks like this::
131
132 msg = FileClass(db, "msg",
133 author=Link("user"), recipients=Multilink("user"),
134 date=Date(), summary=String(),
135 files=Multilink("file"),
136 messageid=String(), inreplyto=String())
137
138 to turn off journalling of author and recipient link events, add
139 ``do_journal='no'`` to the ``author=Link("user")`` part of the statement,
140 like so::
141
142 msg = FileClass(db, "msg",
143 author=Link("user", do_journal='no'),
144 recipients=Multilink("user", do_journal='no'),
145 date=Date(), summary=String(),
146 files=Multilink("file"),
147 messageid=String(), inreplyto=String())
148
149 Nosy list link event journalling is actually turned off by default now. If you
150 want to turn it onn, change to your issue class' nosy list, change its
151 definition from::
152
153 issue = IssueClass(db, "issue",
154 assignedto=Link("user"), topic=Multilink("keyword"),
155 priority=Link("priority"), status=Link("status"))
156
157 to::
158
159 issue = IssueClass(db, "issue", nosy=Multilink("user", do_journal='yes'),
160 assignedto=Link("user"), topic=Multilink("keyword"),
161 priority=Link("priority"), status=Link("status"))
162
163 noting that your definition of the nosy Multilink will override the normal one.
164
165 0.5.0 User schema changes
166 ~~~~~~~~~~~~~~~~~~~~~~~~~
167
168 Users have two more properties, "queries" and "roles". You'll have something
169 like this in your dbinit module now::
170
171 user = Class(db, "user",
172 username=String(), password=Password(),
173 address=String(), realname=String(),
174 phone=String(), organisation=String(),
175 alternate_addresses=String())
176 user.setkey("username")
177
178 and you'll need to add the new properties and the new "query" class to it
179 like so::
180
181 query = Class(db, "query",
182 klass=String(), name=String(),
183 url=String())
184 query.setkey("name")
185
186 # Note: roles is a comma-separated string of Role names
187 user = Class(db, "user",
188 username=String(), password=Password(),
189 address=String(), realname=String(),
190 phone=String(), organisation=String(),
191 alternate_addresses=String(),
192 queries=Multilink('query'), roles=String())
193 user.setkey("username")
194
195 The "queries" property is used to store off the user's favourite database
196 queries. The "roles" property is explained below in `0.5.0 Security
197 Settings`_.
198
199
200 0.5.0 Security Settings
201 ~~~~~~~~~~~~~~~~~~~~~~~
202
203 See the `security documentation`_ for an explanation of how the new security
204 system works. In a nutshell though, the security is handled as a four step
205 process:
206
207 1. Permissions are defined as having a name and optionally a hyperdb class
208 they're specific to,
209 2. Roles are defined that have one or more Permissions,
210 3. Users are assigned Roles in their "roles" property, and finally
211 4. Roundup checks that users have appropriate Permissions at appropriate times
212 (like editing issues).
213
214 Your instance dbinit module's *open* function now has to define any
215 Permissions that are specific to your instance, and also the assignment
216 of Permissions to Roles. At the moment, your open function
217 ends with::
218
219 import detectors
220 detectors.init(db)
221
222 return db
223
224 and what we need to do is insert some commands that will set up the security
225 parameters. Right above the ``import detectors`` line, you'll want to insert
226 these lines::
227
228 #
229 # SECURITY SETTINGS
230 #
231 # new permissions for this schema
232 for cl in 'issue', 'file', 'msg', 'user':
233 db.security.addPermission(name="Edit", klass=cl,
234 description="User is allowed to edit "+cl)
235 db.security.addPermission(name="View", klass=cl,
236 description="User is allowed to access "+cl)
237
238 # Assign the access and edit permissions for issue, file and message
239 # to regular users now
240 for cl in 'issue', 'file', 'msg':
241 p = db.security.getPermission('View', cl)
242 db.security.addPermissionToRole('User', p)
243 p = db.security.getPermission('Edit', cl)
244 db.security.addPermissionToRole('User', p)
245 # and give the regular users access to the web and email interface
246 p = db.security.getPermission('Web Access')
247 db.security.addPermissionToRole('User', p)
248 p = db.security.getPermission('Email Access')
249 db.security.addPermissionToRole('User', p)
250
251 # May users view other user information? Comment these lines out
252 # if you don't want them to
253 p = db.security.getPermission('View', 'user')
254 db.security.addPermissionToRole('User', p)
255
256 # Assign the appropriate permissions to the anonymous user's Anonymous
257 # Role. Choices here are:
258 # - Allow anonymous users to register through the web
259 p = db.security.getPermission('Web Registration')
260 db.security.addPermissionToRole('Anonymous', p)
261 # - Allow anonymous (new) users to register through the email gateway
262 p = db.security.getPermission('Email Registration')
263 db.security.addPermissionToRole('Anonymous', p)
264 # - Allow anonymous users access to the "issue" class of data
265 # Note: this also grants access to related information like files,
266 # messages, statuses etc that are linked to issues
267 #p = db.security.getPermission('View', 'issue')
268 #db.security.addPermissionToRole('Anonymous', p)
269 # - Allow anonymous users access to edit the "issue" class of data
270 # Note: this also grants access to create related information like
271 # files and messages etc that are linked to issues
272 #p = db.security.getPermission('Edit', 'issue')
273 #db.security.addPermissionToRole('Anonymous', p)
274
275 # oh, g'wan, let anonymous access the web interface too
276 p = db.security.getPermission('Web Access')
277 db.security.addPermissionToRole('Anonymous', p)
278
279 Note in the comments there the places where you might change the permissions
280 to restrict users or grant users more access. If you've created additional
281 classes that users should be able to edit and view, then you should add them
282 to the "new permissions for this schema" section at the start of the security
283 block. Then add them to the "Assign the access and edit permissions" section
284 too, so people actually have the new Permission you've created.
285
286 One final change is needed that finishes off the security system's
287 initialisation. We need to add a call to ``db.post_init()`` at the end of the
288 dbinit open() function. Add it like this::
289
290 import detectors
291 detectors.init(db)
292
293 # schema is set up - run any post-initialisation
294 db.post_init()
295 return db
296
297 You may verify the setup of Permissions and Roles using the new
298 "``roundup-admin security``" command.
299
300
301 0.5.0 CGI interface changes
302 ---------------------------
303
304 The CGI interface code was completely reorganised and largely rewritten. The
305 end result is that this section of your instance interfaces module will need
306 changing from::
307
308 from roundup import mailgw
309 from roundup.cgi import client
310
311 class Client(client.Client):
312 ''' derives basic CGI implementation from the standard module,
313 with any specific extensions
314 '''
315 pass
316
317 to::
318
319 from roundup import cgi_client, mailgw
320 from roundup.i18n import _
321
322 class Client(cgi_client.Client):
323 ''' derives basic CGI implementation from the standard module,
324 with any specific extensions
325 '''
326 pass
327
328 0.5.0 HTML templating
329 ---------------------
330
331 You'll want to make a backup of your current instance html directory. You
332 should then copy the html directory from the Roundup source template that you
333 used to create your instance, and modify it according to your local schema
334 changes.
335
336 If you need help with the new templating system, please ask questions on the
337 roundup-users mailing list (available through the roundup project page on
338 sourceforge, http://roundup.sf.net/)
339
340
341 0.5.0 Detectors
342 ---------------
343
344 The nosy reactor has been updated to handle the instance not having an
345 "assignedto" property on issues. You may want to copy it into your instance's
346 detectors directory. Chances are you've already fixed it though :)
25 347
26 348
27 Migrating from 0.4.1 to 0.4.2 349 Migrating from 0.4.1 to 0.4.2
28 ============================= 350 =============================
29 351
46 368
47 and:: 369 and::
48 370
49 <roundup source>/roundup/templates/extended/instance_config.py 371 <roundup source>/roundup/templates/extended/instance_config.py
50 372
51 and the documentation in customizing_ for information on how they're used. 373 and the `customisation documentation`_ for information on how they're used.
52 374
53 375
54 0.4.2 Changes to detectors 376 0.4.2 Changes to detectors
55 -------------------------- 377 --------------------------
56 You will need to copy the detectors from the distribution into your instance 378 You will need to copy the detectors from the distribution into your instance
343 need to install it again from the cgi-bin directory of the source 665 need to install it again from the cgi-bin directory of the source
344 distribution. Make sure you update the ROUNDUP_INSTANCE_HOMES after the 666 distribution. Make sure you update the ROUNDUP_INSTANCE_HOMES after the
345 copy. 667 copy.
346 668
347 669
348 .. _customizing: customizing.html 670 .. _`customisation documentation`: customizing.html
671 .. _`security documentation`: security.html
Roundup Issue Tracker: http://roundup-tracker.org/