add history change reason to allow reasoning for the changes; use changeReason to set values

Author: hmit

AUTHORS.rst

@@ -26,6 +26,7 @@ Authors
 - Trey Hunner
 - Ulysses Vilela
 - vnagendra
+- hmit
 
 Background
 ==========

CHANGES.rst

@@ -5,6 +5,7 @@ tip (unreleased)
 ----------------
 - Do NOT delete the history elements when a user is deleted.
 - Add support for ``latest``
+- Allow setting a reason for change. [using option changeReason]
 
 1.5.3 (2014-11-18)
 ------------------

simple_history/models.py

@@ -159,6 +159,7 @@ def get_instance(self):
         return {
             'history_id': models.AutoField(primary_key=True),
             'history_date': models.DateTimeField(),
+            'history_change_reason': models.CharField(max_length=100, null=True),
             'history_user': models.ForeignKey(
                 user_model, null=True, related_name=self.user_related_name,
                 on_delete=models.SET_NULL),
@@ -204,12 +205,13 @@ def post_delete(self, instance, **kwargs):
     def create_historical_record(self, instance, history_type):
         history_date = getattr(instance, '_history_date', now())
         history_user = self.get_history_user(instance)
+        history_change_reason = getattr(instance, 'changeReason', None)
         manager = getattr(instance, self.manager_name)
         attrs = {}
         for field in instance._meta.fields:
             attrs[field.attname] = getattr(instance, field.attname)
         manager.create(history_date=history_date, history_type=history_type,
-                       history_user=history_user, **attrs)
+                       history_user=history_user, history_change_reason=history_change_reason, **attrs)
 
     def get_history_user(self, instance):
         """Get the modifying user from instance or middleware."""

simple_history/tests/migration_test_app/migrations/0001_initial.py

@@ -30,6 +30,7 @@ class Migration(migrations.Migration):
                 ('history_id', models.AutoField(serialize=False, primary_key=True)),
                 ('history_date', models.DateTimeField()),
                 ('history_type', models.CharField(choices=[('+', 'Created'), ('~', 'Changed'), ('-', 'Deleted')], max_length=1)),
+                ('history_change_reason', models.CharField(max_length=100, null=True)),
                 ('history_user', models.ForeignKey(null=True, to=settings.AUTH_USER_MODEL)),
             ],
             options={

simple_history/tests/tests/test_models.py

@@ -50,7 +50,7 @@ def assertRecordValues(self, record, klass, values_dict):
             self.assertEqual(getattr(record, key), value)
         self.assertEqual(record.history_object.__class__, klass)
         for key, value in values_dict.items():
-            if key != 'history_type':
+            if key not in ['history_type', 'history_change_reason'] :
                 self.assertEqual(getattr(record.history_object, key), value)
 
     def test_create(self):
@@ -69,37 +69,43 @@ def test_update(self):
         Poll.objects.create(question="what's up?", pub_date=today)
         p = Poll.objects.get()
         p.pub_date = tomorrow
+        p.changeReason = 'future poll'
         p.save()
         update_record, create_record = p.history.all()
         self.assertRecordValues(create_record, Poll, {
             'question': "what's up?",
             'pub_date': today,
             'id': p.id,
+            'history_change_reason': None,
             'history_type': "+"
         })
         self.assertRecordValues(update_record, Poll, {
             'question': "what's up?",
             'pub_date': tomorrow,
             'id': p.id,
+            'history_change_reason': 'future poll',
             'history_type': "~"
         })
         self.assertDatetimesEqual(update_record.history_date, datetime.now())
 
     def test_delete(self):
         p = Poll.objects.create(question="what's up?", pub_date=today)
         poll_id = p.id
+        p.changeReason = 'wrongEntry'
         p.delete()
         delete_record, create_record = Poll.history.all()
         self.assertRecordValues(create_record, Poll, {
             'question': "what's up?",
             'pub_date': today,
             'id': poll_id,
+            'history_change_reason': None,
             'history_type': "+"
         })
         self.assertRecordValues(delete_record, Poll, {
             'question': "what's up?",
             'pub_date': today,
             'id': poll_id,
+            'history_change_reason': 'wrongEntry',
             'history_type': "-"
         })