GH-221: Added reserved names to docs (#523)

Author: Ross Mechanic

docs/common_issues.rst

@@ -112,3 +112,47 @@ historical model tries to insert using the ``F()`` expression, and raises a
 ``ValueError``.
 
 .. _here: https://docs.djangoproject.com/en/2.0/ref/models/expressions/#f-expressions
+
+
+Reserved Field Names
+--------------------
+
+For each base model that has its history tracked using ``django-simple-history``,
+an associated historical model is created. Thus, if we have:
+
+.. code-block:: python
+
+    class BaseModel(models.Model):
+        history = HistoricalRecords()
+
+a Django model called ``HistoricalBaseModel`` is also created with all of the fields
+from ``BaseModel``, plus a few extra fields and methods that are on all historical models.
+
+Since these fields and methods are on all historical models, any field or method names
+on a base model that clash with those names will not be on the historical model (and,
+thus, won't be tracked). The reserved historical field and method names are below:
+
+- ``history_id``
+- ``history_date``
+- ``history_change_reason``
+- ``history_type``
+- ``history_object``
+- ``history_user``
+- ``history_user_id``
+- ``instance``
+- ``instance_type``
+- ``next_record``
+- ``prev_record``
+- ``revert_url``
+- ``__str__``
+
+So if we have:
+
+.. code-block:: python
+
+    class BaseModel(models.Model):
+        instance = models.CharField(max_length=255)
+        history = HistoricalRecords()
+
+the ``instance`` field will not actually be tracked on the history table because it's
+in the reserved set of terms.