Bug 180870 - Remove old shadowdb manual replication code

r, a=myk

2 files changed, 151 insertions, 68 deletions

diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml
index f932beb25..847527203 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
@@ -69,8 +69,14 @@
         write locking. What this means is that if someone needs to make a
         change to a bug, they will lock the entire table until the operation
         is complete. Locking for write also blocks reads until the write is
-        complete. The 
-        <quote>shadowdb</quote>
+        complete. Note that more recent versions of mysql support row level
+        locking using different table types. These types are slower than the
+        standard type, and Bugzilla does not yet take advantage of features
+        such as transactions which would justify this speed decrease. The
+        Bugzilla team are, however, happy to hear about any experiences with
+        row level locking and Bugzilla</para>
+
+        <para>The <quote>shadowdb</quote>
         parameter was designed to get around this limitation. While only a
         single user is allowed to write to a table at a time, reads can
         continue unimpeded on a read-only shadow copy of the database.
@@ -85,23 +91,10 @@
         Bugzilla bug changes and comments per day.</para>
 
         <para>The value of the parameter defines the name of the 
-        shadow bug database. 
-        Set "shadowdb" to e.g. "bug_shadowdb" if you will be running a
-        *very* large installation of Bugzilla. 
-        <note>
-          <para>Enabling "shadowdb" can adversely affect the stability of
-          your installation of Bugzilla. You should regularly check that your
-          database is in sync. It is often advisable to force a shadow
-          database sync nightly via 
-          <quote>cron</quote>.
-          </para>
-        </note>
-        </para>
-        
-        <para>If you use the "shadowdb" option, it is only natural that you
-        should turn the "queryagainstshadowdb" option on as well. Otherwise
-        you are replicating data into a shadow database for no reason!</para>
-
+        shadow bug database. You will need to set the host and port settings
+        from the params page, and set up replication in your database server
+        so that updates reach this readonly mirror. Consult your database
+        documentation for more detail.</para>
       </step>
 
       <step>
@@ -129,6 +122,19 @@
         blurb about how to use Bugzilla at your site.</para>
       </step>
 
+
+      <step>
+        <para>
+	<command>movebugs</command>:
+
+	This option is an undocumented feature to allow moving bugs
+	between separate Bugzilla installations.  You will need to understand
+	the source code in order to use this feature.  Please consult
+	<filename>movebugs.pl</filename> in your Bugzilla source tree for
+	further documentation, such as it is.
+	</para>
+      </step>
+
       <step>
         <para>
         <command>useqacontact</command>:
@@ -212,33 +218,11 @@
       you for this username and password.</para>
 
       <tip>
-        <para>If you wish to add more administrative users, you must use the
-        MySQL interface. Run "mysql" from the command line, and use these
-        commands: 
-        <simplelist>
-          <member>
-            <prompt>mysql&gt;</prompt>
-            <command>use bugs;</command>
-          </member>
-
-          <member>
-            <prompt>mysql&gt;</prompt>
-
-            <command>
-              update profiles set groupset=0x7ffffffffffffff where login_name =
-              "(user's login name)";
-            </command>
-          </member>
-        </simplelist>
+        <para>If you wish to add more administrative users, add them to 
+        the "admin" group and, optionally, add edit the tweakparams, editusers,
+        creategroups, editcomponents, and editkeywords groups to add the
+        entire admin group to those groups.
         </para>
-
-        <para>Yes, that is 
-        <emphasis>fourteen</emphasis>
-
-        <quote>f</quote>
-
-        's. A whole lot of f-ing going on if you want to create a new
-        administator.</para>
       </tip>
     </section>
 
@@ -698,10 +682,22 @@
       </listitem>
 
       <listitem>
-        <para>Fill out the "New Name", "New Description", and 
-        "New User RegExp" fields. "New User RegExp" allows you to automatically
+        <para>Fill out the "Group", "Description", and 
+        "User RegExp" fields. "New User RegExp" allows you to automatically
          place all users who fulfill the Regular Expression into the new group. 
          When you have finished, click "Add".</para>
+         <warning>
+           <para>The User Regexp is a perl regexp and, if not anchored, will match 
+           any part of an address.  So, if you do not want to grant access
+           into 'mycompany.com' to 'badperson@mycompany.com.hacker.net', use 
+           '@mycompany\.com$' as the regexp.</para>
+         </warning>
+      </listitem>
+      <listitem>
+        <para>After you add your new group, edit the new group.  On the
+        edit page, you can specify other groups that should be included
+        in this group and which groups should be permitted to add and delete
+        users from this group.</para>
       </listitem>
     </orderedlist>
 
