docs: a new page about migrating between versions

Added basic migraton docs changes

Remove change that likely will not require migration changes

Cannot determine what the behavior was before

Updated ** replacement suggestion

Remove extra indent at end of file

Fix linting issue that needed a trailing indent

Fix a typo in docs

Removed .gitignore corrected a single rule

Added basic migraton docs changes

Fix linting issue that needed a trailing indent

Fix a typo in docs

Correct grammar issue

Co-authored-by: Ned Batchelder <[email protected]>

Correct rule and spelling

Remove personal gitignore config

Removed duplicated license text

Added extra space

Take suggestions from ned

Co-authored-by: Ned Batchelder <[email protected]>

Author: paxnovem

doc/index.rst

@@ -234,4 +234,5 @@ More information
     trouble
     faq
     Change history <changes>
+    Migrating version notes <migrations>
     sleepy

doc/migrations.rst

@@ -0,0 +1,26 @@
+.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
+
+.. _migrations:
+
+==========================
+Migrating between versions
+==========================
+
+.. _migrating_6x_7x:
+
+Migrating 6.5.x — 7.0.x
+-----------------------
+
+- The way that wildcards when specifying file paths work in certain cases has changed in 7.0.x:
+
+  - Previously, ``*`` would incorrectly match directory separators, making
+    precise matching difficult. Patterns such as ``*tests/*``
+    will need to be changed to ``*/tests/*``.
+
+  - ``**`` now matches any number of nested directories. If you wish to retain the behavior of
+    ``**/tests/*`` in previous versions then  ``*/**/tests/*`` can be used instead.
+
+- When remapping file paths with ``[paths]``, a path will be remapped only if
+  the resulting path exists. Ensure that remapped ``[paths]`` exist when upgrading
+  as this is now being enforced.