| Time Log @@ -3096,8 +3097,8 @@ displayed in the template as text like "+ 1y 2:40" (1 year, 2 hours and 40 minutes). -8. If you're using a persistent web server - roundup-server or - mod_python for example - then you'll need to restart that to pick up +8. If you're using a persistent web server - ``roundup-server`` or + ``mod_python`` for example - then you'll need to restart that to pick up the code changes. When that's done, you'll be able to use the new time logging interface. @@ -3116,27 +3117,27 @@ 2. Add the new issue class to your tracker's ``schema.py`` - in this example, we're adding a "system support" class. Just after the "issue" - class definition in the "open" function, add:: + class definition, add:: support = IssueClass(db, "support", assignedto=Link("user"), topic=Multilink("keyword"), status=Link("status"), deadline=Date(), affects=Multilink("system")) -3. Copy the existing "issue.*" (item, search and index) templates in the - tracker's "html" to "support.*". Edit them so they use the properties - defined in the "support" class. Be sure to check for hidden form +3. Copy the existing ``issue.*`` (item, search and index) templates in the + tracker's ``html`` to ``support.*``. Edit them so they use the properties + defined in the ``support`` class. Be sure to check for hidden form variables like "required" to make sure they have the correct set of required properties. -4. Edit the modules in the "detectors", adding lines to their "init" - functions where appropriate. Look for "audit" and "react" registrations - on the "issue" class, and duplicate them for "support". +4. Edit the modules in the ``detectors``, adding lines to their ``init`` + functions where appropriate. Look for ``audit`` and ``react`` registrations + on the ``issue`` class, and duplicate them for ``support``. 5. Create a new sidebar box for the new support class. Duplicate the - existing issues one, changing the "issue" class name to "support". + existing issues one, changing the ``issue`` class name to ``support``. -6. Re-start your tracker and start using the new "support" class. +6. Re-start your tracker and start using the new ``support`` class. Optionally, you might want to restrict the users able to access this new @@ -3151,7 +3152,7 @@ users, and add "SysAdmin" to their Roles list. Alternatively, you might want to change the Edit/View permissions granted -for the "issue" class so that it's only available to users with the "System" +for the ``issue`` class so that it's only available to users with the "System" or "Developer" Role, and then the new class you're adding is available to all with the "User" Role. @@ -3175,7 +3176,7 @@ database - we just use the passwd file to check their password. To do this, we need to override the standard ``verifyPassword`` method defined in ``roundup.cgi.actions.LoginAction`` and register the new class. The -following is added as ``externapassword.py`` in the tracker ``extensions`` +following is added as ``externalpassword.py`` in the tracker ``extensions`` directory:: from roundup.cgi.actions import LoginAction @@ -3224,7 +3225,7 @@ To make use of the passwd file, we therefore synchronise between the two user stores. We also use the passwd file to validate the user logins, as described in the previous example, `using an external password -validation source`_. We keep the users lists in sync using a fairly +validation source`_. We keep the user lists in sync using a fairly simple script that runs once a day, or several times an hour if more immediate access is needed. In short, it: @@ -3239,7 +3240,7 @@ The retiring and updating are simple operations, requiring only a call to ``retire()`` or ``set()``. The creation operation requires more -information though - the user's email address and their roundup Roles. +information though - the user's email address and their Roundup Roles. We're going to assume that the user's email address is the same as their login name, so we just append the domain name to that. The Roles are determined using the passwd group identifier - mapping their UN*X group @@ -3355,11 +3356,11 @@ for more information about doing this. To authenticate off the LDAP store (rather than using the passwords in the -roundup user database) you'd use the same python-ldap module inside an +Roundup user database) you'd use the same python-ldap module inside an extension to the cgi interface. You'd do this by overriding the method called -"verifyPassword" on the LoginAction class in your tracker's interfaces.py -module (see `using an external password validation source`_). The method is -implemented by default as:: +``verifyPassword`` on the ``LoginAction`` class in your tracker's +``extensions`` directory (see `using an external password validation +source`_). The method is implemented by default as:: def verifyPassword(self, userid, password): ''' Verify the password that the user has supplied @@ -3484,8 +3485,8 @@ Adding in state transition control ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sometimes tracker admins want to control the states that users may move -issues to. You can do this by following these steps: +Sometimes tracker admins want to control the states to which users may +move issues. You can do this by following these steps: 1. make "status" a required variable. This is achieved by adding the following to the top of the form in the ``issue.item.html`` @@ -3493,7 +3494,7 @@ - this will force users to select a status. + This will force users to select a status. 2. add a Multilink property to the status class:: @@ -3503,7 +3504,7 @@ and then edit the statuses already created, either: a. through the web using the class list -> status class editor, or - b. using the roundup-admin "set" command. + b. using the ``roundup-admin`` "set" command. 3. add an auditor module ``checktransition.py`` in your tracker's ``detectors`` directory, for example:: @@ -3560,23 +3561,23 @@ they can't be resolved until another issue (the blocker) they rely on is resolved. To achieve this: -1. Create a new property on the issue Class, - ``blockers=Multilink("issue")``. Edit your tracker's schema.py file. - Where the "issue" class is defined, something like:: +1. Create a new property on the ``issue`` class: + ``blockers=Multilink("issue")``. To do this, edit the definition of + this class in your tracker's ``schema.py`` file. Change this:: issue = IssueClass(db, "issue", assignedto=Link("user"), topic=Multilink("keyword"), priority=Link("priority"), status=Link("status")) - add the blockers entry like so:: + to this, adding the blockers entry:: issue = IssueClass(db, "issue", blockers=Multilink("issue"), assignedto=Link("user"), topic=Multilink("keyword"), priority=Link("priority"), status=Link("status")) -2. Add the new "blockers" property to the issue.item edit page, using - something like:: +2. Add the new ``blockers`` property to the ``issue.item.html`` edit + page, using something like:: | Waiting On |
@@ -3594,7 +3595,7 @@
Just make sure it appears in the first table, possibly somewhere near
the "superseders" field.
-3. Create a new detector module (attached) which enforces the rules:
+3. Create a new detector module (see below) which enforces the rules:
- issues may not be resolved if they have blockers
- when a blocker is resolved, it's removed from issues it blocks
@@ -3672,15 +3673,15 @@
example, the existing "Show All" link in the "page" template (in the
tracker's "html" directory) looks like this::
- Show All modify it to add the "blockers" info to the URL (note, both the - ":filter" *and* "blockers" values must be specified):: + "@filter" *and* "blockers" values must be specified)@@ - Show All The above examples are line-wrapped on the trailing & and should @@ -3695,27 +3696,27 @@ Add users to the nosy list based on the topic ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -We need the ability to automatically add users to the nosy list based -on the occurence of a topic. Every user should be allowed to edit his -own list of topics for which he wants to be added to the nosy list. - -Below will be showed that such a change can be performed with only -minimal understanding of the roundup system, but with clever use -of Copy and Paste. +Let's say we need the ability to automatically add users to the nosy +list based +on the occurance of a topic. Every user should be allowed to edit their +own list of topics for which they want to be added to the nosy list. + +Below, we'll show that this change can be done with minimal +understanding of the Roundup system, using only copy and paste. This requires three changes to the tracker: a change in the database to allow per-user recording of the lists of topics for which he wants to -be put on the nosy list, a change in the user view allowing to edit +be put on the nosy list, a change in the user view allowing them to edit this list of topics, and addition of an auditor which updates the nosy list when a topic is set. Adding the nosy topic list :::::::::::::::::::::::::: -The change in the database to make is that for any user there should be +The change to make in the database, is that for any user there should be a list of topics for which he wants to be put on the nosy list. Adding -a ``Multilink`` of ``keyword`` seem to fullfill this (note that within -the code topics are called ``keywords``.) As such, all what has to be +a ``Multilink`` of ``keyword`` seems to fullfill this (note that within +the code, topics are called ``keywords``.) As such, all that has to be done is to add a new field to the definition of ``user`` within the file ``schema.py``. We will call this new field ``nosy_keywords``, and the updated definition of user will be:: @@ -3735,10 +3736,10 @@ We want any user to be able to change the list of topics for which he will by default be added to the nosy list. We choose to add this to the user view, as is generated by the file ``html/user.item.html``. -We easily can -see that the topic field in the issue view has very similar editting -requirements as our nosy topics, both being a list of topics. As -such, we search for Topics in ``issue.item.html``, and extract the +We can easily +see that the topic field in the issue view has very similar editing +requirements as our nosy topics, both being lists of topics. As +such, we look for Topics in ``issue.item.html``, and extract the associated parts from there. We add this to ``user.item.html`` at the bottom of the list of viewed items (i.e. just below the 'Alternate E-mail addresses' in the classic template):: @@ -3755,36 +3756,36 @@ Addition of an auditor to update the nosy list :::::::::::::::::::::::::::::::::::::::::::::: -The more difficult part is the addition of the logic to actually -at the users to the nosy list when it is required. -The choice is made to perform this action when the topics on an -item are set, including when an item is created. +The more difficult part is the logic to add +the users to the nosy list when required. +We choose to perform this action whenever the topics on an +item are set (this includes the creation of items). Here we choose to start out with a copy of the ``detectors/nosyreaction.py`` detector, which we copy to the file ``detectors/nosy_keyword_reaction.py``. This looks like a good start as it also adds users to the nosy list. A look through the code reveals that the -``nosyreaction`` function actually is sending the e-mail, which -we do not need. As such, we can change the init function to:: +``nosyreaction`` function actually sends the e-mail. +We don't need this. Therefore, we can change the ``init`` function to:: def init(db): db.issue.audit('create', update_kw_nosy) db.issue.audit('set', update_kw_nosy) -After that we rename the ``updatenosy`` function to ``update_kw_nosy``. -The first two blocks of code in that function relate to settings +After that, we rename the ``updatenosy`` function to ``update_kw_nosy``. +The first two blocks of code in that function relate to setting ``current`` to a combination of the old and new nosy lists. This functionality is left in the new auditor. The following block of -code, which in ``updatenosy`` handled adding the assignedto user(s) -to the nosy list, should be replaced by a block of code to add the +code, which handled adding the assignedto user(s) to the nosy list in +``updatenosy``, should be replaced by a block of code to add the interested users to the nosy list. We choose here to loop over all -new topics, than loop over all users, -and assign the user to the nosy list when the topic in the user's -nosy_keywords. The next part in ``updatenosy``, adding the author -and/or recipients of a message to the nosy list, obviously is not -relevant here and thus is deleted from the new auditor. The last -part, copying the new nosy list to newvalues, does not have to be changed. -This brings the following function:: +new topics, than looping over all users, +and assign the user to the nosy list when the topic occurs in the user's +``nosy_keywords``. The next part in ``updatenosy`` -- adding the author +and/or recipients of a message to the nosy list -- is obviously not +relevant here and is thus deleted from the new auditor. The last +part, copying the new nosy list to ``newvalues``, can stay as is. +This results in the following function:: def update_kw_nosy(db, cl, nodeid, newvalues): '''Update the nosy list for changes to the topics @@ -3830,9 +3831,9 @@ # that's it, save off the new nosy list newvalues['nosy'] = current.keys() -and these two function are the only ones needed in the file. +These two function are the only ones needed in the file. -TODO: update this example to use the find() Class method. +TODO: update this example to use the ``find()`` Class method. Caveats ::::::: @@ -3841,22 +3842,22 @@ Multiple additions When a user, after automatic selection, is manually removed - from the nosy list, he again is added to the nosy list when the + from the nosy list, he is added to the nosy list again when the topic list of the issue is updated. A better design might be to only check which topics are new compared to the old list of topics, and only add users when they have indicated interest on a new topic. - The code could also be changed to only trigger on the create() event, - rather than also on the set() event, thus only setting the nosy list - when the issue is created. + The code could also be changed to only trigger on the ``create()`` + event, rather than also on the ``set()`` event, thus only setting + the nosy list when the issue is created. Scalability - In the auditor there is a loop over all users. For a site with - only few users this will pose no serious problem, however, with + In the auditor, there is a loop over all users. For a site with + only few users this will pose no serious problem; however, with many users this will be a serious performance bottleneck. - A way out will be to link from the topics to the users which - selected these topics a nosy topics. This will eliminate the + A way out would be to link from the topics to the users who + selected these topics as nosy topics. This will eliminate the loop over all users. Changes to Security and Permissions @@ -3879,7 +3880,7 @@ db.security.addPermissionToRole('Developer', p) -4. In the issue item edit page ("html/issue.item.html" in your tracker +4. In the issue item edit page (``html/issue.item.html`` in your tracker directory), use the new Permission in restricting the "assignedto" list:: @@ -3896,11 +3897,11 @@ For extra security, you may wish to setup an auditor to enforce the -Permission requirement (install this as "assignedtoFixer.py" in your -tracker "detectors" directory):: +Permission requirement (install this as ``assignedtoFixer.py`` in your +tracker ``detectors`` directory):: def assignedtoMustBeFixer(db, cl, nodeid, newvalues): - ''' Ensure the assignedto value in newvalues is a used with the + ''' Ensure the assignedto value in newvalues is used with the Fixer Permission ''' if not newvalues.has_key('assignedto'): @@ -3922,7 +3923,8 @@ Users may only edit their issues ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Users registering themselves are granted Provisional access - meaning they +In this case, users registering themselves are granted Provisional +access, meaning they have access to edit the issues they submit, but not others. We create a new Role called "Provisional User" which is granted to newly-registered users, and has limited access. One of the Permissions they have is the new "Edit @@ -3962,7 +3964,7 @@ db.security.addPermissionToRole('Provisional User', 'Email Access') -Then in the ``config.ini`` we change the Role assigned to newly-registered +Then, in ``config.ini``, we change the Role assigned to newly-registered users, replacing the existing ``'User'`` values:: [main] @@ -3970,8 +3972,8 @@ new_web_user_roles = 'Provisional User' new_email_user_roles = 'Provisional User' -Note that some older trackers might also want to change the ``page.html`` -template as follows:: +Note that some older trackers might also require the ``page.html`` +template to be changed as follows:: @@ -3990,7 +3992,7 @@ Adding action links to the index page ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Add a column to the item.index.html template. +Add a column to the ``item.index.html`` template. Resolving the issue:: @@ -4002,19 +4004,19 @@ take -... and so on +... and so on. Colouring the rows in the issue index according to priority ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A simple ``tal:attributes`` statement will do the bulk of the work here. In -the ``issue.index.html`` template, add to the `` | ||
|---|---|---|---|---|