Bug 252272: Allow extremely large attachments to be stored locally

Patch by A. Karl Kornel <karl@kornel.name>, r=joel,colin

2 files changed, 563 insertions, 28 deletions

diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml
index 1b711ed39..65828412f 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -1,5 +1,5 @@
 <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.99 2008/04/04 06:47:29 mozilla%colinogilvie.co.uk Exp $ -->
+<!-- $Id: installation.xml,v 1.100 2008/04/04 06:47:30 mozilla%colinogilvie.co.uk Exp $ -->
 <chapter id="installing-bugzilla">
   <title>Installing Bugzilla</title>
 
@@ -651,6 +651,14 @@
           'max_allowed_packet' or 'maxattachmentsize' value will not be
           accepted by Bugzilla.
         </para>
+
+        <note>
+          <para>
+            This does not affect Big Files, attachments that are stored directly
+            on disk instead of in the database.  Their maximum size is
+            controlled using the 'maxlocalattachment' parameter.
+          </para>
+        </note>
       </section>
 
 
@@ -707,6 +715,13 @@
           to make a temporary copy of your entire table to do this. Ideally, 
           you should do this when your attachments table is still small.
         </para>
+
+        <note>
+          <para>
+            This does not affect Big Files, attachments that are stored directly
+            on disk instead of in the database.
+          </para>
+        </note>
       </section>
             
       <section id="install-setupdatabase-adduser">
diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml
index 8f616597a..720f461e9 100644
--- a/docs/en/xml/using.xml
+++ b/docs/en/xml/using.xml
@@ -234,8 +234,12 @@
       <listitem>
         <para>
         <emphasis>Attachments:</emphasis>
-        You can attach files (e.g. testcases or patches) to bugs. If there
-        are any attachments, they are listed in this section.</para>
+          You can attach files (e.g. testcases or patches) to bugs. If there
+          are any attachments, they are listed in this section.  Attachments are
+          normally stored in the Bugzilla database, unless they are marked as
+          Big Files, which are stored directly on disk and (unlike attachments
+          kept in the database) may be deleted at some future time.
+        </para>
       </listitem>
 
       <listitem>
@@ -261,6 +265,28 @@
     </orderedlist>
   </section>
 
+  <section id="lifecycle">
+    <title>Life Cycle of a Bug</title>
+
+    <para>
+      The life cycle, also known as work flow, of a bug is currently hardcoded
+      into Bugzilla. <xref linkend="lifecycle-image"/> contains a graphical
+      repsentation of this life cycle. If you wish to customize this image for
+      your site, the <ulink url="../images/bzLifecycle.xml">diagram file</ulink>
+      is available in <ulink url="http://www.gnome.org/projects/dia">Dia's</ulink>
+      native XML format.
+    </para>
+
+    <figure id="lifecycle-image">
+      <title>Lifecycle of a Bugzilla Bug</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="../images/bzLifecycle.png" scale="66" />
+        </imageobject>
+      </mediaobject>
+    </figure>
+  </section>
+
   <section id="query">
     <title>Searching for Bugs</title>
 
@@ -278,8 +304,144 @@
     <para>Once you've run a search, you can save it as a Saved Search, which 
     appears in the page footer.</para>
 
