Update README and add CHANGELOG file

CHANGELOG.md

@@ -0,0 +1,94 @@
+## 1.0.0
+
+*Breaking changes* of the linter usage. The linter now is a Django management command.
+It shoud be used with a `python manage.py lintmigrations` followed by the usual options.
+Additionally, the linter now needs to be added the to the `INSTALLED_APPS` in your Django settings.
+
+* The linter is now much faster: we don't setup django once for each migration
+* The linter is now more robust: we rely on Django internals to discover migrations
+* Clean up of the testing setup: it is cleaner, less brittle and we have more confidence that it works
+
+## 0.1.5
+
+* Bug fix: handle migration files with spaces in their name by quoting the migration name
+
+## 0.1.4
+
+* Explicitly test for mysql, sqlite3 and postgresql
+* Fix alter column type detection in postgresql
+* Do not create cache folder when -no-cache option
+* Fix tests on Windows
+* Use the same Python interpreter as used for launching the linter, instead of manually trying to re-create the path
+
+## 0.1.3
+
+* Fixes migrations that are ignored to generate empty SQL, that PostgreSQL complains about. It throws an exception making migrations fail, that are in fact valid. (Thanks to @fevral13 and @mes3yd)
+* Add options -V and --version to show the current linter version
+
+## 0.1.2
+
+* Bug fix: handle when the linter is called in the working dir django-migration-linter .
+* Bug fix: don't assume that the git root is at the same path as the django project
+
+## 0.1.1
+
+* Fix caching when app is in a folder and not at the root of the project
+* Do not check for .git folder at root, because it might be located somewhere else. Let git itself do the job
+* Make some imports relative
+
+## 0.1.0
+
+The django migration linter is now set to a Beta version, instead of Alpha since it has been used for quite some time.
+
+Version 0.1.0 comes with:
+
+* Possibility to ignore migration files entirely (without specifying them on the command line)
+* This can be used by adding the migration operation IgnoreMigration() in the migrations operations list. See readme
+* Caching. We cache failed and succeeded migrations (w.r.t. migration linting) in a cache file.
+* Each migration file is stored as the MD5 hash of its content with the result of the linting
+
+Other things:
+
+* Added support for Python 3.7
+* Added support for Django 2.1
+* The codebase is now in black format to improve Python-code readability
+* 2019 ! Happy new year
+
+## 0.0.7
+
+* Minor bug fix when no errors detected
+
+## 0.0.6
+
+* Use logger correctly
+* Drop django 1.10 support
+
+## 0.0.5
+
+* Only consider added migrations during linting
+* Change readme to rst format (for PyPi)
+* Added examples folder
+* Add django (at least 1.10) as requirement for the linter
+
+## 0.0.4
+
+Assure compatibility for multiple python and django versions.
+
+* Try to improve PyPi readme
+* Better error messages
+
+## 0.0.3
+
+* Made a mistake and accidentally deleted 0.0.2 from PyPi
+
+## 0.0.2
+
+* Python 3 compatibility
+* Faster migration gathering
+
+* Code base refactoring
+* Test base refactoring
+
+## 0.0.1
+
+First version of command line tool to lint django migrations.

README.rst

@@ -31,7 +31,18 @@ Installation
 Usage
 -----
 
-``django-migration-linter DJANGO_PROJECT_FOLDER [GIT_COMMIT_ID] [--ignore-name-contains=IGNORE_NAME_CONTAINS] [--include-apps INCLUDE_APPS [INCLUDE_APPS ...] | --exclude-apps EXCLUDE_APPS [EXCLUDE_APPS ...]]``
+
+Add the migration linter your ``INSTALLED_APPS``:
+
+.. code-block::
+    INSTALLED_APPS = [
+        ...,
+        "django_migration_linter",
+        ...,
+    ]
+
+
+``python manage.py lintmigrations [GIT_COMMIT_ID] [--ignore-name-contains=IGNORE_NAME_CONTAINS] [--include-apps INCLUDE_APPS [INCLUDE_APPS ...] | --exclude-apps EXCLUDE_APPS [EXCLUDE_APPS ...]]``
 
 ================================================== ===========================================================================================================================
                    Parameter                                                                            Description
@@ -52,7 +63,8 @@ Examples
 --------
 
 3YOURMIND is running the linter on every build getting pushed through CI.
-Checkout the ``examples/`` folder to see how you could integrate the linter in your test suite.
+That enables to be sure that the migrations will allow A/B testing, Blue/Green deployment and they won't break your development environment.
+As every reasonable tool, a non-zero error code means that at least one invalid migration has been found.
 
 Backward incompatible migrations
 --------------------------------
@@ -63,9 +75,10 @@ The linter analyses your migrations and checks the SQL for:
 - Dropping columns
 - Renaming columns
 - Renaming tables
-- Altering columns (which can be backward compatible and eventually ignored)
+- Altering columns (which can be backward compatible and potentially ignored)
 
-Those are the most important and frequent backward incompatible migrations. We are happy to add more if you have some.
+Those are the most important and frequent backward incompatible migrations.
+We are happy to add more if you can specify them to us.
 
 Ignoring migrations
 -------------------
@@ -83,21 +96,35 @@ You can also ignore migrations by adding this to your migrations:
         ]
     # ...
 
+.. code-block::
+    The SQL generated by this looks like:
+    --
+    -- The Django migration linter will ignore this migration
+    --
+    select 1; -- dml ignores this migration;
+
 Cache
 -----
-By default, the linter uses a cache to prevent linting the same migration again.
+By default, the linter uses a cache to prevent linting the same migration multiple times.
 The default location of the cache on Linux is
-``/home/<username>/.cache/django-migration-linter/<version>/<ldjango-project>.pickle``.
+``/home/<username>/.cache/django-migration-linter/<version>/<ldjango-project>_<database_name>.pickle``.
 
-Since the linter uses hashes, modifying migration files, will re-run the linter on that migration.
+Since the linter uses hashes of the file's content, modifying a migration file will re-run the linter on that migration.
 If you want to run the linter without cache, use the flag ``--no-cache``.
 If you want to invalidate the cache, delete the cache folder.
+The cache folder can also be defined manually through the ``--cache-path`` option.
 
 Tests
 -----
 
 The easiest way to run the tests is to invoke `tox`_.
 
+You will need to install the test requirements, which can be found in the ``setup.py`` file.
+A good way to get started is to install the development version of the linter by doing ``pip install -e .[test]``.
+
+To be able to fully test the linter, you will need both MySQL and PostgreSQL databases running.
+You can either tweak the ``tests/test_project/settings.py`` file to get your DB settings right, or to have databases and users corresponding to the default Travis users.
+
 Contributing
 ------------