Bug 1067416 - reorganize and update Bugzilla docs

7 files changed, 655 insertions, 0 deletions

diff --git a/docs/en/rst/integrating/apis.rst b/docs/en/rst/integrating/apis.rst
new file mode 100644
index 000000000..6067c12df
--- /dev/null
+++ b/docs/en/rst/integrating/apis.rst
@@ -0,0 +1,72 @@
+.. _api-list:
+
+APIs
+####
+
+Bugzilla has a number of APIs that you can call in your code to extract
+information from and put information into Bugzilla. Some are deprecated and
+will soon be removed. Which one to use? Short answer: the
+:ref:`REST WebService API v1 <apis>`
+should be used for all new integrations, but keep an eye out for version 2,
+coming soon.
+
+The APIs currently available are as follows:
+
+Ad-Hoc APIs
+===========
+
+Various pages on Bugzilla are available in machine-parseable formats as well
+as HTML. For example, bugs can be downloaded as XML, and buglists as CSV.
+CSV is useful for spreadsheet import. There should be links on the HTML page
+to alternate data formats where they are available.
+
+XML-RPC
+=======
+
+Bugzilla has an `XML-RPC API
+<http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Server/XMLRPC.html>`_.
+This will receive no further updates and will be removed in a future version
+of Bugzilla.
+
+Endpoint: :file:`/xmlrpc.cgi`
+
+JSON-RPC
+========
+
+Bugzilla has a `JSON-RPC API
+<http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Server/JSONRPC.html>`_.
+This will receive no further updates and will be removed in a future version
+of Bugzilla.
+
+Endpoint: :file:`/jsonrpc.cgi`
+
+REST
+====
+
+Bugzilla has a :ref:`REST API <apis>` which is the currently-recommended API
+for integrating with Bugzilla. The current REST API is version 1. It is stable,
+and so will not be changed in a backwardly-incompatible way.
+
+**This is the currently-recommended API for new development.**
+
+Endpoint: :file:`/rest`
+
+BzAPI/BzAPI-Compatible REST
+===========================
+
+The first ever REST API for Bugzilla was implemented using an external proxy
+called `BzAPI <https://wiki.mozilla.org/Bugzilla:BzAPI>`_. This became popular
+enough that a BzAPI-compatible shim on top of the (native) REST API has been
+written, to allow code which used the BzAPI API to take advantage of the
+speed improvements of direct integration without needing to be rewritten.
+The shim is an extension which you would need to install in your Bugzilla.
+
+Neither BzAPI nor this BzAPI-compatible API shim will receive any further
+updates, and they should not be used for new code.
+
+REST v2
+=======
+
+The future of Bugzilla's APIs is version 2 of the REST API, which will take
+the best of the current REST API and the BzAPI API. It is still under
+development.
diff --git a/docs/en/rst/integrating/extensions.rst b/docs/en/rst/integrating/extensions.rst
new file mode 100644
index 000000000..2097909fc
--- /dev/null
+++ b/docs/en/rst/integrating/extensions.rst
@@ -0,0 +1,199 @@
+.. _extensions:
+
+Extensions
+##########
+
+One of the best ways to customize Bugzilla is by using a Bugzilla
+Extension. Extensions can modify both the code and UI of Bugzilla in a way
+that can be distributed to other Bugzilla users and ported forward to future
+versions of Bugzilla with minimal effort. We maintain a
+`list of available extensions <https://wiki.mozilla.org/Bugzilla:Addons>`_
+written by other people on our wiki. You would need to
+make sure that the extension in question works with your version of Bugzilla.
+
+Or, you can write your own extension. See the `Bugzilla Extension
+documentation <../html/api/Bugzilla/Extension.html>`_ for the core
+documentation on how to do that. It would make sense to read
+the section on :ref:`templates`. There is also a sample extension in
+:file:`$BUGZILLA_HOME/extensions/Example/` which gives examples of how to
+use all the code hooks.
+
+This section explains how to achieve some common tasks using the Extension APIs.
+
+Adding A New Page to Bugzilla
+=============================
+
+There are occasions where it's useful to add a new page to Bugzilla which
+has little or no relation to other pages, and perhaps doesn't use very much
+Bugzilla data. A help page, or a custom report for example. The best mechanism
+for this is to use :file:`page.cgi` and the ``page_before_template`` hook.
+
+Altering Data On An Existing Page
+=================================
+
+The ``template_before_process`` hook can be used to tweak the data displayed
+on a particular existing page, if you know what template is used. It has
+access to all the template variables before they are passed to the templating
+engine.
+
+Adding New Fields To Bugs
+=========================
+
+To add new fields to a bug, you need to do the following:
+
+* Add an ``install_update_db`` hook to add the fields by calling
+  ``Bugzilla::Field->create`` (only if the field doesn't already exist).
+  Here's what it might look like for a single field:
+
+  .. code-block:: perl
+
+    my $field = new Bugzilla::Field({ name => $name });
+    return if $field;
+ 
+    $field = Bugzilla::Field->create({
+        name        => $name,
+        description => $description,
+        type        => $type,        # From list in Constants.pm
+        enter_bug   => 0,
+        buglist     => 0,
+        custom      => 1,
+    });
+
+* Push the name of the field onto the relevant arrays in the ``bug_columns``
+  and ``bug_fields`` hooks.
+
+* If you want direct accessors, or other functions on the object, you need to
+  add a BEGIN block to your Extension.pm:
+
+  .. code-block:: perl
+
+    BEGIN { 
+       *Bugzilla::Bug::is_foopy = \&_bug_is_foopy; 
+    }
+ 
+    ...
+ 
+    sub _bug_is_foopy {
+        return $_[0]->{'is_foopy'};
+    }
+
+* You don't have to change ``Bugzilla/DB/Schema.pm``.
+
+* You can use ``bug_end_of_create``, ``bug_end_of_create_validators``, and
+  ``bug_end_of_update`` to create or update the values for your new field.
+
+Adding New Fields To Other Things
+=================================
+
+If you are adding the new fields to an object other than a bug, you need to
+go a bit lower-level. With reference to the instructions above:
+
+* In ``install_update_db``, use ``bz_add_column`` instead
+
+* Push on the columns in ``object_columns`` and ``object_update_columns``
+  instead of ``bug_columns``.
+
+* Add validators for the values in ``object_validators``
+
+The process for adding accessor functions is the same.
+
+You can use the hooks ``object_end_of_create``,
+``object_end_of_create_validators``, ``object_end_of_set_all``, and
+``object_end_of_update`` to create or update the values for the new object
+fields you have added. In the hooks you can check the object type being
+operated on and skip any objects you don't care about. For example, if you
+added a new field to the ``products`` table:
+
+.. code-block:: perl
+
+    sub object_end_of_create {
+        my ($self, $args) = @_;
+        my $class = $args->{'class'};
+        my $object = $args->{'object'};
+        if ($class->isa('Bugzilla::Product') {
+            [...]
+        }
+    }
+
+You will need to do this filtering for most of the hooks whose names begin with
+``object_``.
+
+Adding Admin Configuration Panels
+=================================
+
+If you add new functionality to Bugzilla, it may well have configurable
+options or parameters. The way to allow an administrator to set those
+is to add a new configuration panel.
+
+As well as using the ``config_add_panels`` hook, you will need a template to
+define the UI strings for the panel. See the templates in
+:file:`template/en/default/admin/params` for examples, and put your own
+template in :file:`template/en/default/admin/params` in your extension's
+directory.
+
+You can access param values from Templates using::
+
+    [% Param('param_name') %]
+
+and from code using:
+
+.. code-block:: perl
+
+    Bugzilla->params->{'param_name'}
+
+Adding User Preferences
+=======================
+
+To add a new user preference:
+
+* Call ``add_setting('setting_name', ['some_option', 'another_option'],
+  'some_option')`` in the ``install_before_final_checks`` hook. (The last
+  parameter is the name of the option which should be the default.)
+
+* Add descriptions for the identifiers for your setting and choices
+  (setting_name, some_option etc.) to the hash defined in
+  :file:`global/setting-descs.none.tmpl`. Do this in a template hook:
+  :file:`hook/global/setting-descs-settings.none.tmpl`. Your code can see the
+  hash variable; just set more members in it.
+
+* To change behaviour based on the setting, reference it in templates using
+  ``[% user.settings.setting_name.value %]``. Reference it in code using
+  ``$user->settings->{'setting_name'}->{'value'}``. The value will be one of
+  the option tag names (e.g. some_option).
+
+.. _who-can-change-what:
+
+Altering Who Can Change What
+============================
+
+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.
+
+By default, assignees, QA owners and users
+with *editbugs* privileges can edit all fields of bugs,
+except group restrictions (unless they are members of the groups they
+are trying to change). Bug reporters also have the ability to edit some
+fields, but in a more restrictive manner. Other users, without
+*editbugs* privileges, cannot edit
+bugs, except to comment and add themselves to the CC list.
+
+Because this kind of change is such a common request, we have added a
+specific hook for it that :ref:`extensions` can call. It's called
+``bug_check_can_change_field``, and it's documented `in the Hooks
+documentation <http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Hook.html#bug_check_can_change_field>`_.
+
+Checking Syntax
+===============
+
+It's not immediately obvious how to check the syntax of your extension's
+Perl modules, if it contains any. Running :command:`checksetup.pl` might do
+some of it, but the errors aren't necessarily massively informative.
+
+:command:`perl -Mlib=lib -MBugzilla -e 'BEGIN { Bugzilla->extensions; } use Bugzilla::Extension::ExtensionName::Class;'`
+
+(run from ``$BUGZILLA_HOME``) is what you need.
+
diff --git a/docs/en/rst/integrating/faq.rst b/docs/en/rst/integrating/faq.rst
new file mode 100644
index 000000000..19f8b59ff
--- /dev/null
+++ b/docs/en/rst/integrating/faq.rst
@@ -0,0 +1,27 @@
+
+.. _customization-faq:
+
+Customization FAQ
+=================
+
+How do I...
+
+...add a new field on a bug?
+  Use :ref:`custom-fields` or, if you just want new form fields on bug entry
+  but don't need Bugzilla to track the field seperately thereafter, you can
+  use a :ref:`custom bug entry form <custom-bug-entry>`.
+
+...change the name of a built-in bug field?
+  :ref:`Edit <templates>` the relevant value in the template
+  :file:`template/en/default/global/field-descs.none.tmpl`.
+
+...use a word other than 'bug' to describe bugs?
+  :ref:`Edit or override <templates>` the appropriate values in the template
+  :file:`template/en/default/global/variables.none.tmpl`.
+  
+...call the system something other than 'Bugzilla'?
+  :ref:`Edit or override <templates>` the appropriate value in the template
+  :file:`template/en/default/global/variables.none.tmpl`.
+  
+...alter who can change what field when?
+  See :ref:`who-can-change-what`.
diff --git a/docs/en/rst/integrating/index.rst b/docs/en/rst/integrating/index.rst
new file mode 100644
index 000000000..816ffe8e5
--- /dev/null
+++ b/docs/en/rst/integrating/index.rst
@@ -0,0 +1,22 @@
+.. highlight:: perl
+
+.. _integrating:
+
+===================================
+Integration and Customization Guide
+===================================
+
+You may find that Bugzilla already does what you want it to do, you just
+need to configure it correctly. Read the :ref:`administering` sections
+carefully to see if that's the case for you. If not, then this chapter
+explains how to use the available mechanisms for integration and customization.
+
+.. toctree::
+   :maxdepth: 2
+
+   faq
+   languages
+   skins
+   templates
+   extensions
+   apis
diff --git a/docs/en/rst/integrating/languages.rst b/docs/en/rst/integrating/languages.rst
new file mode 100644
index 000000000..01586d3fe
--- /dev/null
+++ b/docs/en/rst/integrating/languages.rst
@@ -0,0 +1,19 @@
+Languages
+=========
+
+Bugzilla's templates can be localized, although it's a `big job
+<https://wiki.mozilla.org/Bugzilla:L10n:Guide>`_. If you have
+a localized set of templates for your version of Bugzilla, Bugzilla can 
+support multiple languages at once. In that case, Bugzilla honours the user's
+``Accept-Language`` HTTP header when deciding which language to serve. If
+multiple languages are installed, a menu will display in the header allowing
+the user to manually select a different language. If they do this, their
+choice will override the ``Accept-Language`` header.
+
+Many language templates can be obtained from
+`the localization section of the Bugzilla website
+<http://www.bugzilla.org/download.html#localizations>`_. Instructions
+for submitting new languages are also available from that location. There's
+also a `list of localization teams
+<https://wiki.mozilla.org/Bugzilla:L10n:Localization_Teams>`_; you might
+want to contact someone to ask about the status of their localization.
diff --git a/docs/en/rst/integrating/skins.rst b/docs/en/rst/integrating/skins.rst
new file mode 100644
index 000000000..2cd08b4c0
--- /dev/null
+++ b/docs/en/rst/integrating/skins.rst
@@ -0,0 +1,27 @@
+.. _skins:
+
+Skins
+=====
+
+Bugzilla supports skins - ways of changing the look of the UI without altering
+its underlying structure. It ships with two - "Classic" and "Dusk". You can
+find some more listed
+`on the wiki <https://wiki.mozilla.org/Bugzilla:Addons#Skins>`_, and there
+are a couple more which are part of
+`bugzilla.mozilla.org <http://git.mozilla.org/?p=webtools/bmo/bugzilla.git>`_.
+However, in each
+case you may need to check that the skin supports the version of Bugzilla
+you have. 
+
+To create a new custom skin, make a directory that contains all the same CSS
+file names as :file:`skins/standard/`, and put your directory in
+:file:`skins/contrib/`. Then, add your CSS to the appropriate files.
+
+After you put the directory there, make sure to run :file:`checksetup.pl` so
+that it can set the file permissions correctly.
+
+After you have installed the new skin, it will show up as an option in the
+user's :guilabel:`Preferences`, on the :guilabel:`General` tab. If you would
+like to force a particular skin on all users, just select that skin in the
+:guilabel:`Default Preferences` in the :guilabel:`Administration` UI, and
+then uncheck "Enabled" on the preference, so users cannot change it.
diff --git a/docs/en/rst/integrating/templates.rst b/docs/en/rst/integrating/templates.rst
new file mode 100644
index 000000000..f30b4a848
--- /dev/null
+++ b/docs/en/rst/integrating/templates.rst
@@ -0,0 +1,289 @@
+.. _templates:
+
+Templates
+#########
+
+Bugzilla uses a system of templates to define its user interface. The standard
+templates can be modified, replaced or overridden. You can also use template
+hooks in an :ref:`extension <extensions>` to add or modify the
+behaviour of templates using a stable interface.
+
+.. _template-directory:
+
+Template Directory Structure
+============================
+
+The template directory structure starts with top level directory
+named :file:`template`, which contains a directory
+for each installed localization. Bugzilla comes with English
+templates, so the directory name is :file:`en`,
+and we will discuss :file:`template/en` throughout
+the documentation. Below :file:`template/en` is the
+:file:`default` directory, which contains all the
+standard templates shipped with Bugzilla.
+
+.. warning:: A directory :file:`data/template` also exists;
+   this is where Template Toolkit puts the compiled versions (i.e. Perl code)
+   of the templates. *Do not* directly edit the files in this
+   directory, or all your changes will be lost the next time
+   Template Toolkit recompiles the templates.
+
+.. _template-method:
+
+Choosing a Customization Method
+===============================
+
+If you want to edit Bugzilla's templates, the first decision
+you must make is how you want to go about doing so. There are three
+choices, and which you use depends mainly on the scope of your
+modifications, and the method you plan to use to upgrade Bugzilla.
+
+#. You can directly edit the templates found in :file:`template/en/default`.
+
+#. You can copy the templates to be modified into a mirrored directory
+   structure under :file:`template/en/custom`. Templates in this
+   directory structure automatically override any identically-named
+   and identically-located templates in the
+   :file:`template/en/default` directory. (The :file:`custom` directory does
+   not exist by default and must be created if you want to use it.)
+
+#. You can use the hooks built into many of the templates to add or modify
+   the UI from an :ref:`extension <extensions>`. Hooks generally don't go away
+   and have a stable interface. 
+
+The third method is the best if there are hooks in the appropriate places
+and the change you want to do is possible using hooks. It's not very easy
+to modify existing UI using hooks; they are most commonly used for additions.
+You can make modifications if you add JS code which then makes the
+modifications when the page is loaded. You can remove UI by adding CSS to hide
+it.
+
+Unlike code hooks, there is no requirement to document template hooks, so
+you just have to open up the template and see (search for ``Hook.process``).
+
+If there are no hooks available, then the second method of customization
+should be used if you are going to make major changes, because it is
+guaranteed that the contents of the :file:`custom` directory will not be
+touched during an upgrade, and you can then decide whether
+to revert to the standard templates, continue using yours, or make the effort
+to merge your changes into the new versions by hand. It's also good for
+entirely new files, and for a few files like
+:file:`bug/create/user-message.html.tmpl` which are designed to be entirely
+replaced.
+
+Using the second method, your user interface may break if incompatible
+changes are made to the template interface. Templates do change regularly
+and so interface changes are not individually documented, and you would
+need to work out what had changed and adapt your template accordingly.
+
+For minor changes, the convenience of the first method is hard to beat. When
+you upgrade Bugzilla, :command:`git` will merge your changes into the new
+version for you. On the downside, if the merge fails then Bugzilla will not
+work properly until you have fixed the problem and re-integrated your code.
+
+Also, you can see what you've changed using :command:`git diff`, which you
+can't if you fork the file into the :file:`custom` directory.
+
+.. _template-edit:
+
+How To Edit Templates
+=====================
+
+.. note:: If you are making template changes that you intend on submitting 
+   back for inclusion in standard Bugzilla, you should read the relevant
+   sections of the
+   `Developers' Guide <http://www.bugzilla.org/docs/developer.html>`_.
+
+Bugzilla uses a templating system called Template Toolkit. The syntax of the
+language is beyond the scope of this guide. It's reasonably easy to pick up by
+looking at the current templates; or, you can read the manual, available on
+the `Template Toolkit home page <http://www.template-toolkit.org>`_.
+
+One thing you should take particular care about is the need
+to properly HTML filter data that has been passed into the template.
+This means that if the data can possibly contain special HTML characters
+such as ``<``, and the data was not intended to be HTML, they need to be
+converted to entity form, i.e. ``&lt;``.  You use the ``html`` filter in the
+Template Toolkit to do this (or the ``uri`` filter to encode special
+characters in URLs).  If you forget, you may open up your installation
+to cross-site scripting attacks.
+
+
+You should run :command:`./checksetup.pl` after editing any templates. Failure
+to do so may mean either that your changes are not picked up, or that the
+permissions on the edited files are wrong so the webserver can't read them. 
+
+.. _template-formats:
+
+Template Formats and Types
+==========================
+
+Some CGI's have the ability to use more than one template. For example,
+:file:`buglist.cgi` can output itself as two formats of HTML (complex and
+simple). Each of these is a separate template. The mechanism that provides
+this feature is extensible - you can create new templates to add new formats.
+
+You might use this feature to e.g. add a custom bug entry form for a
+particular subset of users or a particular type of bug.
+
+Bugzilla can also support different types of output - e.g. bugs are available
+as HTML and as XML, and this mechanism is extensible also to add new content
+types. However, instead of using such interfaces or enhancing Bugzilla to add
+more, you would be better off using the :ref:`apis` to integrate with
+Bugzilla.
+
+To see if a CGI supports multiple output formats and types, grep the
+CGI for ``get_format``. If it's not present, adding
+multiple format/type support isn't too hard - see how it's done in
+other CGIs, e.g. :file:`config.cgi`.
+
+To make a new format template for a CGI which supports this,
+open a current template for
+that CGI and take note of the INTERFACE comment (if present.) This
+comment defines what variables are passed into this template. If
+there isn't one, I'm afraid you'll have to read the template and
+the code to find out what information you get.
+
+Write your template in whatever markup or text style is appropriate.
+
+You now need to decide what content type you want your template
+served as. The content types are defined in the
+:file:`Bugzilla/Constants.pm` file in the :file:`contenttypes`
+constant. If your content type is not there, add it. Remember
+the three- or four-letter tag assigned to your content type.
+This tag will be part of the template filename.
+
+Save your new template as
+:file:`<stubname>-<formatname>.<contenttypetag>.tmpl`.
+Try out the template by calling the CGI as
+``<cginame>.cgi?format=<formatname>``. Add ``&ctype=<type>`` if the type is
+not HTML.
+
+.. _template-specific:
+
+Particular Templates
+====================
+
+There are a few templates you may be particularly interested in
+customizing for your installation.
+
+:file:`index.html.tmpl`:
+  This is the Bugzilla front page.
+
+:file:`global/header.html.tmpl`:
+  This defines the header that goes on all Bugzilla pages.
+  The header includes the banner, which is what appears to users
+  and is probably what you want to edit instead.  However the
+  header also includes the HTML HEAD section, so you could for
+  example add a stylesheet or META tag by editing the header.
+
+:file:`global/banner.html.tmpl`:
+  This contains the ``banner``, the part of the header that appears
+  at the top of all Bugzilla pages.  The default banner is reasonably
+  barren, so you'll probably want to customize this to give your
+  installation a distinctive look and feel.  It is recommended you
+  preserve the Bugzilla version number in some form so the version
+  you are running can be determined, and users know what docs to read.
+
+:file:`global/footer.html.tmpl`:
+  This defines the footer that goes on all Bugzilla pages.  Editing
+  this is another way to quickly get a distinctive look and feel for
+  your Bugzilla installation.
+
+:file:`global/variables.none.tmpl`:
+  This allows you to change the word 'bug' to something else (e.g. "issue")
+  throughout the interface, and also to change the name Bugzilla to something
+  else (e.g. "FooCorp Bug Tracker").
+
+:file:`list/table.html.tmpl`:
+  This template controls the appearance of the bug lists created
+  by Bugzilla. Editing this template allows per-column control of
+  the width and title of a column, the maximum display length of
+  each entry, and the wrap behaviour of long entries.
+  For long bug lists, Bugzilla inserts a 'break' every 100 bugs by
+  default; this behaviour is also controlled by this template, and
+  that value can be modified here.
+
+:file:`bug/create/user-message.html.tmpl`:
+  This is a message that appears near the top of the bug reporting page.
+  By modifying this, you can tell your users how they should report
+  bugs.
+
+:file:`bug/process/midair.html.tmpl`:
+  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.
+
+.. _custom-bug-entry:
+
+:file:`bug/create/create.html.tmpl` and :file:`bug/create/comment.txt.tmpl`:
+    You may not wish to go to the effort of creating custom fields in
+    Bugzilla, yet you want to make sure that each bug report contains
+    a number of pieces of important information for which there is not
+    a special field. The bug entry system has been designed in an
+    extensible fashion to enable you to add arbitrary HTML widgets,
+    such as drop-down lists or textboxes, to the bug entry page
+    and have their values appear formatted in the initial comment.
+
+    An example of this is the `guided bug submission form
+    <http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided>`_.
+    The code for this comes with the Bugzilla distribution as an example for
+    you to copy. It can be found in the files
+    :file:`create-guided.html.tmpl` and :file:`comment-guided.html.tmpl`.
+        
+    A hidden field that indicates the format should be added inside
+    the form in order to make the template functional. Its value should
+    be the suffix of the template filename. For example, if the file
+    is called :file:`create-guided.html.tmpl`, then
+
+    ::
+
+        <input type="hidden" name="format" value="guided">
+
+    is used inside the form.
+
+    So to use this feature, create a custom template for
+    :file:`enter_bug.cgi`. The default template, on which you
+    could base it, is
+    :file:`default/bug/create/create.html.tmpl`.
+    Call it :file:`custom/bug/create/create-<formatname>.html.tmpl`, and
+    in it, add form inputs for each piece of information you'd like
+    collected - such as a build number, or set of steps to reproduce.
+
+    Then, create a template based on
+    :file:`default/bug/create/comment.txt.tmpl`, and call it
+    :file:`custom/bug/create/comment-<formatname>.txt.tmpl`.
+    It needs a couple of lines of boilerplate at the top like this::
+
+        [% USE Bugzilla %]
+        [% cgi = Bugzilla.cgi %
+
+    Then, this template can reference the form fields you have created using
+    the syntax ``[% cgi.param("field_name") %]``. When a bug report is
+    submitted, the initial comment attached to the bug report will be
+    formatted according to the layout of this template.
+
+    For example, if your custom enter_bug template had a field::
+
+        <input type="text" name="buildid" size="30">
+
+    and then your comment.txt.tmpl had::
+
+        [% USE Bugzilla %]
+        [% cgi = Bugzilla.cgi %]
+        Build Identifier: [%+ cgi.param("buildid") %]
+
+    then something like::
+
+        Build Identifier: 20140303
+
+    would appear in the initial comment.
+
+    This system allows you to gather structured data in bug reports without
+    the overhead and UI complexity of a large number of custom fields.