-    <para>Highly advanced querying is done using Boolean Charts. See the
-    Boolean Charts help link on the Search page for more information.</para>
+    <section id="boolean">
+      <title>Boolean Charts</title>
+      <para>
+        Highly advanced querying is done using Boolean Charts.
+      </para>
+      <para>
+        The boolean charts further restrict the set of results
+        returned by a query. It is possible to search for bugs
+        based on elaborate combinations of critera.
+      </para>
+      <para>
+        The simplest boolean searches have only one term. These searches
+        permit the selected left <emphasis>field</emphasis>
+        to be compared using a
+        selectable <emphasis>operator</emphasis> to a
+        specified <emphasis>value.</emphasis>
+        Using the "And," "Or," and "Add Another Boolean Chart" buttons, 
+        additonal terms can be included in the query, further
+        altering the list of bugs returned by the query.
+      </para>
+      <para>
+        There are three fields in each row of a boolean search. 
+      </para>
+      <itemizedlist>
+        <listitem>
+          <para>
+            <emphasis>Field:</emphasis>
+            the items being searched 
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <emphasis>Operator:</emphasis>
+            the comparison operator 
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <emphasis>Value:</emphasis>
+            the value to which the field is being compared
+          </para>
+        </listitem>
+      </itemizedlist>
+      <section id="pronouns">
+        <title>Pronoun Substitution</title>
+        <para>
+          Sometimes, a query needs to compare a field containing
+          a user's ID (such as ReportedBy) with 
+          a user's ID (such as the user running the query or the user
+          to whom each bug is assigned). When the operator is either 
+          "equals" or "notequals", the value can be "%reporter%", 
+          "%assignee%", "%qacontact%", or "%user%."  The user pronoun
+          referes to the user who is executing the query or, in the case
+          of whining reports, the user who will be the recipient
+          of the report. The reporter, assignee, and qacontact
+          pronouns refer to the corresponding fields in the bug.
+        </para>
+      </section>
+      <section id="negation">
+        <title>Negation</title>
+        <para>
+          At first glance, negation seems redundant. Rather than
+          searching for
+          <blockquote>
+            <para>
+              NOT("summary" "contains the string" "foo"),
+            </para>
+          </blockquote>
+          one could search for 
+          <blockquote>
+            <para>
+              ("summary" "does not contain the string" "foo").
+            </para>
+          </blockquote>
+          However, the search 
+          <blockquote>
+            <para>
+              ("CC" "does not contain the string" "@mozilla.org")
+            </para>
+          </blockquote>
+          would find every bug where anyone on the CC list did not contain 
+          "@mozilla.org" while
+          <blockquote>
+            <para>
+              NOT("CC" "contains the string" "@mozilla.org")
+            </para>
+          </blockquote>
+          would find every bug where there was nobody on the CC list who
+          did contain the string. Similarly, the use of negation also permits
+          complex expressions to be built using terms OR'd together and then
+          negated. Negation permits queries such as
+          <blockquote>
+            <para>
+              NOT(("product" "equals" "update") OR 
+            ("component" "equals" "Documentation"))
+            </para>
+          </blockquote>
+          to find bugs that are neither 
+          in the update product or in the documentation component or
+          <blockquote>
+            <para>
+              NOT(("commenter" "equals" "%assignee%") OR 
+              ("component" "equals" "Documentation"))
+            </para>
+          </blockquote>
+          to find non-documentation
+          bugs on which the assignee has never commented.
+        </para>
+      </section>
+      <section id="multiplecharts">
+        <title>Multiple Charts</title>
+        <para>
+          The terms within a single row of a boolean chart are all
+          constraints on a single piece of data. If you are looking for
+          a bug that has two different people cc'd on it, then you need 
+          to use two boolean charts. A search for
+          <blockquote>
+            <para>
+              ("cc" "contains the string" "foo@") AND
+              ("cc" "contains the string" "@mozilla.org")
+            </para>
+          </blockquote>
+          would return only bugs with "foo@mozilla.org" on the cc list.
+          If you wanted bugs where there is someone on the cc list
+          containing "foo@" and someone else containing "@mozilla.org",
+          then you would need two boolean charts.
+          <blockquote>
+            <para>
+              First chart: ("cc" "contains the string" "foo@")
+            </para>
+            <para>
+              Second chart: ("cc" "contains the string" "@mozilla.org")
+            </para>
+          </blockquote>
+          The bugs listed will be only the bugs where ALL the charts are true.
+        </para>
+      </section>
+    </section>
   </section>
 
   <section id="list">
@@ -303,7 +465,22 @@
 
       get the buglist as comma-separated values, for import into e.g.
       a spreadsheet.</member>
-      
+     
+      <member>
+      <emphasis>RSS</emphasis>
+
+      get the buglist as an RSS 1.0 feed.  Copy this link into your
+      favorite feed reader.  If you are using Firefox, you can also
+      save the list as a live bookmark by clicking the live bookmark
+      icon in the status bar.  To limit the number of bugs in the feed,
+      add a limit=n parameter to the URL.</member>
+
+      <member>
+      <emphasis>iCalendar</emphasis>
+
+      Get the buglist as an iCalendar file. Each bug is represented as a 
+      to-do item in the imported calendar.</member>
+     
       <member>
       <emphasis>Change Columns:</emphasis>
 
@@ -314,12 +491,12 @@
 
       If your account is sufficiently empowered, you can make the same
       change to all the bugs in the list - for example, changing their
-      owner.</member>
+      assignee.</member>
 
       <member>
-      <emphasis>Send mail to bug owners:</emphasis>
+      <emphasis>Send mail to bug assignees:</emphasis>
 
-      Sends mail to the owners of all bugs on the list.</member>
+      Sends mail to the assignees of all bugs on the list.</member>
 
       <member>
       <emphasis>Edit Search:</emphasis>
@@ -336,6 +513,17 @@
       </member>
     </simplelist>
     </para>