@@ -712,17 +708,6 @@
         <para>Turn on "usebuggroups" and "usebuggroupsentry" in the "Edit
         Parameters" screen.</para>
 
-        <warning>
-          <para>XXX is this still true?
-          "usebuggroupsentry" has the capacity to prevent the
-          administrative user from directly altering bugs because of
-          conflicting group permissions. If you plan on using
-          "usebuggroupsentry", you should plan on restricting
-          administrative account usage to administrative duties only. In
-          other words, manage bugs with an unpriveleged user account, and
-          manage users, groups, Products, etc. with the administrative
-          account.</para>
-        </warning>
       </listitem>
 
       <listitem>
@@ -734,13 +719,6 @@
       </listitem>
     </orderedlist>
 
-    <warning>
-      <para>Bugzilla currently has a limit of 64 groups per installation. If
-      you have more than about 50 products, you should consider
-      running multiple Bugzillas. Ask in the newsgroup for other
-      suggestions for working around this restriction.</para>
-    </warning>
-
     <para>
       Note that group permissions are such that you need to be a member
       of <emphasis>all</emphasis> the groups a bug is in, for whatever
@@ -1128,6 +1106,19 @@
         By modifying this, you can tell your users how they should report
         bugs.
       </para>
+
+      <para>
+        <command>bug/process/midair.html.tmpl</command>:
+        This is the page used if two people submit simultaneous changes to the
+        same bug.  The second person to submit their changes will get this page
+        to tell them what the first person did, and ask if they wish to
+        overwrite those changes or go back and revisit the bug.  The default
+        title and header on this page read "Mid-air collision detected!"  If
+        you work in the aviation industry, or other environment where this
+        might be found offensive (yes, we have true stories of this happening)
+        you'll want to change this to something more appropriate for your
+        environment.
+      </para>
         
       <para>
         <command>bug/create/create.html.tmpl</command> and
@@ -1176,6 +1167,100 @@
     
   </section>
 
+  <section id="cust-change-permissions">
+    <title>Change Permission Customisation</title>
+    
+    <warning>
+      <para>
+        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.
+      </para>
+    </warning>
+       
+    <para>
+      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.
+    </para>
+    
+    <para>
+      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 
+      <filename>CheckCanChangeField()</filename>,
+      and is found in <filename>process_bug.cgi</filename> in your 
+      Bugzilla directory. If you open that file and grep for 
+      "sub CheckCanChangeField", you'll find it.
+    </para>
+    
+    <para>
+      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:
+      <programlisting>    # Allow the owner to change anything.
+    if ($ownerid eq $whoid) {
+        return 1;
+    }</programlisting>
+      It's fairly obvious what this piece of code does.
+    </para>      
+      
+    <para>
+      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.
+    </para>
+    
+    <para>
+      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.:
+      <programlisting>    if ($field eq "qacontact") {
+        if (UserInGroup("quality_assurance")) {
+            return 1;
+        } 
+        else {
+            return 0;
+        }
+    }</programlisting>
+      This says that only users in the group "quality_assurance" can change
+      the QA Contact field of a bug. Getting more weird:
+      <programlisting>    if (($field eq "priority") &&
+        ($vars->{'user'}{'login'} =~ /.*\@example\.com$/))
+    {
+        if ($oldvalue eq "P1") {
+            return 1;
+        } 
+        else {
+            return 0;
+        }
+    }</programlisting>
+      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.
+    </para>
+    
+    <para>
+      For a list of possible field names, look in 
+      <filename>data/versioncache</filename> for the list called 
+      <filename>@::log_columns</filename>. If you need help writing custom
+      rules for your organisation, ask in the newsgroup.
+    </para>    
+  </section>   
+  
   <section id="upgrading">
     <title>Upgrading to New Releases</title>
 
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml
index 8d1a94ec7..7aec021ce 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -559,9 +559,7 @@ AllowOverride Limit
         <para>There are important files and directories that should not be a
         served by the HTTP server - most files in the 
         <quote>data</quote>
-        and 
-        <quote>shadow</quote>
-        directories and the 
+        directory and the 
         <quote>localconfig</quote>
         file. You should configure your HTTP server to not serve 
         these files. Failure to do so will expose critical passwords and