From 6fa5c6eccf660b60ff65e5b46e0c66968b19351c Mon Sep 17 00:00:00 2001
From: "gerv%gerv.net" <>
Date: Thu, 19 Sep 2002 06:23:52 +0000
Subject: Bug 168804 - Document CheckCanChangeField so sites can modify it for
local needs. Patch by gerv; r=bbaetz, joel.
---
docs/sgml/administration.sgml | 94 +++++++++++++++++++++++++++++++++++++++++++
docs/xml/administration.xml | 94 +++++++++++++++++++++++++++++++++++++++++++
2 files changed, 188 insertions(+)
(limited to 'docs')
diff --git a/docs/sgml/administration.sgml b/docs/sgml/administration.sgml
index f932beb25..a82a659bf 100644
--- a/docs/sgml/administration.sgml
+++ b/docs/sgml/administration.sgml
@@ -1176,6 +1176,100 @@
+
+ Change Permission Customisation
+
+
+
+ This feature should be considered experimental; the Bugzilla code you
+ will be changing is not stable, and could change or move between
+ versions. Be aware that if you make modifications to it, you may have
+ to re-make them or port them if Bugzilla changes internally between
+ versions.
+
+
+
+
+ Companies often have rules about which employees, or classes of employees,
+ are allowed to change certain things in the bug system. For example,
+ only the bug's designated QA Contact may be allowed to VERIFY the bug.
+ Bugzilla has been
+ designed to make it easy for you to write your own custom rules to define
+ who is allowed to make what sorts of value transition.
+
+
+
+ For maximum flexibility, customising this means editing Bugzilla's Perl
+ code. This gives the administrator complete control over exactly who is
+ allowed to do what. The relevant function is called
+ CheckCanChangeField(),
+ and is found in process_bug.cgi in your
+ Bugzilla directory. If you open that file and grep for
+ "sub CheckCanChangeField", you'll find it.
+
+
+
+ This function has been carefully commented to allow you to see exactly
+ how it works, and give you an idea of how to make changes to it. Certain
+ marked sections should not be changed - these are the "plumbing" which
+ makes the rest of the function work. In between those sections, you'll
+ find snippets of code like:
+ # Allow the owner to change anything.
+ if ($ownerid eq $whoid) {
+ return 1;
+ }
+ It's fairly obvious what this piece of code does.
+
+
+
+ So, how does one go about changing this function? Well, simple changes
+ can be made just be removing pieces - for example, if you wanted to
+ prevent any user adding a comment to a bug, just remove the lines marked
+ "Allow anyone to change comments." And if you want the reporter to have
+ no special rights on bugs they have filed, just remove the entire section
+ which refers to him.
+
+
+
+ More complex customisations are not much harder. Basically, you add
+ a check in the right place in the function, i.e. after all the variables
+ you are using have been set up. So, don't look at $ownerid before
+ $ownerid has been obtained from the database. You can either add a
+ positive check, which returns 1 (allow) if certain conditions are true,
+ or a negative check, which returns 0 (deny.) E.g.:
+ if ($field eq "qacontact") {
+ if (UserInGroup("quality_assurance")) {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }
+ This says that only users in the group "quality_assurance" can change
+ the QA Contact field of a bug. Getting more weird:
+ if (($field eq "priority") &&
+ ($vars->{'user'}{'login'} =~ /.*\@example\.com$/))
+ {
+ if ($oldvalue eq "P1") {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }
+ This says that if the user is trying to change the priority field,
+ and their email address is @example.com, they can only do so if the
+ old value of the field was "P1". Not very useful, but illustrative.
+
+
+
+ For a list of possible field names, look in
+ data/versioncache for the list called
+ @::log_columns. If you need help writing custom
+ rules for your organisation, ask in the newsgroup.
+
+
+
Upgrading to New Releases
diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml
index f932beb25..a82a659bf 100644
--- a/docs/xml/administration.xml
+++ b/docs/xml/administration.xml
@@ -1176,6 +1176,100 @@
+
+ Change Permission Customisation
+
+
+
+ This feature should be considered experimental; the Bugzilla code you
+ will be changing is not stable, and could change or move between
+ versions. Be aware that if you make modifications to it, you may have
+ to re-make them or port them if Bugzilla changes internally between
+ versions.
+
+
+
+
+ Companies often have rules about which employees, or classes of employees,
+ are allowed to change certain things in the bug system. For example,
+ only the bug's designated QA Contact may be allowed to VERIFY the bug.
+ Bugzilla has been
+ designed to make it easy for you to write your own custom rules to define
+ who is allowed to make what sorts of value transition.
+
+
+
+ For maximum flexibility, customising this means editing Bugzilla's Perl
+ code. This gives the administrator complete control over exactly who is
+ allowed to do what. The relevant function is called
+ CheckCanChangeField(),
+ and is found in process_bug.cgi in your
+ Bugzilla directory. If you open that file and grep for
+ "sub CheckCanChangeField", you'll find it.
+
+
+
+ This function has been carefully commented to allow you to see exactly
+ how it works, and give you an idea of how to make changes to it. Certain
+ marked sections should not be changed - these are the "plumbing" which
+ makes the rest of the function work. In between those sections, you'll
+ find snippets of code like:
+ # Allow the owner to change anything.
+ if ($ownerid eq $whoid) {
+ return 1;
+ }
+ It's fairly obvious what this piece of code does.
+
+
+
+ So, how does one go about changing this function? Well, simple changes
+ can be made just be removing pieces - for example, if you wanted to
+ prevent any user adding a comment to a bug, just remove the lines marked
+ "Allow anyone to change comments." And if you want the reporter to have
+ no special rights on bugs they have filed, just remove the entire section
+ which refers to him.
+
+
+
+ More complex customisations are not much harder. Basically, you add
+ a check in the right place in the function, i.e. after all the variables
+ you are using have been set up. So, don't look at $ownerid before
+ $ownerid has been obtained from the database. You can either add a
+ positive check, which returns 1 (allow) if certain conditions are true,
+ or a negative check, which returns 0 (deny.) E.g.:
+ if ($field eq "qacontact") {
+ if (UserInGroup("quality_assurance")) {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }
+ This says that only users in the group "quality_assurance" can change
+ the QA Contact field of a bug. Getting more weird:
+ if (($field eq "priority") &&
+ ($vars->{'user'}{'login'} =~ /.*\@example\.com$/))
+ {
+ if ($oldvalue eq "P1") {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }
+ This says that if the user is trying to change the priority field,
+ and their email address is @example.com, they can only do so if the
+ old value of the field was "P1". Not very useful, but illustrative.
+
+
+
+ For a list of possible field names, look in
+ data/versioncache for the list called
+ @::log_columns. If you need help writing custom
+ rules for your organisation, ask in the newsgroup.
+
+
+
Upgrading to New Releases
--
cgit v1.2.3-24-g4f1b