+
+    <para>
+      If you would like to access the bug list from another program 
+      it is often useful to have the list returned in something other
+      than HTML. By adding the ctype=type parameter into the bug list URL
+      you can specify several alternate formats. The supported formats
+      are: Comma Separated Values (ctype=csv), iCalendar (ctype=ics),
+      RDF Site Summary (RSS) 1.0 (ctype=rss), ECMAScript, also known
+      as JavaScript (ctype=js), and finally Resource Description Framework
+      RDF/XML (ctype=rdf).
+    </para>
   </section>
 
   <section id="bugreports">
@@ -590,7 +778,17 @@
       Content-Type (e.g. application/xhtml+xml), you can override this 
       using a 'content-type' parameter on the URL, e.g.
       <filename>&amp;content-type=text/plain</filename>.
-      </para>     
+      </para> 
+
+      <para>
+        If you have a really large attachment, something that does not need to
+        be recorded forever (as most attachments are), you can mark your
+        attachment as a Big File, Assuming the administrator of the
+        installation has enabled this feature.  Big Files are stored directly on
+        disk instead of in the database, and can be deleted when it is no longer
+        needed.  The maximum size of a Big File is normally larger than the
+        maximum size of a regular attachment.
+      </para>
     </section>
   </section>
   
@@ -619,30 +817,144 @@
     <section id="emailsettings">
       <title>Email Settings</title>
 
-      <para>On this tab you can reduce or increase the amount of email sent
-      you from Bugzilla, opting in our out depending on your relationship to
-      the bug and the change that was made to it. 
+      <para>
+        This tab controls the amount of email Bugzilla sends you.
       </para>
-      
+
       <para>
-      You can also do further filtering on the client side by 
-      using the X-Bugzilla-Reason mail header which Bugzilla
-      adds to all bugmail. This tells you what relationship you have to the
-      bug in question,
-      and can be any of Owner, Reporter, QAcontact, CClist, Voter and
-      WatchingComponent.</para>
+        The first item on this page is marked <quote>Users to watch</quote>.
+        When you enter one or more comma-delineated user accounts (usually email
+        addresses) into the text entry box, you will receive a copy of all the
+        bugmail those users are sent (security settings permitting).
+        This powerful functionality enables seamless transitions as developers
+        change projects or users go on holiday.
+      </para>
 
-      <para>By entering user email names, delineated by commas, into the
-      "Users to watch" text entry box you can receive a copy of all the
-      bugmail of other users (security settings permitting.) This powerful
-      functionality enables seamless transitions as developers change
-      projects or users go on holiday.</para>
+      <note>
+        <para>
+          The ability to watch other users may not be available in all
+          Bugzilla installations. If you don't see this feature, and feel
+          that you need it, speak to your administrator.
+        </para>
+      </note>
+
+      <para>
+        In general, users have almost complete control over how much (or
+        how little) email Bugzilla sends them. If you want to receive the
+        maximum amount of email possible, click the <quote>Enable All 
+        Mail</quote> button. If you don't want to receive any email from
+        Bugzilla at all, click the <quote>Disable All Mail</quote> button.
+      </para>
 
       <note>
-        <para>The ability to watch other users may not be available in all
-        Bugzilla installations. If you can't see it, ask your 
-        administrator.</para>
+        <para>
+          Your Bugzilla administrator can stop a user from receiving
+          bugmail by adding the user's name to the 
+          <filename>data/nomail</filename> file. This is a drastic step
+          best taken only for disabled accounts, as it overrides the 
+          the user's individual mail preferences.
+        </para>
       </note>
