Restore common_issues docs entry

Author: dolfinus

docs/common_issues/all_dirty.rst

@@ -0,0 +1,24 @@
+.. _all-dirty-issue:
+
+Every version built by CI is ``dirty``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is usually caused by some files created by CI pipeline like build
+artifacts or test reports, e.g. ``dist/my_package.whl`` or
+``reports/unit.xml``. If these files are not mentioned in ``.gitignore`` file
+they will be recognized by git as untracked. Because of that
+``git status`` will report that you have **uncommitted (dirty) changes** in
+the index, so ``setuptools-git-versioning`` will detect current version
+as ``dirty``.
+
+You should such files to the ``.gitignore`` file. In most the cases adding these lines solves the issue:
+
+.. code:: gitignore
+
+    build/
+    dist/
+    eggs/
+    *.egg*
+    venv
+
+See `full example <https://github.com/dolfinus/setuptools-git-versioning/blob/master/.gitignore>`_.

docs/common_issues/index.rst

@@ -0,0 +1,8 @@
+Common issues
+--------------
+
+.. toctree::
+    :maxdepth: 1
+
+    all_dirty
+    wrong_tag

docs/common_issues/wrong_tag.rst

@@ -0,0 +1,23 @@
+.. _wrong-tag-issue:
+
+Wrong tag ordering/latest tag number detection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This could be caused by some unusual way of creating tags in your repo.
+
+Annotated tags
+^^^^^^^^^^^^^^
+
+If you're using annotated tags in your git repo, please avoid creating them in non-chronological order.
+This can cause issues with detecting versions of existing commits.
+
+Multiple tags on commit
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Please do not add multiple tags for the same commit.
+It is impossible to automatically determine which one is latest because of ambiguity -
+both tag and commit have a creation date, and it is not possible to sort tags by multiple columns.
+
+See also
+^^^^^^^^
+- :ref:`sort-by-option` option