Skip to content

Commit 6d282a7

Browse files
committed
Add docs to change reason
1 parent 9e7d3a0 commit 6d282a7

File tree

1 file changed

+40
-0
lines changed

1 file changed

+40
-0
lines changed

docs/advanced.rst

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,3 +213,43 @@ You can use the ``table_name`` parameter with both ``HistoricalRecords()`` or
213213
pub_date = models.DateTimeField('date published')
214214
215215
register(Question, table_name='polls_question_history')
216+
217+
Change Reason
218+
-------------
219+
220+
Change reason is a message to explain why the change was made in the instance. It is stored in the
221+
field ``history_change_reason`` and its default value is ``None``.
222+
223+
By default, the django-simple-history gets the change reason in the field ``changeReason`` of the instance. Also, is possible to pass
224+
the ``changeReason`` explicitly. For this, after a save or delete in an instance, is necessary call the
225+
function ``utils.update_change_reason``. The first argument of this function is the instance and the seccond
226+
is the message that represents the change reason.
227+
228+
For instance, for the model:
229+
230+
.. code-block:: python
231+
232+
from django.db import models
233+
from simple_history.models import HistoricalRecords
234+
235+
class Poll(models.Model):
236+
question = models.CharField(max_length=200)
237+
history = HistoricalRecords()
238+
239+
You can create a instance with a implicity change reason.
240+
241+
.. code-block:: python
242+
243+
poll = Poll(question='Question 1')
244+
poll.changeReason = 'Add a question'
245+
poll.save()
246+
247+
Or you can pass the change reason explicitly:
248+
249+
.. code-block:: python
250+
251+
from simple_history.utils import update_change_reason
252+
253+
poll = Poll(question='Question 1')
254+
poll.save()
255+
update_change_reason(poll, 'Add a question')

0 commit comments

Comments
 (0)