+  
+      <para>
+        If you'd like to set your bugmail to something besides
+        'Completely ON' and 'Completely OFF', the
+        <quote>Field/recipient specific options</quote> table
+        allows you to do just that. The rows of the table
+        define events that can happen to a bug -- things like
+        attachments being added, new comments being made, the
+        priority changing, etc. The columns in the table define
+        your relationship with the bug:
+      </para>
+
+      <itemizedlist spacing="compact">
+        <listitem>
+          <para>
+            Reporter - Where you are the person who initially
+            reported the bug. Your name/account appears in the
+            <quote>Reporter:</quote> field.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Assignee - Where you are the person who has been
+            designated as the one responsible for the bug. Your
+            name/account appears in the <quote>Assigned To:</quote>
+            field of the bug.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            QA Contact - You are one of the designated
+            QA Contacts for the bug. Your account appears in the 
+            <quote>QA Contact:</quote> text-box of the bug.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            CC - You are on the list CC List for the bug.
+            Your account appears in the <quote>CC:</quote> text box
+            of the bug.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Voter - You have placed one or more votes for the bug.
+            Your account appears only if someone clicks on the 
+            <quote>Show votes for this bug</quote> link on the bug.
+          </para>
+        </listitem>
+      </itemizedlist>
+
+
+      <note>
+        <para>
+          Some columns may not be visible for your installation, depending
+          on your site's configuration.
+        </para>
+      </note>
+
+      <para>
+        To fine-tune your bugmail, decide the events for which you want
+        to receive bugmail; then decide if you want to receive it all
+        the time (enable the checkbox for every column), or only when
+        you have a certain relationship with a bug (enable the checkbox
+        only for those columns). For example: if you didn't want to
+        receive mail when someone added themselves to the CC list, you
+        could uncheck all the boxes in the <quote>CC Field Changes</quote>
+        line. As another example, if you never wanted to receive email
+        on bugs you reported unless the bug was resolved, you would
+        un-check all boxes in the <quote>Reporter</quote> column
+        except for the one on the <quote>The bug is resolved or
+        verified</quote> row.
+      </para>
+
+      <note>
+        <para>
+          Bugzilla adds the <quote>X-Bugzilla-Reason</quote> header to
+          all bugmail it sends, describing the recipient's relationship
+          (AssignedTo, Reporter, QAContact, CC, or Voter) to the bug.
+          This header can be used to do further client-side filtering.
+        </para>
+      </note>
+
+      <para>
+        Two items not in the table (<quote>Email me when someone
+        asks me to set a flag</quote> and <quote>Email me when someone
+        sets a flag I asked for</quote>) define how you want to
+        receive bugmail with regards to flags. Their use is quite
+        straightforward; enable the checkboxes if you want Bugzilla to
+        send you mail under either of the above conditions.
+      </para>
+
+      <para>
+        By default, Bugzilla sends out email regardless of who made the
+        change... even if you were the one responsible for generating
+        the email in the first place. If you don't care to receive bugmail
+        from your own changes, check the box marked <quote>Only email me
+        reports of changes made by other people</quote>.
+      </para>
+
     </section>
 
     <section id="permissionsettings">
@@ -862,6 +1174,214 @@
     </para>
   </section>
 
