Fixed #25259 -- Added comments to header of generated migration files

AUTHORS

@@ -713,6 +713,7 @@ answer newbie questions, and generally made Django that much better:
     tstromberg@google.com
     tt@gurgle.no
     Tyler Tarabula <tyler.tarabula@gmail.com>
+    Tyson Clugg <tyson@clugg.net>
     Tyson Tate <tyson@fallingbullets.com>
     Unai Zalakain <unai@gisa-elkartea.org>
     Valentina Mukhamedzhanova <umirra@gmail.com>

django/db/migrations/writer.py

@@ -10,6 +10,7 @@ import re
 import types
 from importlib import import_module
 
+from django import get_version
 from django.apps import apps
 from django.db import migrations, models
 from django.db.migrations.loader import MigrationLoader
@@ -21,7 +22,7 @@ from django.utils.encoding import force_text
 from django.utils.functional import Promise
 from django.utils.inspect import get_func_args
 from django.utils.module_loading import module_dir
-from django.utils.timezone import utc
+from django.utils.timezone import now, utc
 from django.utils.version import get_docs_version
 
 
@@ -211,6 +212,11 @@ class MigrationWriter(object):
         # If there's a replaces, make a string for it
         if self.migration.replaces:
             items['replaces_str'] = "\n    replaces = %s\n" % self.serialize(self.migration.replaces)[0]
+        # Hinting that goes into comment
+        items.update(
+            version=get_version(),
+            timestamp=now().strftime("%Y-%m-%d %H:%M"),
+        )
 
         if self.migration.initial:
             items['initial_str'] = "\n    initial = True\n"
@@ -526,6 +532,7 @@ class MigrationWriter(object):
 
 MIGRATION_TEMPLATE = """\
 # -*- coding: utf-8 -*-
+# Generated by Django %(version)s on %(timestamp)s
 from __future__ import unicode_literals
 
 %(imports)s

docs/howto/writing-migrations.txt

@@ -103,6 +103,7 @@ the respective field according to your needs.
     :filename: 0006_remove_uuid_null.py
 
     # -*- coding: utf-8 -*-
+    # Generated by Django A.B on YYYY-MM-DD HH:MM
     from __future__ import unicode_literals
 
     from django.db import migrations, models
@@ -156,6 +157,7 @@ the respective field according to your needs.
     :filename: 0005_populate_uuid_values.py
 
     # -*- coding: utf-8 -*-
+    # Generated by Django A.B on YYYY-MM-DD HH:MM
     from __future__ import unicode_literals
 
     from django.db import migrations, models

docs/topics/migrations.txt

@@ -449,6 +449,7 @@ the file in the right place, suggest a name, and add dependencies for you)::
 Then, open up the file; it should look something like this::
 
     # -*- coding: utf-8 -*-
+    # Generated by Django A.B on YYYY-MM-DD HH:MM
     from django.db import models, migrations
 
     class Migration(migrations.Migration):

tests/migrations/test_writer.py

@@ -12,13 +12,14 @@ import unittest
 import custom_migration_operations.more_operations
 import custom_migration_operations.operations
 
+from django import get_version
 from django.conf import settings
 from django.core.validators import EmailValidator, RegexValidator
 from django.db import migrations, models
 from django.db.migrations.writer import (
     MigrationWriter, OperationWriter, SettingsReference,
 )
-from django.test import SimpleTestCase, ignore_warnings
+from django.test import SimpleTestCase, ignore_warnings, mock
 from django.utils import datetime_safe, six
 from django.utils._os import upath
 from django.utils.deconstruct import deconstructible
@@ -525,6 +526,27 @@ class WriterTests(SimpleTestCase):
             output
         )
 
+    def test_migration_file_header_comments(self):
+        """
+        Test comments at top of file.
+        """
+        migration = type(str("Migration"), (migrations.Migration,), {
+            "operations": []
+        })
+        dt = datetime.datetime(2015, 7, 31, 4, 40, 0, 0, tzinfo=utc)
+        with mock.patch('django.db.migrations.writer.now', lambda: dt):
+            writer = MigrationWriter(migration)
+            output = writer.as_string().decode('utf-8')
+
+        self.assertTrue(
+            output.startswith(
+                "# -*- coding: utf-8 -*-\n"
+                "# Generated by Django %(version)s on 2015-07-31 04:40\n" % {
+                    'version': get_version(),
+                }
+            )
+        )
+
     def test_models_import_omitted(self):
         """
         django.db.models shouldn't be imported if unused.