1 files changed, 149 insertions, 0 deletions
diff --git a/docs/en/rst/administering/custom-fields.rst b/docs/en/rst/administering/custom-fields.rst
new file mode 100644
index 000000000..29cc72e62
--- /dev/null
+++ b/docs/en/rst/administering/custom-fields.rst
@@ -0,0 +1,149 @@
+.. _custom-fields:
+
+Custom Fields
+#############
+
+Custom Fields are fields defined by the administrator, in addition to those
+which come with Bugzilla by default. Custom Fields are treated like any other
+field—they can be set in bugs and used for search queries.
+
+Administrators should keep in mind that
+adding too many fields can make the user interface more complicated and
+harder to use. Custom Fields should be added only when necessary and with
+careful consideration.
+
+.. note:: Before adding a Custom Field, make sure that Bugzilla cannot already
+   do the desired behavior. Many Bugzilla options are not enabled by
+   default, and many times Administrators find that simply enabling
+   certain options that already exist is sufficient.
+
+Administrators can manage Custom Fields using the
+``Custom Fields`` link on the Administration page. The Custom
+Fields administration page displays a list of Custom Fields, if any exist,
+and a link to "Add a new custom field".
+
+.. _add-custom-fields:
+
+Adding Custom Fields
+====================
+
+To add a new Custom Field, click the "Add a new custom field" link. This
+page displays several options for the new field, described below.
+
+The following attributes must be set for each new custom field:
+
+- *Name:*
+  The name of the field in the database, used internally. This name
+  MUST begin with ``cf_`` to prevent confusion with
+  standard fields. If this string is omitted, it will
+  be automatically added to the name entered.
+
+- *Description:*
+  A brief string used as the label for this Custom Field.
+  That is the string that users will see, and it should be
+  short and explicit.
+
+- *Type:*
+  The type of field to create. There are
+  several types available:
+
+  Bug ID:
+      A field where you can enter the ID of another bug from
+      the same Bugzilla installation. To point to a bug in a remote
+      installation, use the See Also field instead.
+  Large Text Box:
+      A multiple line box for entering free text.
+  Free Text:
+      A single line box for entering free text.
+  Multiple-Selection Box:
+      A list box where multiple options
+      can be selected. After creating this field, it must be edited
+      to add the selection options. See
+      :ref:`edit-values-list` for information about
+      editing legal values.
+  Drop Down:
+      A list box where only one option can be selected.
+      After creating this field, it must be edited to add the
+      selection options. See
+      :ref:`edit-values-list` for information about
+      editing legal values.
+  Date/Time:
+      A date field. This field appears with a
+      calendar widget for choosing the date.
+
+- *Sortkey:*
+  Integer that determines in which order Custom Fields are
+  displayed in the User Interface, especially when viewing a bug.
+  Fields with lower values are displayed first.
+
+- *Reverse Relationship Description:*
+  When the custom field is of type ``Bug ID``, you can
+  enter text here which will be used as label in the referenced
+  bug to list bugs which point to it. This gives you the ability
+  to have a mutual relationship between two bugs.
+
+- *Can be set on bug creation:*
+  Boolean that determines whether this field can be set on
+  bug creation. If not selected, then a bug must be created
+  before this field can be set. See :ref:`filing`
+  for information about filing bugs.
+
+- *Displayed in bugmail for new bugs:*
+  Boolean that determines whether the value set on this field
+  should appear in bugmail when the bug is filed. This attribute
+  has no effect if the field cannot be set on bug creation.
+
+- *Is obsolete:*
+  Boolean that determines whether this field should
+  be displayed at all. Obsolete Custom Fields are hidden.
+
+- *Is mandatory:*
+  Boolean that determines whether this field must be set.
+  For single and multi-select fields, this means that a (non-default)
+  value must be selected; for text and date fields, some text
+  must be entered.
+
+- *Field only appears when:*
+  A custom field can be made visible when some criteria is met.
+  For instance, when the bug belongs to one or more products,
+  or when the bug is of some given severity. If left empty, then
+  the custom field will always be visible, in all bugs.
+
+- *Field that controls the values that appear in this field:*
+  When the custom field is of type ``Drop Down`` or
+  ``Multiple-Selection Box``, you can restrict the
+  availability of the values of the custom field based on the
+  value of another field. This criteria is independent of the
+  criteria used in the ``Field only appears when``
+  setting. For instance, you may decide that some given value
+  ``valueY`` is only available when the bug status
+  is RESOLVED while the value ``valueX`` should
+  always be listed.
+  Once you have selected the field that should control the
+  availability of the values of this custom field, you can
+  edit values of this custom field to set the criteria; see
+  :ref:`edit-values-list`.
+
+.. _edit-custom-fields:
+
+Editing Custom Fields
+=====================
+
+As soon as a Custom Field is created, its name and type cannot be
+changed. If this field is a drop-down menu, its legal values can
+be set as described in :ref:`edit-values-list`. All
+other attributes can be edited as described above.
+
+.. _delete-custom-fields:
+
+Deleting Custom Fields
+======================
+
+Only custom fields that are marked as obsolete, and that have never
+been used, can be deleted completely (else the integrity
+of the bug history would be compromised). For custom fields marked
+as obsolete, a "Delete" link will appear in the ``Action``
+column. If the custom field has been used in the past, the deletion
+will be rejected. Marking the field as obsolete, however, is sufficient
+to hide it from the user interface entirely.
+