+  <section id="whining">
+    <title>Whining</title>
+
+    <para>
+      Whining is a feature in Bugzilla that can regularly annoy users at 
+      specified times.  Using this feature, users can execute saved searches 
+      at specific times (i.e. the 15th of the month at midnight) or at 
+      regular intervals (i.e. every 15 minutes on Sundays).  The results of the
+      searches are sent to the user, either as a single email or as one email 
+      per bug, along with some descriptive text.
+    </para>
+
+    <warning>
+      <para>
+        Throughout this section it will be assumed that all users are members 
+        of the bz_canusewhines group, membership in which is required in order 
+        to use the Whining system.  You can easily make all users members of 
+        the bz_canusewhines group by setting the User RegExp to ".*" (without 
+        the quotes).
+      </para>
+
+      <para>
+        Also worth noting is the bz_canusewhineatothers group.  Members of this
+        group can create whines for any user or group in Bugzilla using a 
+        extended form of the whining interface.  Features only available to 
+        members of the bz_canusewhineatothers group will be noted in the 
+        appropriate places.
+      </para>
+    </warning>
+
+    <note>
+      <para>
+        For whining to work, a special Perl script must be executed at regular
+        intervals.  More information on this is available in 
+        <xref linkend="installation-whining"/>.
+      </para>
+    </note>
+
+    <note>
+      <para>
+        This section does not cover the whineatnews.pl script.  See
+        <xref linkend="installation-whining-cron"/> for more information on 
+        The Whining Cron.
+      </para>
+    </note>
+
+    <section id="whining-overview">
+      <title>The Event</title>
+
+      <para>
+        The whining system defines an "Event" as one or more queries being 
+        executed at regular intervals, with the results of said queries (if
+        there are any) being emailed to the user.  Events are created by 
+        clicking on the "Add new event" button.
+      </para>
+
+      <para>
+        Once a new event is created, the first thing to set is the "Email 
+        subject line".  The contents of this field will be used in the subject
+        line of every email generated by this event.  In addition to setting a 
+        subject, space is provided to enter some descriptive text that will be 
+        included at the top of each message (to help you in understanding why 
+        you received the email in the first place).
+      </para>
+
+      <para>
+        The next step is to specify when the Event is to be run (the Schedule) 
+        and what searches are to be performed (the Queries).
+      </para>
+
+    </section>
+
+    <section id="whining-schedule">
+      <title>Whining Schedule</title>
+
+      <para>
+         Each whining event is associated with zero or more schedules.  A 
+         schedule is used to specify when the query (specified below) is to be
+         run.  A new event starts out with no schedules (which means it will 
+         never run, as it is not scheduled to run).  To add a schedule, press
+         the "Add a new schedule" button.
+      </para>
+
+      <para>
+         Each schedule includes an interval, which you use to tell Bugzilla 
+         when the event should be run.  An event can be run on certain days of
+         the week, certain days of the month, during weekdays (defined as 
+         Monday through Friday), or every day.
+      </para>
+
+      <warning>
+        <para>
+          Be careful if you set your event to run on the 29th, 30th, or 31st of
+          the month, as your event may not run exactly when expected.  If you 
+          want your event to run on the last day of the month, select "Last day
+          of the month" as the interval.
+        </para>
+      </warning>
+
+      <para>
+        Once you have specified the day(s) on which the event is to be run, you
+        should now specify the time at which the event is to be run.  You can 
+        have the event run at a certain hour on the specified day(s), or 
+        every hour, half-hour, or quarter-hour on the specified day(s).
+      </para>
+
+      <para>
+        If a single schedule does not execute an event as many times as you 
+        would want, you can create another schedule for the same event.  For 
+        example, if you want to run an event on days whose numbers are
+        divisible by seven, you would need to add four schedules to the event,
+        setting the schedules to run on the 7th, 14th, 21st, and 28th (one day 
+        per schedule) at whatever time (or times) you choose.
+      </para>
+
+      <note>
+        <para>
+          If you are a member of the bz_canusewhineatothers group, then you
+          will be presented with another option: "Mail to".  Using this you 
+          can control who will receive the emails generated by this event.  You
+          can choose to send the emails to a single user (identified by email 
+          address) or a single group (identified by group name).  To send to 
+          multiple users or groups, create a new schedule for each additional 
+          user/group.
+        </para>
+      </note>
+    </section>
+
+    <section id="whining-query">
+      <title>Whining Queries</title>
+
+      <para>
+        Each whining event is associated with zero or more queries.  A query is
+        a saved search that is executed on the schedule specified (see above).
+        You start out with zero queries attached to the event (which means that
+        the event will not run, as there will never be any results to return).
+        To add a query, press the "Add a new query" button.
+      </para>
+
+      <para>
+        The first field to examine in your new query is the Sort field.  Queries
+        are executed, and results returned, in the order specified by the Sort 
+        field.  Queries with lower Sort values will run before queries with 
+        higher Sort values.
+      </para>
+
+      <para>
+        The next field to examine is the Search field.  This is where you 
+        choose the actual search that is to be run.  Instead of defining search
+        parameters here, you are asked to choose from the list of saved 
+        searches (the same list that appears at the bottom of every Bugzilla 
+        page).  You are only allowed to choose from searches that you have 
+        saved yourself (the default saved search, "My Bugs", is not a valid 
+        choice).  If you do not have any saved searches, you can take this 
+        opportunity to create one (see <xref linkend="list"/>).
+      </para>
+
+      <note>
+        <para>
+          When running queries, the whining system acts as if you are the user
+          executing the query.  This means that the whining system will ignore
+          bugs that match your query, but that you can not access.
+        </para>
+      </note>
+
+      <para>
+        Once you have chosen the saved search to be executed, give the query a 
+        descriptive title.  This title will appear in the email, above the 
+        results of the query.  If you choose "One message per bug", the query 
+        title will appear at the top of each email that contains a bug matching
+        your query.
+      </para>
+
+      <para>
+        Finally, decide if the results of the query should be sent in a single
+        email, or if each bug should appear in its own email.
+      </para>
+
+      <warning>
+        <para>
+          Think carefully before checking the "One message per bug" box.  If
+          you create a query that matches thousands of bugs, you will receive 
+          thousands of emails!
+        </para>
+      </warning>
+    </section>
+
+    <section>
+      <title>Saving Your Changes</title>
+
+      <para>
+        Once you have defined at least one schedule, and created at least one 
+        query, go ahead and "Update/Commit".  This will save your Event and make
+        it available for immediate execution.
+      </para>
+
+      <note>
+        <para>
+          If you ever feel like deleting your event, you may do so using the 
+          "Remove Event" button in the upper-right corner of each Event.  You 
+          can also modify an existing event, so long as you "Update/Commit" 
+          after completing your modifications.
+        </para>
+      </note>
+    </section>
+
+  </section>
+
 </chapter>
 
 <!-- Keep this comment at the end of the file